MPowerKit.Regions 1.1.5

MPowerKit .NET MAUI MVVM navigation framework.

Supports regular/modal navigation, opening/closing windows, multiple windows, regions, popups

Available Nugets

Framework	Nuget
MPowerKit.Navigation.Core
MPowerKit.Navigation
MPowerKit.Navigation.Popups
MPowerKit.Navigation.Regions

MPowerKit.Navigation.Core

WIP

MPowerKit.Navigation

WIP

MPowerKit.Navigation.Popups

This library based on MPowerKit.Navigation and MPowerKit.Popups libraries

Setup

Add UsePopupNavigation() to MPowerKitBuilder in your MauiProgram.cs file as next

builder
    .UseMauiApp<App>()
    .UseMPowerKitNavigation(mpowerBuilder =>
    {
        mpowerBuilder.ConfigureServices(s =>
        {
            s.RegisterForNavigation<MainPage>();
            s.RegisterForNavigation<TestPopupPage>();
        })
        .UsePopupNavigation()
        .OnAppStart("NavigationPage/MainPage");
    });

When you specify .UsePopupNavigation() it registers MPowerKitPopupsWindow as main class for every window, it is responsible for system back button. It inherits MPowerKitWindow which is main class for window in MPowerKit.Navigation, it also responsible for system back button on every platform, even in mac and ios (top-left back button on the page's toolbar)

Register your popup pages

mpowerBuilder.ConfigureServices(s =>
{
    s.RegisterForNavigation<TestPopupPage>();
})

• The popup will be resolved by it's string name
• No view model is specified, which means it has BindingContext set to new object();

or

mpowerBuilder.ConfigureServices(s =>
{
    s.RegisterForNavigation<TestPopupPage, TestPopupViewModel>();
})

• The popup will be resolved by it's string name
• The view model is TestPopupViewModel

or

mpowerBuilder.ConfigureServices(s =>
{
    s.RegisterForNavigation<TestPopupPage, TestPopupViewModel>("TheAssociationNameForYourPopup");
})

• The popup will be resolved by association name, which is preferred way
• The view model is TestPopupViewModel

Usage

Each popup page should inherit from PopupPage of MPowerKit.Popups library

IPopupDialogAware

To have full control over the popup flow it is better that your popup or popup's viewmodel implement this interface. This interface gives you an ability to close popup programmatically from popup or it's viewmodel. IPopupDialogAware interface provides only one property RequestClose. It is an Action. You should call it when you want to close the popup. It accepts a tuple with Confirmation object and a boolean whether animated or not. The value for RequestClose property is set under the hood by the framework, so you don't need to do smth extra with it.

Confirmation is a record which accepts 2 parameters:

1. Boolean whether confirmed or not;
2. INavigationParameters to pass the parameters back from popup to popup caller (it is optional).

Example

public class TestPopupViewModel : IPopupDialogAware
{
    public Action<(Confirmation Confirmation, bool Animated)> RequestClose { get; set; }

    protected virtual async Task Cancel(object obj = null)
    {
        var nparams = new NavigationParameters
        {
            { NavigationConstants.CloseParameter, obj }
        };

        RequestClose?.Invoke((new Confirmation(false, nparams), true));
    }

    protected virtual async Task Confirm(object obj = null)
    {
        var nparams = new NavigationParameters
        {
            { NavigationConstants.CloseParameter, obj }
        };

        RequestClose?.Invoke((new Confirmation(true, nparams), true));
    }
}

IPopupNavigationService

Main unit of work of this library is IPopupNavigationService. Under the hood it is registered as scoped service (NOT SINGLETONE), which means that it knows from which page it was opened to know the parent window it is attached to. So, in theory you can open different popups in different windows in same time.

Inject IPopupNavigationService to your page's or viewmodel's contructor.

IPopupNavigationService describes 4 methods:

Show 'fire-and-forget' popup:

ValueTask<NavigationResult> ShowPopupAsync(string popupName, INavigationParameters? parameters = null, bool animated = true, Action<Confirmation>? closeAction = null);

When you invoke this method it will show the popup and the main thread will continue doing it's very important work. You can provide close callback which accepts Confirmation object with boolean whether confirmed or not and INavigationParameters parameters. it invokes all necessary aware interfaces you specified for your popup or it's viewmodel. The result of showing popup is NavigationResult

Show awaitable popup:

ValueTask<PopupResult> ShowAwaitablePopupAsync(string popupName, INavigationParameters? parameters = null, bool animated = true);

When you invoke this method it will show the popup and it will await until the popup is closed. The reslut of this method is PopupResult. PopupResult is inherited from NavigationResult. It has extra property for Confirmation object to know how the popup was closed.

Hide the last popup from popup stack:

ValueTask<NavigationResult> HidePopupAsync(bool animated = true);

Hides the last popup available in the popup stack. The stack is controlled by the MPowerKit.Popups framework.

Hide specific popup:

ValueTask<NavigationResult> HidePopupAsync(PopupPage page, bool animated = true);

Hides the specified popup if it was opened. The difference with MPowerKit.Popups that it invokes all necessary aware interfaces you specified for your popup or it's viewmodel.

MPowerKit.Navigation.Regions

Like MPowerKit.Navigation Regions library is very similar to Prism's. It has same sense, but different implementation.

Shortly what it is: In MAUI you can navigate only through pages, but what if you need to have big page with few different sections, let's call them, regions. For example: TabView or some desktop screen with sections. Do we need to keep all logic in one viewmodel? - With regions no. It gives you simple and flexible way to navigate to the regions (sections on UI) from your page or viewmodel, or even from another region.

Setup

Add UseMPowerKitRegions() to your MauiProgram.cs file as next

builder
    .UseMauiApp<App>()
    .UseMPowerKitRegions();

Regions can work with(out) MPowerKit.Navigation or MPowerKit.Navigation.Popups.

builder
    .UseMauiApp<App>()
    .UseMPowerKitNavigation(mpowerBuilder =>
    {
        mpowerBuilder.ConfigureServices(s =>
        {
            s.RegisterForNavigation<MainPage>();
            s.RegisterForNavigation<RegionView1>();
        })
        .OnAppStart("NavigationPage/MainPage");
    })
    .UseMPowerKitRegions();

Note: if you are using regions in couple with MPowerKit.Navigation you can specify whether you want your region views get parent page's events like navigation, destroy, lifecycle etc. Just add UsePageEventsInRegions() to mpowerBuilder

builder
    .UseMauiApp<App>()
    .UseMPowerKitNavigation(mpowerBuilder =>
    {
        mpowerBuilder.ConfigureServices(s =>
        {
            s.RegisterForNavigation<MainPage>();
            s.RegisterForNavigation<RegionView1>();
        })
        .UsePageEventsInRegions()
        .OnAppStart("NavigationPage/MainPage");
    })
    .UseMPowerKitRegions();

Register your region views

builder.Services
    .RegisterForNavigation<RegionView1>();

• The region view will be resolved by it's string name
• No view model is specified, which means it has BindingContext set to new object();

or

builder.Services
    .RegisterForNavigation<RegionView1, Region1ViewModel>();

• The region view will be resolved by it's string name
• The view model is Region1ViewModel

or

builder.Services
    .RegisterForNavigation<RegionView1, Region1ViewModel>("RegionViewAssociationName");

• The region view will be resolved by association name, which is preferred way
• The view model is Region1ViewModel

Usage

Each region should have the parent container which will be the so-called region holder. This region holder has to be typeof(ContentView).

In your xaml:

add namespace

xmlns:regions="clr-namespace:MPowerKit.Regions;assembly=MPowerKit.Regions"

and then

<ContentView regions:RegionManager.RegionName="YourVeryMeaningfulRegionName" />

or, unlike Prism, it can have dynamic name, for example if you need to bind it to some ID.

<ContentView regions:RegionManager.RegionName="{Binding DynamicString}" />

This is very helpful if you use it, for example, with TabView and you need to open new tab with tab specific dynamic data which has region(s). With static names you are not able to do such trick.

!!! Important: the region names have to be unique through entire app or it will crash.

IRegionManager

This interface has 2 methods:

1. NavigationResult NavigateTo(string regionName, string viewName, INavigationParameters? parameters = null); It does navigation to empty region holder, creates IRegion object which describes the region with region stack and pushes chosen view to the region. Or if the region holder contains any child view it will clear region stack and push new view to the region.
2. IEnumerable<IRegion> GetRegions(VisualElement? regionHolder); Get all child regions for chosen region holder. It can be useful if you need to clean all resources and invoke lificycle events for regions.

Then from your view or viewmodel:

<ContentView regions:RegionManager.RegionName="{Binding DynamicString}" />

To remove region holder from region registrations there is hidden method

RegionManager.RemoveHolder(string? key)