Merge pull request #13269 from abpframework/Doc-Dynamic-Widget

Doc dynamic widget

docs/en/Modules/Cms-Kit/Dynamic-Widget.md

@@ -0,0 +1,137 @@
+# Dynamic Widget
+
+CMS kit provides a dynamic [widget](https://docs.abp.io/en/abp/latest/UI/AspNetCore/Widgets) used to render the components previously developed by the software in the content of the pages and blog posts. Its means, that in static content you can use dynamic content. We will mention how you can do it. You have two choices to define the widget in the system: Writing and UI.
+
+### Adding the widget
+Firstly we will show how to use the widget system via writing manually in the page and blogpost contents.
+
+Let's define the view component
+
+```csharp
+[Widget]
+[ViewComponent(Name = "CmsToday")]
+public class TodayViewComponent : AbpViewComponent
+{
+    public IViewComponentResult Invoke()
+    {
+        return View("~/ViewComponents/Today.cshtml",
+         new TodayViewComponent());
+    }
+} 
+```
+
+```html
+@model Volo.CmsKit.ViewComponents.TodayViewComponent
+
+<p>Welcome Today Component</p>
+<p>@DateTime.Now.ToString()</p>
+
+```
+
+Now configuration time on YourModule.cs
+```csharp
+Configure<CmsKitContentWidgetOptions>(options =>
+    {
+        options.AddWidget("Today","CmsToday");
+    }); 
+```
+
+Now you're ready to add your widget by writing.
+[Widget Type="Today"]
+
+After completing the above steps, you can see the output at the right of the below screenshot.
+![cmskit-without-parameter.png](../../images/cmskit-without-parameter.png)
+
+### Adding by using UI 
+Now we will mention the second option, using UI.
+Once writing these definitions can make some mistakes hence we added a new feature to use the widget system easily. To the right of the editor, you will see the customized `W` button to add a dynamic widget like the below image. Don't forget please this is design mode and you need to view your page in view mode after saving. Also `Preview` tab on the editor will be ready to check your output easily for widget configurations in the next features.
+
+![cms-kit-page-editor](../../images/cms-kit-page-editor.png)
+
+### Adding by using UI with parameters
+Let's improve the above example by adding a new parameter named format. Via this feature, we can use the widget system with many different scenarios but not prolong the document. Also, these examples can be expandable with dependency injection and getting values from the database, but we will use a basic example. We will add the format parameter to customize the date.
+
+```csharp
+[Widget]
+[ViewComponent(Name = "CmsToday")]
+public class TodayViewComponent : AbpViewComponent
+{
+    public string Format { get; set; }
+
+    public IViewComponentResult Invoke(string format)
+    {
+        return View("~/ViewComponents/Today.cshtml",
+         new TodayViewComponent() { Format = format });
+    }
+} 
+```
+
+```html
+@model Volo.CmsKit.ViewComponents.TodayViewComponent
+
+<p>Welcome Today Component</p>
+<p>@DateTime.Now.ToString(Format)</p>
+
+```
+
+Let's define the format component.
+```csharp
+[Widget]
+[ViewComponent(Name = "Format")]
+public class FormatViewComponent : AbpViewComponent
+{
+    public IViewComponentResult Invoke()
+    {
+        return View("~/ViewComponents/Format.cshtml",
+         new FormatViewModel());
+    }  
+}
+
+public class FormatViewModel
+{
+    [DisplayName("Format your date in the component")]
+    public string Format { get; set; }
+}
+```
+> Important Note: To get properties properly you should set the `name` property on the razor page or you may use the ABP component. ABP handles that automatically.
+
+```html
+@using Volo.CmsKit.ViewComponents
+@model FormatViewModel
+
+<div>
+    <abp-input asp-for="Format" />
+</div>
+```
+
+```csharp
+Configure<CmsKitContentWidgetOptions>(options =>
+    {
+        options.AddWidget("Today", "CmsToday", "Format");
+    }); 
+```
+
+![cmskit-module-editor-parameter](../../images/cmskit-module-editor-parameter.png)
+
+In this image, after choosing your widget (on the other case, it changes automatically up to your configuration, mine is `Today`. Its parameter name `parameterWidgetName` and its value is `Format`) you will see the next widget. Enter input values or choose them and click `Add`. You will see the underlined output in the editor. Right of the image, also you can see its previewed output.
+
+You can edit this output manually if do any wrong coding for that (wrong value or typo) you won't see the widget, even so, your page will be viewed successfully. 
+
+## Options 
+To configure the widget, you should define the below code in YourModule.cs 
+
+```csharp
+Configure<CmsKitContentWidgetOptions>(options =>
+    {
+        options.AddWidget(widgetType: "Today", widgetName: "CmsToday", parameterWidgetName: "Format");
+    }); 
+```
+
+Let's look at these parameters in detail
+* `widgetType` is used for end-user and more readable names. The following bold word represents widgetType.
+[Widget Type="**Today**" Format="yyyy-dd-mm HH:mm:ss"].
+
+* `widgetName` is used for your widget name used in code for the name of the `ViewComponent`.
+
+* `parameterWidgetName` is used the for editor component side to see on the `Add Widget` modal.
+After choosing the widget type from listbox (now just defined `Format`) and renders this widget automatically. It's required only to see UI once using parameters

docs/en/Modules/Cms-Kit/Index.md

@@ -14,6 +14,7 @@ The following features are currently available:
 * Provides a [**rating**](Ratings.md) system to add rating feature to any kind of resource.
 * Provides a [**menu**](Menus.md) system to manage public menus dynamically.
 * Provides a [**global resources**](Global-Resources.md) system to add global styles and scripts dynamically.
+* Provides a [**Dynamic Widget**](Dynamic-Widget.md) system to create dynamic widgets for page and blog posts.
 
 Click to a feature to understand and learn how to use it.
 

docs/zh-Hans/Modules/Cms-Kit/Dynamic-Widget.md

@@ -0,0 +1,47 @@
+# 动态部件
+
+CMS kit提供了组件系统在页面和博客文章和生成动态部件. 这是一个在 `Page` 端的示例投票部件截图
+
+> 重要提示: 投票部件是ABP Commercial实现的唯一部件
+![cmskit-example-output-on-page](../../images/cmskit-example-output-on-page.png)
+
+> 你也可以对其他小部件执行相同的操作.这只是一个例子.
+要添加部件,你应该去页面或博客创建或更新, 然后单击 `W` 按钮添加一个动态部件, 如下图所示. 不要忘了这是设计模态框,你需要在保存后查看你的页面. 此外 `预览` 选项卡可以轻松的查看部件配置的部件输出.
+
+![cmskit-add-widget-on-page](../../images/cmskit-add-widget-on-page.png)
+
+在这张图中, 选择投票后(在其他情况下,它根据你的配置自动改变, 这里是投票组件,它的参数名是 `editorWidgetName`),你看到下一个部件, 输入值或选择值或选择并单击 `添加`. 你将看到以下输出
+
+> [Widget Type="Poll" Code="SelectedValue"]
+如果编码有任何错误(错误的值或拼写错误)你可以手动修改输出.
+
+## 选项
+
+使添加的部件工作,你必须在模块类中进行配置:
+
+```csharp
+Configure<CmsKitContentWidgetOptions>(options =>
+{
+    options.AddWidget("widgetKey", "widgetName", "editorWidgetName");
+}); 
+```
+
+* `widgetKey` 用于最终用户更具有可读性的名称.
+    [Widget Type="**Poll**" Code="SelectedValue"]
+* `widgetName` 用于代码中通过 `[widget]` Attribute使用的小部件名称
+
+```csharp
+[Widget]
+public class WidgetNameViewComponent : AbpViewComponent
+{
+    public IViewComponentResult Invoke()
+    {
+        return View();
+    }
+}
+    
+```
+
+* `editorWidgetName` 用于编辑器组件端，在 `添加部件` 模态框中查看.
+
+另请参阅[部件](https://docs.abp.io/zh-Hans/abp/latest/UI/AspNetCore/Widgets).

docs/zh-Hans/Modules/Cms-Kit/Index.md

@@ -13,6 +13,7 @@
 * 提供 [**反应**](Reactions.md) 系统来添加对任何资源的反应 (表情符号) 功能, 如博客文章或评论.
 * 提供 [**评级**](Ratings.md) 系统来添加对任何资源的评级功能.
 * 提供 [**菜单**](Menus.md) 系统来动态管理公共菜单.
+* 提供 [**动态部件**](Dynamic-Widget.md) 系统在页面和博客文章中创建动态部件.
 
 点击功能以了解和学习如何去使用它.
 

modules/cms-kit/host/Volo.CmsKit.Web.Unified/CmsKitWebUnifiedModule.cs

@@ -1,11 +1,7 @@
 using System.IO;
-using System.Linq;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
-using Volo.CmsKit.EntityFrameworkCore;
-using Volo.CmsKit.MultiTenancy;
-using Volo.CmsKit.Web;
 using Microsoft.OpenApi.Models;
 using Volo.Abp;
 using Volo.Abp.Account;
@@ -19,8 +15,8 @@ using Volo.Abp.BlobStoring.Database.EntityFrameworkCore;
 using Volo.Abp.Data;
 using Volo.Abp.EntityFrameworkCore;
 using Volo.Abp.EntityFrameworkCore.SqlServer;
-using Volo.Abp.FeatureManagement.EntityFrameworkCore;
 using Volo.Abp.FeatureManagement;
+using Volo.Abp.FeatureManagement.EntityFrameworkCore;
 using Volo.Abp.Identity;
 using Volo.Abp.Identity.EntityFrameworkCore;
 using Volo.Abp.Identity.Web;
@@ -29,6 +25,7 @@ using Volo.Abp.Modularity;
 using Volo.Abp.MultiTenancy;
 using Volo.Abp.PermissionManagement;
 using Volo.Abp.PermissionManagement.EntityFrameworkCore;
+using Volo.Abp.PermissionManagement.HttpApi;
 using Volo.Abp.PermissionManagement.Identity;
 using Volo.Abp.SettingManagement.EntityFrameworkCore;
 using Volo.Abp.Swashbuckle;
@@ -38,15 +35,16 @@ using Volo.Abp.TenantManagement.Web;
 using Volo.Abp.Threading;
 using Volo.Abp.VirtualFileSystem;
 using Volo.CmsKit.Admin.Web;
-using Volo.CmsKit.Public.Web;
-using System;
-using Volo.Abp.PermissionManagement.HttpApi;
-using Volo.CmsKit.Tags;
 using Volo.CmsKit.Comments;
+using Volo.CmsKit.Contents;
+using Volo.CmsKit.EntityFrameworkCore;
 using Volo.CmsKit.MediaDescriptors;
-using Volo.CmsKit.Reactions;
+using Volo.CmsKit.MultiTenancy;
+using Volo.CmsKit.Public.Web;
 using Volo.CmsKit.Ratings;
-using Volo.CmsKit.Contents;
+using Volo.CmsKit.Reactions;
+using Volo.CmsKit.Tags;
+using Volo.CmsKit.Web;
 
 namespace Volo.CmsKit;
 
@@ -93,9 +91,8 @@ public class CmsKitWebUnifiedModule : AbpModule
     public override void ConfigureServices(ServiceConfigurationContext context)
     {
         var hostingEnvironment = context.Services.GetHostingEnvironment();
-        var configuration = context.Services.GetConfiguration();
 
-        ConfigureCmsKit(context);
+        ConfigureCmsKit();
 
         Configure<AbpDbContextOptions>(options =>
         {
@@ -156,11 +153,11 @@ public class CmsKitWebUnifiedModule : AbpModule
 
         Configure<CmsKitContentWidgetOptions>(options =>
         {
-            options.AddWidget("ExComment", "CommentDate");
+            options.AddWidget("Today", "CmsToday", "Format");
         });
     }
 
-    private void ConfigureCmsKit(ServiceConfigurationContext context)
+    private void ConfigureCmsKit()
     {
         Configure<CmsKitTagOptions>(options =>
         {

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/CommentDate.cshtml

@@ -1,11 +0,0 @@
-@model Volo.CmsKit.ViewComponents.CommentDateViewComponent
-
-<p>Welcome Comment Date Component</p>
-@if (Model.IsShow)
-{
-    <p> @DateTime.Today.ToLongDateString()</p>
-}
-else
-{
-    <p>Without date</p>
-}

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/DecisionCommentDate.cshtml

@@ -1,6 +0,0 @@
-@using Volo.CmsKit.ViewComponents
-@model DecisionCommentDateViewModel
-
-<div class="form-check mb-3">
-    <abp-input asp-for="IsShow" />
-</div>

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/DecisionCommentDateViewComponent.cs

@@ -1,32 +0,0 @@
-using System.ComponentModel;
-using System.ComponentModel.DataAnnotations;
-using System.Threading.Tasks;
-using Microsoft.AspNetCore.Mvc;
-using Volo.Abp.AspNetCore.Mvc;
-using Volo.Abp.AspNetCore.Mvc.UI.Widgets;
-using Volo.Abp.Localization;
-
-namespace Volo.CmsKit.ViewComponents;
-
-[Widget(
-    AutoInitialize = true
-)]
-
-[ViewComponent(Name = "DecisionCommentDate")]
-public class DecisionCommentDateViewComponent : AbpViewComponent
-{
-    public DecisionCommentDateViewComponent()
-    {
-    }
-
-    public virtual async Task<IViewComponentResult> InvokeAsync()
-    {
-        return View("~/ViewComponents/DecisionCommentDate.cshtml", new DecisionCommentDateViewModel());
-    }
-}
-
-public class DecisionCommentDateViewModel
-{
-    [DisplayName("Show date in the component")]
-    public bool IsShow { get; set; } = true;
-}

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/Format.cshtml

@@ -0,0 +1,6 @@
+@using Volo.CmsKit.ViewComponents
+@model FormatViewModel
+
+<div>
+    <abp-input asp-for="Format" />
+</div>

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/FormatViewComponent.cs

@@ -0,0 +1,30 @@
+using System.ComponentModel;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Mvc;
+using Volo.Abp.AspNetCore.Mvc;
+using Volo.Abp.AspNetCore.Mvc.UI.Widgets;
+
+namespace Volo.CmsKit.ViewComponents;
+
+[Widget(
+    AutoInitialize = true
+)]
+
+[ViewComponent(Name = "Format")]
+public class FormatViewComponent : AbpViewComponent
+{
+    public FormatViewComponent()
+    {
+    }
+
+    public virtual async Task<IViewComponentResult> InvokeAsync()
+    {
+        return View("~/ViewComponents/Format.cshtml", new FormatViewModel());
+    }
+}
+
+public class FormatViewModel
+{
+    [DisplayName("Format your date in the component")]
+    public string Format { get; set; }
+}

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/Today.cshtml

@@ -0,0 +1,5 @@
+@model Volo.CmsKit.ViewComponents.TodayViewComponent
+
+<p>Welcome Today Component</p>
+
+<p>@DateTime.Now.ToString(Model.Format)</p>

modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/CommentDateViewComponent.cs → modules/cms-kit/host/Volo.CmsKit.Web.Unified/ViewComponents/TodayViewComponent.cs

@@ -9,17 +9,17 @@ namespace Volo.CmsKit.ViewComponents;
     AutoInitialize = true
 )]
 
-[ViewComponent(Name = "CommentDate")]
-public class CommentDateViewComponent : AbpViewComponent
+[ViewComponent(Name = "CmsToday")]
+public class TodayViewComponent : AbpViewComponent
 {
-    public bool IsShow { get; set; }
+    public string Format { get; set; }
 
-    public CommentDateViewComponent()
+    public TodayViewComponent()
     {
     }
 
-    public virtual async Task<IViewComponentResult> InvokeAsync(string isShow)
+    public virtual async Task<IViewComponentResult> InvokeAsync(string format)
     {
-        return View("~/ViewComponents/CommentDate.cshtml", new CommentDateViewComponent() { IsShow = bool.Parse(isShow) });
+        return View("~/ViewComponents/Today.cshtml", new TodayViewComponent() { Format = format });
     }
 }

modules/cms-kit/src/Volo.CmsKit.Common.Application/Volo/CmsKit/Contents/CmsKitContentWidgetOptions.cs

@@ -11,9 +11,9 @@ public class CmsKitContentWidgetOptions
         WidgetConfigs = new();
     }
 
-    public void AddWidget(string widgetKey, string widgetName, string editorWidgetName = null)
+    public void AddWidget(string widgetType, string widgetName, string parameterWidgetName = null)
     {
-        var config = new ContentWidgetConfig(widgetName, editorWidgetName);
-        WidgetConfigs.Add(widgetKey, config);
+        var config = new ContentWidgetConfig(widgetName, parameterWidgetName);
+        WidgetConfigs.Add(widgetType, config);
     }
 }