🆕 feat(PopupService): Add the advance usage to open custom popup comp…

…onent (#1048) * 🆕 feat(PopupService): Add the advance usage * 📝 docs: missing diff about error-handler * 📝 docs: Update nav.json
masastack · Mar 3, 2023 · 2f66644 · 2f66644
1 parent 550def8
commit 2f66644
Show file tree

Hide file tree

Showing 13 changed files with 171 additions and 44 deletions.
diff --git a/docs/Masa.Blazor.Docs/Examples/components/popup-service/Advance.razor b/docs/Masa.Blazor.Docs/Examples/components/popup-service/Advance.razor
@@ -0,0 +1,21 @@
+@inject IPopupService PopupService
+
+<MButton OnClick="OnClick" Class="text-capitalize">Open the CustomPopupComponent</MButton>
+
+@code {
+
+    private async Task OnClick()
+    {
+        await OpenCustomPopupAsync("content here", AlertTypes.Info);
+    }
+
+    private async Task OpenCustomPopupAsync(string content, AlertTypes type)
+    {
+        await PopupService.OpenAsync(typeof(CustomPopupComponent), new Dictionary<string, object?>()
+        {
+            { nameof(CustomPopupComponent.Content), content },
+            { nameof(CustomPopupComponent.Type), type }
+        });
+    }
+
+}
diff --git a/docs/Masa.Blazor.Docs/Examples/components/popup-service/CustomPopupComponent.razor b/docs/Masa.Blazor.Docs/Examples/components/popup-service/CustomPopupComponent.razor
@@ -0,0 +1,22 @@
+@inherits Masa.Blazor.Popup.Components.PopupComponentBase
+
+<MDialog Value="Visible" MaxWidth="360">
+    <MAlert Class="mb-0" Type="@Type" Dismissible Value="Visible" ValueChanged="ValueChanged">@Content</MAlert>
+</MDialog>
+
+@code {
+
+    [Parameter, EditorRequired]
+    public string? Content { get; set; }
+
+    [Parameter]
+    public AlertTypes Type { get; set; }
+
+    private async Task ValueChanged(bool val)
+    {
+        Visible = val;
+
+        await ClosePopupAsync();
+    }
+
+}
diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/nav.json b/docs/Masa.Blazor.Docs/wwwroot/data/nav.json
@@ -82,7 +82,7 @@
       "borders",
       {
         "title": "bottom-navigation",
-        "state": "new"
+        "state": "update"
       },
       "bottom-sheets",
       "breadcrumbs",
@@ -92,7 +92,10 @@
       "chips",
       "copyable-text",
       "cron",
-      "defaults-providers",
+      {
+        "title": "defaults-providers",
+        "state": "new"
+      },
       "dialogs",
       "dividers",
       "drag-zone",
@@ -102,9 +105,14 @@
         "state": "update"
       },
       "editors",
-      "ellipsis-texts",
-      "enqueued-snackbars",
-      "error-handler",
+      {
+        "title": "enqueued-snackbars",
+        "state": "new"
+      },
+      {
+        "title": "error-handler",
+        "state": "update"
+      },
       "expansion-panels",
       "floating-action-buttons",
       "footers",
@@ -195,7 +203,10 @@
           "time-pickers"
         ]
       },
-      "popup-service",
+      {
+        "title": "popup-service",
+        "state": "update"
+      },
       {
         "title": "progress",
         "group": "components",

diff --git a/docs/Masa.Blazor.Docs/wwwroot/pages/components/popup-service/en-US.md b/docs/Masa.Blazor.Docs/wwwroot/pages/components/popup-service/en-US.md
@@ -89,3 +89,40 @@ services.AddMasaBlazor(options =>
     };
 })
 ```
+
+## Advance
+
+You can use open your own popup component using `IPopupSerivce.OpenAsync`.
+Here are some necessary steps:
+
+1. Your own popup component should inherit from the **PopupComponentBase** which is in the **Masa.Blazor.Popup.Components** namespace.
+2. Use the `Visible` property inherited from **PopupComponentBase** to control whether your component opens or closes.
+3. When you close the popup component, the `ClosePopupAsync` method inherited from **PopupComponentBase** should be called. The `returnVal` parameter in the `ClosePopupAsync` method will be the return value of `IPopupService.OpenAsync`.
+4. (optional) There is also a `PopupOkEventArgs` class that helps you leave the power to close the popup component to the user. For details, check the source code for [Confirm component](https://github.com/BlazorComponent/MASA.Blazor/blob/main/src/Masa.Blazor/Popup/Components/Confirm/Confirm.razor.cs#L69).
+
+Here is a simple popup component named **CustomPopupComponent** that encapsulates the **MDialog** and **MAlert** components:
+
+```razor
+@inherits Masa.Blazor.Popup.Components.PopupComponentBase
+
+<MDialog Value="Visible" MaxWidth="360">
+    <MAlert Class="mb-0" Type="@Type" Dismissible Value="Visible" ValueChanged="ValueChanged">@Content</MAlert>
+</MDialog>
+
+@code {
+    [Parameter, EditorRequired]
+    public string? Content { get; set; }
+
+    [Parameter]
+    public AlertTypes Type { get; set; }
+
+    private async Task ValueChanged(bool val)
+    {
+        Visible = val;
+
+        await ClosePopupAsync();
+    }
+}
+```
+
+<masa-example file="Examples.components.popup_service.Advance"></masa-example>
diff --git a/docs/Masa.Blazor.Docs/wwwroot/pages/components/popup-service/zh-CN.md b/docs/Masa.Blazor.Docs/wwwroot/pages/components/popup-service/zh-CN.md
@@ -87,3 +87,40 @@ services.AddMasaBlazor(options =>
     };
 })
 ```
+
+## 进阶用法
+
+你可以使用 `IPopupService.OpenAsync` 打开你自己的组件。
+这里有一些必要的步骤：
+
+1. 你自己的弹出组件应该继承自 **PopupComponentBase**，它在 **Masa.Blazor.Popup.Components** 命名空间下。
+2. 使用继承自 **PopupComponentBase** 的 `Visible` 属性来控制你的组件显示和关闭。
+3. 当你关闭你的弹出组件时，需要调用 继承自 **PopupComponentBase** 的 `ClosePopupAsync` 方法。 这个方法的 `returnVal` 入参将会作为 `IPopupService.OpenAsync` 的返回值。
+4. （可选）还有一个 `PopupOkEventArgs` 类，能帮你把关闭组件的权力留给用户。具体用法请查看 [Confirm 组件](https://github.com/BlazorComponent/MASA.Blazor/blob/cc2e3178db40c0d6bacbe9b66f8e371afbe4cba2/src/Masa.Blazor/Popup/Components/Confirm/Confirm.razor.cs#L69) 的源码。
+
+下面是一个简单的弹出组件：**CustomPopupComponent**，它封装了 **MDialog** 和 **MAlert**组件：
+
+```razor
+@inherits Masa.Blazor.Popup.Components.PopupComponentBase
+
+<MDialog Value="Visible" MaxWidth="360">
+    <MAlert Class="mb-0" Type="@Type" Dismissible Value="Visible" ValueChanged="ValueChanged">@Content</MAlert>
+</MDialog>
+
+@code {
+    [Parameter, EditorRequired]
+    public string? Content { get; set; }
+
+    [Parameter]
+    public AlertTypes Type { get; set; }
+
+    private async Task ValueChanged(bool val)
+    {
+        Visible = val;
+
+        await ClosePopupAsync();
+    }
+}
+```
+
+<masa-example file="Examples.components.popup_service.Advance"></masa-example>
diff --git a/docs/Masa.Blazor.Docs/wwwroot/pages/getting-started/upgrade-guide/en-US.md b/docs/Masa.Blazor.Docs/wwwroot/pages/getting-started/upgrade-guide/en-US.md
@@ -23,10 +23,10 @@ v1.0.x contains non backwards compatible breaking changes, the following changes
   ```
 - The **PConfirm** has been removed now, use `IPopupService.ConfirmAsync` instead.
 - **MHover** removes the `Class` and `Style` properties of `Context`.
-- **MErrorHandler** removes the parameter `ShowAlert`, uses `PopupType` instead:
+- **MErrorHandler** removes the `ShowAlert` parameter, uses `PopupType` instead. And removes the `OnErrorHandleAsync` parameter, use `OnHandle` instead. `OnHandle` would overrides the default error handler. Use `OnAfterHandle` if you only want to do something else after handling an error.
   ```diff
   - <MErrorHandler ShowAlert="false"></MErrorHandler>
-  + <MErrorHandler PopupType="ErrorPopupType.None"></MErrorHandler>
+  + <MErrorHandler PopupType="ErrorPopupType.None" OnHandle="" OnAfterHandle=""></MErrorHandler>
   ```
 - Removed the **PToasts** component, and use the **PEnqueuedSnackbars** component instead.
 - **PopupService** removes `AlertAsync` 和 `ToastAsync`, and use `EnqueueSnackbarAsync` instead.

diff --git a/docs/Masa.Blazor.Docs/wwwroot/pages/getting-started/upgrade-guide/zh-CN.md b/docs/Masa.Blazor.Docs/wwwroot/pages/getting-started/upgrade-guide/zh-CN.md
@@ -23,10 +23,10 @@ v1.0.x 包含了不兼容的破坏性更改，包括以下变更：
   ```
 - **PConfirm** 已被移除，请使用 `IPopupService.ConfirmAsync`。
 - **MHover** 移除了 `Context` 的 `Class` 和 `Style` 属性。
-- **MErrorHandler** 移除了 `ShowAlert` 参数，使用 `PopupType` 代替：
+- **MErrorHandler** 移除了 `ShowAlert` 参数，使用 `PopupType` 代替；移除了 `OnErrorHandleAsync` 参数，请使用 `OnHandle` 代替。`OnHandle` 会覆盖默认的错误处理程序，如果你只想在处理错误之后做其他操作，请使用 `OnAfterHandle`。
   ```diff
-  - <MErrorHandler ShowAlert="false"></MErrorHandler>
-  + <MErrorHandler PopupType="ErrorPopupType.None"></MErrorHandler>
+  - <MErrorHandler ShowAlert="false" OnErrorHandleAsync=""></MErrorHandler>
+  + <MErrorHandler PopupType="ErrorPopupType.None" OnHandle="" OnAfterHandle=""></MErrorHandler>
   ```
 - 移除了 **PToasts** 组件，请使用 **PEnqueuedSnackbars** 组件代替。
 - **PopupService** 移除了 `AlertAsync` 和 `ToastAsync`，请使用 `EnqueueSnackbarAsync` 代替。

diff --git a/src/Masa.Blazor/Popup/Components/AlertingPopupComponentBase.cs b/src/Masa.Blazor/Popup/Components/AlertingPopupComponentBase.cs
@@ -1,4 +1,6 @@
-namespace Masa.Blazor.Popup.Components;
+#nullable enable
+
+namespace Masa.Blazor.Popup.Components;
 
 public class AlertingPopupComponentBase : PopupComponentBase
 {
@@ -47,4 +49,4 @@ protected virtual string? ComputedIconColor
             };
         }
     }
-}
+}
diff --git a/src/Masa.Blazor/Popup/Components/Confirm/Confirm.razor.cs b/src/Masa.Blazor/Popup/Components/Confirm/Confirm.razor.cs
@@ -61,7 +61,7 @@ protected override void OnParametersSet()
     private Task HandleOnCancel()
     {
         Visible = false;
-        return SetResult(false);
+        return ClosePopupAsync(false);
     }
 
     private async Task HandleOnOk()
@@ -78,16 +78,7 @@ private async Task HandleOnOk()
         if (args.IsCanceled is false)
         {
             Visible = false;
-            await SetResult(true);
-        }
-    }
-
-    private async Task SetResult(bool value)
-    {
-        if (PopupItem is not null)
-        {
-            await Task.Delay(256);
-            PopupItem.Discard(value);
+            await ClosePopupAsync(true);
         }
     }
 

diff --git a/src/Masa.Blazor/Popup/Components/PopupComponentBase.cs b/src/Masa.Blazor/Popup/Components/PopupComponentBase.cs
@@ -1,12 +1,12 @@
-namespace Masa.Blazor.Popup.Components;
+#nullable enable
+
+namespace Masa.Blazor.Popup.Components;
 
 public class PopupComponentBase : BComponentBase
 {
-    [Inject]
-    protected I18n I18n { get; set; } = null!;
+    [Inject] protected I18n? I18n { get; set; }
 
-    [CascadingParameter]
-    protected ProviderItem? PopupItem { get; set; }
+    [CascadingParameter] private ProviderItem? PopupItem { get; set; }
 
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? Attributes { get; set; }
@@ -23,4 +23,17 @@ protected override void OnInitialized()
             StateHasChanged();
         });
     }
+
+    /// <summary>
+    /// Close the opened popup component and return the value argument as feedback.
+    /// </summary>
+    /// <param name="returnVal">return value for the <see cref="IPopupService"/>'s Open method.</param>
+    protected async Task ClosePopupAsync(object? returnVal = null)
+    {
+        if (PopupItem != null)
+        {
+            await Task.Delay(256);
+            PopupItem.Discard(returnVal);
+        }
+    }
 }
diff --git a/src/Masa.Blazor/Popup/Components/Prompt/Prompt.razor.cs b/src/Masa.Blazor/Popup/Components/Prompt/Prompt.razor.cs
@@ -62,7 +62,7 @@ protected override void OnParametersSet()
     private Task HandleOnCancel()
     {
         Visible = false;
-        return SetResult(null);
+        return ClosePopupAsync(null);
     }
 
     private async Task HandleOnSubmit()
@@ -79,7 +79,7 @@ private async Task HandleOnSubmit()
         if (args.IsCanceled is false)
         {
             Visible = false;
-            await SetResult(_promptValue.Value);
+            await ClosePopupAsync(_promptValue.Value);
         }
     }
 
@@ -91,15 +91,6 @@ private async Task HandleOnOk()
         }
     }
 
-    private async Task SetResult(string? value)
-    {
-        if (PopupItem != null)
-        {
-            await Task.Delay(256);
-            PopupItem.Discard(value);
-        }
-    }
-
     protected virtual ModalButtonProps GetDefaultSaveButtonProps() => new()
     {
         Color = "primary",

diff --git a/src/Masa.Blazor/Popup/IPopupService.cs b/src/Masa.Blazor/Popup/IPopupService.cs
@@ -1,11 +1,13 @@
-using Masa.Blazor.Presets;
+#nullable enable
+
+using Masa.Blazor.Presets;
 using Masa.Blazor.Popup;
 
 namespace Masa.Blazor;
 
 public interface IPopupService
 {
-    Task<object> OpenAsync(Type componentType, IDictionary<string, object> parameters);
+    Task<object?> OpenAsync(Type componentType, IDictionary<string, object?> parameters);
 
     #region Confirm
 
@@ -39,7 +41,7 @@ public interface IPopupService
 
     Task EnqueueSnackbarAsync(string title, string content, AlertTypes type = AlertTypes.None, bool closeable = false, int timeout = 5000);
 
-    Task EnqueueSnackbarAsync(Exception exception, bool withStackTrace, bool closeable = false, int timeout = 5000);
+    Task EnqueueSnackbarAsync(Exception exception, bool withStackTrace = false, bool closeable = false, int timeout = 5000);
 
     Task EnqueueSnackbarAsync(SnackbarOptions options);
 

diff --git a/src/Masa.Blazor/Popup/PopupService.snackbar.cs b/src/Masa.Blazor/Popup/PopupService.snackbar.cs
@@ -17,7 +17,7 @@ public async Task EnqueueSnackbarAsync(string title, string content, AlertTypes
         await EnqueueSnackbarAsync(new SnackbarOptions(title, content, type, closeable, timeout));
     }
 
-    public async Task EnqueueSnackbarAsync(Exception exception, bool withStackTrace, bool closeable = false, int timeout = 5000)
+    public async Task EnqueueSnackbarAsync(Exception exception, bool withStackTrace = false, bool closeable = false, int timeout = 5000)
     {
         if (withStackTrace)
         {