Mindfire.Xamarin 1.5.1

Mindfire.Xamarin

This package is used to provide a better separation between a view and view model in Xamarin. Using this pattern will prevent your view from containing any knowledge about what view model is bound to it, and prevent the view model from knowing which view is presented. It provides a programmatic way of navigating both with routes and with the traditional NavigationPage style of navigation.

Usage

There are two different scenarios in which this library can be used. Navigation while using the new Shell, and navigation using the traditional NavigationPage navigation style.

The data-binding is handled via convention similar to Caliburn's convention. For a given page, the view model must be either in the same namespace or adjacent to the namespace where Page or View has been switched for ViewModel. For example, if a view's namespace is MyApp.Pages.Items.ItemsPage, then the view model must be found in one of: MyApp.Pages.Items.ItemsPageModel, MyApp.Pages.Items.ItemsViewModel, MyApp.ViewModels.Items.ItemsPageModel, MyApp.ViewModels.Items.ItemViewModel.

The IBinder interface also provides a Map method that allows users to specifically indicate that a page should be bound with a view model. It would be used by specifying IBinder.Map<MyApp.Pages.Items.ItemsPage, MyApp.ViewModels.Items.ItemViewModel> where the namespaces would normally not fit within the conventions. This allows developers to use the same view model for multiple views (or vice-versa).

Shell Navigation

To use Shell, simply create a Shell as your main page. You can setup the shell to behave exactly as you wish -- Mindfire.Xamarin does not interfere or require a specific setup here. In the App.xaml.cs file, wire up your dependency container as you normally would. Add to it a registration for both IBinder and IRouteNavigator. You may provide your own implementations of these interfaces, or use the provided types. The IBinder implementation is SimpleBinder and it requires either an implementation of IServiceProvider, or two funcs for retrieving services from the dependency container. IRouteNavigator is fulfilled by ShellNavigator.

services.AddSingleton<IBinder>(provider => new SimpleBinder(type => provider.GetService(type), type => provider.GetServices(type)));
services.AddSingleton<IRouteNavigator>(provider =>
{
  var binder = provider.GetService<IBinder>();
  return new ShellNavigator(MainPage as Shell, binder);
}
// You may also provide an registration for INavigator in case you have a need to abstract the routing portion.
services.AddSingleton<INavigator>(provider => provider.GetService<IRouteNavigator>());

Once registered, simply make sure that an instance of INavigator or IRouteNavigator is created when your app starts. This is needed to allow the system to wire up the pages.

You may register routes both inside the Shell, as well as programmatically using the Routing class. You may then request the IRouteNavigator or INavigator interfaces as injection parameters to your ViewModels and use them to navigate.

Traditional Navigation

If you are not using Shell and would like to use the more traditional form of navigation, you need to register both the IBinder and INavigator interfaces. You may use your own, or use the provided implementations. As above, SimpleBinder works for the IBinder interface, and ClassicNavigator works for the INavigator interface.

services.AddSingleton<IBinder>(provider => new SimpleBinder(provider));
services.AddSingleton<INavigator>(provider => new ClassicNavigator(MainPage as NavigationPage, provider.GetService<IBinder>()));

As with the shell navigation, you must ensure that an instance of INavigator is created upon startup of your application to allow the system to wire up the pages. You may then request an INavigator instance inside your view models and navigate as you normally would.

INavigator API

• Task NavigateTo<T>()
  • Pushes the desired page onto the stack. Creation of the page is handled automatically, as is binding to the appropriate view model.
• Task NavigateTo<TPage, TData>(TData data)
  • Is identical to the above method, however this allows you to pass data to the view model of the next page. The view model must have a property of type TData, and it will automatically be assigned the passed in value data.
• Task NavigateToModal<T>()
  • Pushes the desired page onto the modal stack and shows the page as a modal dialog.
• Task NavigateToModal<TPage, TData>(TData data)
  • Is identical to the above method, except allowing you to pass data to the view model of the modal dialog. The view model must have a property of type TData that can be assigned the passed in value data.
• Task NavigateToRoot()
  • Navigates back to the Root of the navigation stack. This is the Shell for shell navigation scenarios, and the RootPage for NavigationPage scenarios.
• Task GoBack()
  • Pops a page off of the stack. If there are pages on the ModalStack, these are popped before any other pages.
  • For Shell navigation, if there are pages on the NavigationStack, these are popped first. If there are none, this call is equivalent to Shell.GoToAsync("..")
• Task<string> DisplayActionSheet(string title, string cancel, string destruction, params string[] buttons)
  • Displays an action sheet and returns the value selected by the user
• Task DisplayAlert(string title, string message, string cancel), Task<bool> DisplayAlert(string title, string message, string cancel, string accept)
  • Displays an alert. For the second version true will be returned if the accept button is selected, otherwise false.
• Task<string> DisplayPrompt(string title, string message, string accept, string cancel, string placeholder, int maxLength, Keyboard keyboard, string initialValue)
  • Displays a prompt window and returns the input value
• Task InsertPageBefore<TReference, TPage>(), Task InsertPageBefore<TPage>(Page reference)
  • Inserts a page before the reference page. The version with 2 generic types will lookup and find the first page of type TReference on the navigation stack.
• Task RemovePage<TPage>(), Task RemovePage(Page page)
  • Removes a page from the navigation stack. The generic version will find the first page of type TPage and remove that.
• Task<Page> LookupView(object viewModel)
  • Will find the first page where viewModel is set as the binding context and return that page.
• Task PopToRootThenNavigateTo<T>()
  • Pop the view stack back to the root, then navigate to page T
• Task PopToThenNavigateTo<TExisting, TNew>()
  • Pops the stack back to the first instance of type TExisting (or root), then navigates to TNew

IBinder API

• void Bind(Page page)
  • Binds the view model to the page
• Page Bind<T>() where T : Page
  • Binds the view model to a page that is created. Returns the created page
• void Map<TPage, TViewModel>() where TPage : Page
  • Specifies a relationship between the page and view model that will be used when binding a page