From f253ab44a940202f7831222f738f860d4d03a23c Mon Sep 17 00:00:00 2001 From: Shaun Lawrence <17139988+bijington@users.noreply.github.com> Date: Thu, 2 Nov 2023 19:39:35 +0000 Subject: [PATCH] Add in a section to cover the PopupService --- .../servicecollection-extensions.md | 47 ++++++++++++++ docs/maui/views/popup.md | 64 ++++++++++++++++++- 2 files changed, 109 insertions(+), 2 deletions(-) diff --git a/docs/maui/extensions/servicecollection-extensions.md b/docs/maui/extensions/servicecollection-extensions.md index c0d14b69..22ff0185 100644 --- a/docs/maui/extensions/servicecollection-extensions.md +++ b/docs/maui/extensions/servicecollection-extensions.md @@ -311,6 +311,53 @@ The `RouteFactory` to control View construction. [IServiceCollection](/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) A reference to this instance after the operation has completed. +## Register Popup View and View Model + +The following methods allow you to register Popup based Views and ViewModels within the .NET MAUI `IServiceCollection`. + +### AddTransientPopup(IServiceCollection) + +Adds a transient View of the type specified in TPopupView and ViewModel of the type TPopupViewModel to the specified IServiceCollection. + +```csharp +using CommunityToolkit.Maui; + +namespace CommunityToolkit.Maui.Sample; + +public static class MauiProgram +{ + public static MauiApp CreateMauiApp() + { + var builder = MauiApp.CreateBuilder() + .UseMauiCommunityToolkit() + .UseMauiApp(); + + builder.Services.AddTransientPopup(); + } +} +``` + +#### Type Parameters + +##### TView + +The type of the View to add. Constrained to `Popup` + +##### TViewModel + +The type of the ViewModel to add. Constrained to reference types implementing `INotifyPropertyChanged` + +#### Parameters + +##### `services` [IServiceCollection](/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) + +The [IServiceCollection](/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) to add the View and ViewModel to. + +#### Returns + +[IServiceCollection](/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) +A reference to this instance after the operation has completed. + ## API You can find the source code for `ServiceCollectionExtensions` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui/Extensions/ServiceCollectionExtensions.shared.cs). diff --git a/docs/maui/views/popup.md b/docs/maui/views/popup.md index 6f9843bb..3ead29a7 100644 --- a/docs/maui/views/popup.md +++ b/docs/maui/views/popup.md @@ -78,7 +78,67 @@ var popup = new Popup ## Presenting a Popup -Once the `Popup` has been built it can then be presented through the use of our `Popup` extension methods. +Once the `Popup` has been built it can then be presented through the use of our `Popup` extension methods or through the `IPopupService` implementation from this toolkit. + +### IPopupService + +The .NET MAUI Community Toolkit provides a mechanism to instantiate and present popups in a .NET MAUI application. The popup service is automatically registered with the `MauiAppBuilder` when using the `UseMauiCommunityToolkit` initialization method. This enables you to resolve an `IPopupService` implementation in any part of your application. + +The `IPopupService` makes it possible to register a popup view and its associated view model. The ability to show a `Popup` can now be driven by only providing the view model making it possible to keep a clean separation between view and view model. + +#### Registering Popups + +In order to first use the `IPopupService` to display a popup in your application you will need to register the popup and view model with the `MauiAppBuilder`, this can be done through the use of [Register Popup View and View Model](../extensions/servicecollection-extensions.md#register-popup-view-and-view-model). + +#### Displaying Popups + +The following example shows how to use the `IPopupService` to create and display a popup in a .NET MAUI application: + +```csharp +public class MyViewModel : INotifyPropertyChanged +{ + private readonly IPopupService popupService; + + public MyViewModel(IPopupService popupService) + { + this.popupService = popupService; + } + + public void DisplayPopup() + { + this.popupService.ShowPopup(); + } +} +``` + +For a more concrete example please refer to our sample application and the example in [`MultiplePopupViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs) + +The `IPopupService` also provides methods to handle a result being returned from a Popup as covered in [Returning a result](./popup.md#returning-a-result). + +#### Passing data to a Popup view model + +When presenting a Popup we sometimes need to pass data across to the underlying view model to allow for dynamic content to be presented to the user. The `IPopupService` makes this possible through the overloads of the `ShowPopup` and `ShowPopupAsync` methods that takes a `Action onPresenting` parameter. This parameter has been designed to be framework agnostic and allow you as a developer to drive the loading/passing of data however best fits your architecture. + +To extend the previous example of showing a `UpdatingPopupViewModel` and its associated Popup, we can use the `onPresenting` parameter to pass in the number of updates that we wish to perform: + +```csharp +public class MyViewModel : INotifyPropertyChanged +{ + private readonly IPopupService popupService; + + public MyViewModel(IPopupService popupService) + { + this.popupService = popupService; + } + + public void DisplayPopup() + { + this.popupService.ShowPopup(onPresenting: viewModel => viewModel.PerformUpdates(10)); + } +} +``` + +### Extension methods > [!IMPORTANT] > A `Popup` can only be displayed from a `Page` or an implementation inheriting from `Page`. @@ -124,7 +184,7 @@ If we enhance the previous XAML example by adding an ok `Button`: In the resulting event handler we call `Close`, this will programmatically close the `Popup`. -> [!NOTE] +> [!NOTE] > `Close()` is a fire-and-forget method. It will complete and return to the calling thread before the operating system has dismissed the `Popup` from the screen. If you need to pause the execution of your code until the operating system has dismissed the `Popup` from the screen, use instead `CloseAsync()`. ```csharp