Regions in Prism for Xamarin.Forms

Prism has long been considered the premiere choice of frameworks for developing Xamarin.Forms applications with about 1.5 million downloads of just the Prism.Forms NuGet package alone! Why has Prism been the gold standard for app development? For starters Prism originated around 2008 from the Microsoft Patterns and Practices team for WPF development. Prism was never about basic MVVM helpers like providing a base implementation of INotifyPropertyChanged and ICommand, with perhaps a ViewModelLocator thrown in for good measure. Sure Prism has all of these things but Prism has always been about giving you the tools you need to actually develop your app which includes an understanding of the platform you're working with to give you the ability to Navigate. This is a key feature that makes Prism an actual MVVM Framework for building Highly Modular, Highly Testable XAML applications rather than just a set of MVVM Helpers like MvvmLight or the new Microsoft.Toolkit.Mvvm.

Recently Prism celebrated a huge leap forward for its Xamarin.Forms developers with the introduction of support for Region Navigation. Regions has long been the preferred method of application development for WPF development and was adopted as the preferred method of app development for Uno Platform apps.

What is a Region

Before we can really start to understand what exactly a Region is, let's define a few terms:

• Page - This is a Xamarin.Forms concept which generally encompasses the entire device screen for platforms like iOS/Android or a traditional application window on platforms like UWP/macOS
• View (Xamarin.Forms) - This is a Visual Element from Xamarin.Forms that is generally added as the content of a Xamarin.Forms ContentPage. Developers coming from other backgrounds may often think of these as Controls and Layouts. Examples include the Label, Button, StackLayout, and Grid.
• Composite Control - This is generally a Xamarin.Forms Layout such as a StackLayout, Grid, ContentView, or other layout which contains various children. This may be very simple or as complex as anything else you may typically do on the Page.
• View (MVVM) - This is a Visual Element presented by the Application that is bound to a ViewModel. The View could represent the entire visible area to the User or a subsection of the total visible area within the device screen or application window.

For the purposes of this article, and to avoid confusion note that when we use the term View we are referring to the MVVM context of what a View is. When we say control we are referring to the Xamarin.Forms context of what a View is, and when we say Page we are referring again to the Xamarin.Forms context of what a Page is.

So what is a Region? A Region within Prism.Forms is generally a Composite Control. If you're coming from the context of traditional Prism.Forms Page based app design just think whatever you had on the Page but a small section that may need to change or be reused across various Pages.

How do I use Regions in Prism for Xamarin.Forms

While we don't want to get into the specifics for how to add support for additional controls, it is important to understand that support for controls used in your Xamarin apps is provided by mapping a RegionAdapter to a control type that you need to support. Out of the box Prism includes support for:

These out of the box adapters do not require any mapping. So what do you need to do? For starters let's create a View that we'll call RegionViewA

    <StackLayout xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="HelloRegions.Views.RegionViewA">
  <Label Text="Region View A" />
  <Label Text="{Binding Message}" />
</StackLayout>
  

Now that we have a View that we will display in our Region lets create a Page to host our Region, we will call the Page ViewA.

    <ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:prism="http://prismlibrary.com"
             x:Class="HelloRegions.Views.ViewA">
  <ContentView prism:RegionManager.RegionName="ContentRegion" />
</ContentPage>
  

Now that we have our two Views lets head over to our App and register these for Navigation. We will also need to make sure that our App is ready to use Regions and navigate to our initial Page so that the Application.MainPage is set to our Page (ViewA).

    public partial class App : PrismApplication
{
    protected override void OnInitialized()
    {
        InitializeComponent();
        NavigationService.NavigateAsync("ViewA?message=Hello%20Region%20From%20PrismApplication!");
    }

    protected override void RegisterTypes()
    {
        containerRegistry.RegisterRegionServices();
        containerRegistry.RegisterForNavigation<ViewA, ViewAViewModel>();
        containerRegistry.RegisterForRegionNavigation<RegionViewA, RegionViewAViewModel>();
    }
}
  

Now we could run our app but we really wouldn't see anything as we haven't done anything to load RegionViewA into our ContentRegion in ViewA. So next we'll need to look at how we can do that in our ViewAViewModel.

    public class ViewAViewModel : BindableBase, IInitialize
{
    private IRegionManager _regionManager { get; }

    public ViewAViewModel(IRegionManager regionManager)
    {
        _regionManager = regionManager;
    }

    public void Initialize(INavigationParameters parameters)
    {
        _regionManager.RequestNavigate("ContentRegion", "RegionViewA", RegionNavigationCallback);
    }

    private void RegionNavigationCallback(IRegionNavigationResult result)
    {
        // Handle any errors or anything else you need to here...
    }
}
  

Now you may have noticed that we had a binding for a Message property in our RegionViewA, and we passed a message in our querystring when we navigated to ViewA but so far we haven't done anything with that. So let's look at how we can pass parameters to our Region now:

    public void Initialize(INavigationParameters parameters)
{
    _regionManager.RequestNavigate("ContentRegion", "RegionViewA", RegionNavigationCallback, parameters);
}
  

It really couldn't be easier to use. Prism 8.0 and Regions for Prism.Forms are out of preview. Need help with your Prism application? Be sure to contact us today about our Enterprise Support contracts or for other help getting your projects ready to use Regions.