Navigation Service

Navigation Service

Xalami's Navigation Service centralizes two mechanisms: navigation between pages, and passing parameters between pages. Broadly speaking, it is an abstraction over Xamarin's NavigationPage, so its navigation semantics will be identical to those of the NavigationPage.

Getting Started

In order to create a Xalami Navigation Service, first you need a NavigationHost object. The NavigationHost is the object that wraps the Xamarin NavigationPage, and provides several helper methods.

The Navigation Service allows for navigation via ViewModel, but in order to work, the ViewModels must be associated with a Page. In order to make this association, Configure() must be called on the NavigationService object with the ViewModel type and the Page type.

Altogether, getting a basic Navigation Service up and running looks something like this:

 NavigationHost navigationHost = new NavigationHost();
 NavigationService navService = new NavigationService(navigationHost)
    .Configure(typeof(MainViewModel), typeof(MainPage); // supposing you have a MainViewModel and and MainPage type somewhere...

By default, this is done for you in the provided ViewModelLocator.cs.

ViewModel Lifecycles

By default, the Navigation Service triggers overrideable Activated() and Deactivated() methods on any ViewModel that implements INavigable. Xalami provides a NavigableViewModelBase that provides virtual Activated() and virtual Deactivated() methods for just this purpose. When navigated to, the ViewModel's Activated() method will be called. When navigated away from, Deactivated() will be called.

The Activated() method includes a navigationType argument that indicates whether or not this activation is the result of navigating Forward or Back.

Note that Activated() and Deactivated() both return a Task. If you do not mark your overrides of these methods as async and make at least one await call within them, the compiler will give you an error or warning respectively. In order to avoid that, you can just return or await a LocalTaskExtensions.CompletedTask.

Parameter Passing

Xalami's Navigation Service allows you to pass parameters between Pages (and, with a little bit of extra work, ViewModels). To do so, call one of the NavigateToPageAsync() or NavigateToViewModelAsync() overloads that include a "parameter" argument.

In order to receive this parameter, your navigation target must be or be associated with a Page that contains a constructor with exactly one parameter of the type being passed.

If you wish the pass this parameter on to your ViewModel, the page is responsible for that. Xalami's NavigableViewModelBase includes a mechanism for doing that just that--a property of type object named Parameter. In your Page's constructor, obtain a reference to your ViewModel, and set its Parameter property to the parameter you've just received.

A full example of a passed parameter might look like this:

The Passer, MainViewModel.cs:

MyCustomType myType = new MyCustomType("some arguments");
await _navigationService.NavigateToViewModelAsync<SettingsViewModel>(myType);

SettingsViewModel's associated Page, SettingsPage.cs:

public SettingsPage(MyCustomType myType)
{
    var settingsViewModel = ServiceLocator.Current.GetInstance<SettingsViewModel>();
    settingsViewModel.Parameter = myType;
    InitializeComponent();
}

The Receiving ViewModel, SettingsViewModel.cs:

private MyType _cachedMyType;

public override Activated(NavigationType navType)
{
    _cachedMyType = (MyType)Parameter;
}