diff --git a/docs/en/modules/cms-kit/blogging.md b/docs/en/modules/cms-kit/blogging.md index 90356a59fe..1c0ee4713e 100644 --- a/docs/en/modules/cms-kit/blogging.md +++ b/docs/en/modules/cms-kit/blogging.md @@ -15,6 +15,8 @@ By default, CMS Kit features are disabled. Therefore, you need to enable the fea > Check the ["How to Install" section of the CMS Kit Module documentation](index.md#how-to-install) to see how to enable/disable CMS Kit features on development time. +> The built-in MVC blog routes are registered by the Pages global feature. Enable both `Blogs` and `Pages` when you use the built-in public blog pages. + ## User Interface ### Menu Items @@ -38,7 +40,7 @@ A screenshot from the new blog creation modal: **Slug** is the URL part of the blog. For this example, the root URL of the blog becomes `your-domain.com/blogs/technical-blog/`. -- You can change the default slug by using `CmsBlogsWebConsts.BlogRoutePrefix` constant. For example, if you set it to `foo`, the root URL of the blog becomes `your-domain.com/foo/technical-blog/`. +- You can change the default route prefix by using the `CmsBlogsWebConsts.BlogsRoutePrefix` property. For example, if you set it to `foo`, the root URL of the blog becomes `your-domain.com/foo/technical-blog/`. ```csharp public override void PreConfigureServices(ServiceConfigurationContext context) @@ -49,7 +51,7 @@ A screenshot from the new blog creation modal: #### Blog Features -Blog feature uses some of the other CMS Kit features. You can enable or disable the features by clicking the features action for a blog. +The blogging feature uses other CMS Kit features. A newly created blog enables comments, reactions, ratings, tags, marked items, the quick navigation bar and XSS prevention by default when the related global features are available. You can enable or disable these features for each blog by clicking the features action. ![blogs-feature-action](../../images/cmskit-module-blogs-feature-action.png) @@ -58,7 +60,7 @@ You can select/deselect the desired features for blog posts. ![features-dialog](../../images/cmskit-module-features-dialog-2.png) ##### Quick Navigation Bar In Blog Post -If you enable "Quick navigation bar in blog posts", it will enabled scroll index as seen below. +If you enable **Quick navigation bar in blog posts**, the public blog post page builds a scroll index from the post headings. ![scroll-index](../../images/cmskit-module-features-scroll-index.png) @@ -72,6 +74,10 @@ You can create and edit an existing blog post on this page. If you enable specif ![blog-post-edit](../../images/cmskit-module-blog-post-edit.png) +Blog posts have three statuses: `Draft`, `WaitingForReview` and `Published`. Creating, updating, deleting and publishing posts use separate permissions. The public blog list requests only published posts and can filter them by author, tag or the current user's marked items. + +The built-in renderer allows HTML in blog post Markdown. The per-blog **Prevent XSS** feature controls whether the Markdown renderer sanitizes that HTML and is enabled for newly created blogs. Keep it enabled when post authors are not trusted to submit arbitrary HTML. + ## Internals ### Domain Layer @@ -138,4 +144,4 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ## Entity Extensions -Check the ["Entity Extensions" section of the CMS Kit Module documentation](index.md#entity-extensions) to see how to extend entities of the Blogging Feature of the CMS Kit module. \ No newline at end of file +Check the ["Entity Extensions" section of the CMS Kit Module documentation](index.md#entity-extensions) to see how to extend entities of the Blogging Feature of the CMS Kit module. diff --git a/docs/en/modules/cms-kit/comments.md b/docs/en/modules/cms-kit/comments.md index 0070b5a2a9..c3a595a7d8 100644 --- a/docs/en/modules/cms-kit/comments.md +++ b/docs/en/modules/cms-kit/comments.md @@ -25,16 +25,16 @@ The comment system provides a mechanism to group comment definitions by entity t Configure(options => { options.EntityTypes.Add(new CommentEntityTypeDefinition("Product")); - options.IsRecaptchaEnabled = true; //false by default + options.IsRecaptchaEnabled = true; options.AllowedExternalUrls = new Dictionary> { - { - "Product", - new List { - "https://abp.io/" + "Product", + new List + { + "https://abp.io/" + } } - } }; }); ``` @@ -43,9 +43,9 @@ Configure(options => `CmsKitCommentOptions` properties: -- `EntityTypes`: List of defined entity types(`CmsKitCommentOptions`) in the comment system. +- `EntityTypes`: List of defined entity types (`CommentEntityTypeDefinition`) in the comment system. - `IsRecaptchaEnabled`: This flag enables or disables the reCaptcha for the comment system. You can set it as **true** if you want to use reCaptcha in your comment system. -- `AllowedExternalUrls`: Indicates the allowed external URLs by entity types, which can be included in a comment. If it's specified for a certain entity type, then only the specified external URLs are allowed in the comments. +- `AllowedExternalUrls`: Registers the URL values used by the external-link validation for each entity type. `CommentEntityTypeDefinition` properties: @@ -67,6 +67,17 @@ The comment system provides a commenting [widget](../../framework/ui/mvc-razor-p `entityType` was explained in the previous section. `entityId` should be the unique id of the product, in this example. If you have a Product entity, you can use its Id here. `referralLinks` is an optional parameter. You can use this parameter to add values (such as "nofollow", "noreferrer", or any other values) to the [rel attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel) of links. +Creating, updating and deleting a comment requires an authenticated user. Users can update only their own comments. They can delete their own comments, while the `CmsKitPublic.Comments.DeleteAll` permission allows deleting comments created by other users. Deleting a comment also deletes its direct replies. + +Reactions are enabled inside the MVC comments widget by default when the Reactions global feature is available. Disable them without disabling reactions for other entity types by configuring the UI options in the web project: + +```csharp +Configure(options => +{ + options.CommentsOptions.IsReactionsEnabled = false; +}); +``` + ## User Interface ### Menu Items @@ -89,7 +100,7 @@ You can also view and manage replies on this page. ## Settings -You can configure the approval status of comments using the "Comment" tab under the "Cms" section on the Settings page. When this feature is enabled, you can approve and reject comments. In this way, users can only see the comments that you approve. By default, this feature is set to "false." +You can configure the approval status of comments using the **Comment** tab under the **Cms** section on the Settings page. When approval is required, new comments wait for an administrator and public queries return only approved comments. When approval is disabled, waiting comments are also visible. The setting is stored globally, not per tenant, and is `false` by default. Changing it requires the `CmsKit.Comments.SettingManagement` permission. ![comments-settings](../../images/cmskit-module-comments-settings.png) @@ -136,7 +147,7 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ##### Table / collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ##### Connection string @@ -155,4 +166,3 @@ See the [connection strings](../../framework/fundamentals/connection-strings.md) ##### Collections - **CmsComments** - diff --git a/docs/en/modules/cms-kit/dynamic-widget.md b/docs/en/modules/cms-kit/dynamic-widget.md index f0646cc00f..6eed96868c 100644 --- a/docs/en/modules/cms-kit/dynamic-widget.md +++ b/docs/en/modules/cms-kit/dynamic-widget.md @@ -122,7 +122,7 @@ Configure(options => 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. +The stored widget markup is parsed when a page or blog post is rendered. When at least one widget has been registered, an unknown widget type is omitted from the rendered fragments. If no widgets have been registered, the stored markup remains in a Markdown fragment. If a registered view component throws while rendering, CMS Kit keeps the rest of the page visible, renders a localized error alert for that fragment and writes the exception to the application log. ## Options @@ -146,4 +146,6 @@ The `CmsKitContentWidgetOptions` provides two methods for registering widgets: - `parameterWidgetName` (optional): The name of the parameter widget that will be displayed in the "Add Widget" modal to collect parameter values from users. This is only required when your widget needs parameters. - **AddWidgetIfFeatureEnabled:** Registers a widget conditionally, only if a specified [global feature](../../framework/infrastructure/global-features.md) is enabled. It accepts the same parameters as `AddWidget`, plus an additional first parameter: - - `featureType` (required): The type of the global feature that must be enabled for the widget to be available (e.g., `typeof(PagesFeature)`). \ No newline at end of file + - `featureType` (required): The type of the global feature that must be enabled for the widget to be available (e.g., `typeof(PagesFeature)`). + +The registration is shared by the administration editor and the public content parser. `AddWidgetIfFeatureEnabled` evaluates the global feature while the module configures its services; it does not use the runtime tenant feature system. diff --git a/docs/en/modules/cms-kit/global-resources.md b/docs/en/modules/cms-kit/global-resources.md index ff02351be8..e945908ace 100644 --- a/docs/en/modules/cms-kit/global-resources.md +++ b/docs/en/modules/cms-kit/global-resources.md @@ -31,6 +31,10 @@ Global Resources page is used to manage global styles and scripts in the system. ![cms-kit-global-resources-page](../../images/cmskit-module-global-resources-page.png) +The built-in public web module adds the style resource at `LayoutHooks.Head.Last` and the script resource at `LayoutHooks.Body.Last`. The resources are served from `/cms-kit/global-resources/style` and `/cms-kit/global-resources/script`. A cache miss stores the loaded resource in the distributed cache with a two-minute absolute expiration. Updating an existing resource refreshes its cached value through a local entity event and uses the configured default cache options. + +> Global resources are trusted administrator input. The style is returned as CSS and the script is returned as executable JavaScript on every public page that uses the layout hooks. Grant `CmsKit.GlobalResources` only to users who are allowed to execute code in visitors' browsers, and apply your Content Security Policy accordingly. + # Internals ## Domain Layer @@ -76,4 +80,4 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ##### Collections -- CmsGlobalResources \ No newline at end of file +- CmsGlobalResources diff --git a/docs/en/modules/cms-kit/index.md b/docs/en/modules/cms-kit/index.md index 344b719889..02bd58f5f9 100644 --- a/docs/en/modules/cms-kit/index.md +++ b/docs/en/modules/cms-kit/index.md @@ -11,7 +11,7 @@ This module provides CMS (Content Management System) capabilities for your appli > You can see the live demo at [cms-kit-demo.abpdemo.com](https://cms-kit-demo.abpdemo.com/). -> **This module currently available only for the MVC / Razor Pages UI**. While there is no official Blazor package, it can also work in a Blazor Server UI since a Blazor Server UI is actually a hybrid application that runs in an ASP.NET Core MVC / Razor Pages application. +> CMS Kit provides MVC / Razor Pages packages for both the administration and public websites. The `@abp/ng.cms-kit` package provides an Angular administration UI. There is no official Blazor package; a Blazor Server application can host the MVC / Razor Pages UI because it runs on ASP.NET Core. The following features are currently available: @@ -28,7 +28,12 @@ The following features are currently available: > You can click on the any feature links above to understand and learn how to use it. -All features are individually usable. If you disable a feature, it completely disappears from your application, even from the database tables, with the help of the [Global Features](../../framework/infrastructure/global-features.md) system. +CMS Kit uses two feature layers: + +* [Global Features](../../framework/infrastructure/global-features.md) select the CMS Kit subsystems included in the application model. When using Entity Framework Core, changing these features requires a new migration because disabled entities are excluded from the EF Core model. +* The [Feature System](../../framework/infrastructure/features.md) can enable or disable the corresponding subsystem at runtime for a tenant or another feature value provider. Runtime feature changes do not change the database model. + +Most subsystems can be selected independently. The built-in MVC blog pages are currently registered together with the Pages global feature, so enable both `Blogs` and `Pages` when you use the built-in public blog UI. ## Pre Requirements @@ -38,6 +43,23 @@ All features are individually usable. If you disable a feature, it completely di - CMS Kit uses [distributed cache](../../framework/fundamentals/caching.md) for responding faster. > Using a distributed cache, such as [Redis](../../framework/fundamentals/redis-cache.md), is highly recommended for data consistency in distributed/clustered deployments. +## Media Storage and Entity Types + +When the Media global feature is enabled, CMS Kit registers media definitions for blog posts and pages. To upload media for another entity type, register a `MediaDescriptorDefinition` and specify the permissions that can create and delete its media: + +```csharp +Configure(options => +{ + options.EntityTypes.Add( + new MediaDescriptorDefinition( + "Product", + createPolicies: new[] { "Products.Update" }, + deletePolicies: new[] { "Products.Update" })); +}); +``` + +The administration service grants an operation when the current user has any policy in the corresponding list. An empty list grants no access. Media files are downloaded from the anonymous `GET /api/cms-kit/media/{id}` endpoint, so this facility is for public media; use a separately authorized BLOB endpoint for private files. + ## Identity Integration for User Lookup CMS Kit uses `ICmsUserLookupService` when it needs user information for features such as comments, ratings, blog post management and user synchronization. @@ -129,6 +151,31 @@ CMS kit packages are designed for various usage scenarios. If you check the [CMS - `Volo.CmsKit.Public.*` packages contain the functionalities used in public websites where users read blog posts or leave comments. - `Volo.CmsKit.*` (without Admin/Public suffix) packages are called as unified packages. Unified packages are shortcuts for adding Admin & Public packages (of the related layer) separately. If you have a single application for administration and public web site, you can use these packages. +### Angular Administration UI + +The `@abp/ng.cms-kit` package contains the Angular administration components, routes, configuration providers and generated proxies. Register the administration menu configuration in the application configuration and lazy-load the administration routes: + +```typescript +import { ApplicationConfig } from '@angular/core'; +import { Routes } from '@angular/router'; +import { provideCmsKitAdminConfig } from '@abp/ng.cms-kit/admin/config'; + +export const appConfig: ApplicationConfig = { + providers: [provideCmsKitAdminConfig()], +}; + +export const routes: Routes = [ + { + path: 'cms', + loadChildren: () => import('@abp/ng.cms-kit/admin').then(m => m.createRoutes()), + }, +]; +``` + +The Angular administration routes include comments, tags, pages, blogs, blog posts, menus and global resources. The built-in public page and blog UI documented in this guide uses the MVC / Razor Pages packages. + +`createRoutes` accepts a `CmsKitAdminConfigOptions` object for Angular UI extensions. It supports entity-action, entity-property, toolbar-action, create-form-property and edit-form-property contributors. Key the contributor dictionaries with `eCmsKitAdminComponents`; the supported screens cover comment lists/details, tags, pages and page forms, blogs, blog posts and blog post forms, and menus. Each contributor type exposes only the keys supported by that screen. + ## Integrating Public and Admin Packages in a Unified Application If you are using a single application for both admin and public web site, it's important to configure the global layout settings appropriately. By default, the layout is set for a **Public Website**, which is suitable for public-facing pages. However, when your application serves both admin and public pages, you should explicitly set the global layout for all CMS Kit pages. @@ -150,7 +197,7 @@ To do this, add a `_ViewStart.cshtml` file to your web project at `/Pages/Public ### Table / collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ### Connection string @@ -209,13 +256,10 @@ public static void ConfigureExtraProperties() * `ConfigureCmsKit(...)` method is used to configure the entities of the CMS Kit module. -* `cmsKit.ConfigureBlog(...)` is used to configure the **Blog** entity of the CMS Kit module. You can add or update your extra properties on the **Blog** entity. +* CMS Kit provides configuration methods for `Blog`, `BlogPost`, `BlogFeature`, `MediaDescriptor`, `Page`, `Tag`, `Comment`, `MenuItem`, `CmsUser` and `GlobalResource`. -* `cmsKit.ConfigureBlogPost(...)` is used to configure the **BlogPost** entity of the CMS Kit module. You can add or update your extra properties of the **BlogPost** entity. +* The built-in MVC create and update forms consume extensions for blogs, blog posts, menu items, pages and tags. The Angular administration UI consumes object extensions and contributor callbacks for its comments, tags, pages, blogs, blog posts and menu screens. * You can also set some validation rules for the property that you defined. In the above sample, `RequiredAttribute` and `StringLengthAttribute` were added for the property named **"BlogPostDescription"**. -* When you define the new property, it will automatically add to **Entity**, **HTTP API**, and **UI** for you. - * Once you define a property, it appears in the create and update forms of the related entity. - * New properties also appear in the datatable of the related page. - +* Each helper exposes the module entity extension configuration for that type. Persistence and DTO propagation depend on the mappings registered by the installed CMS Kit packages. Automatic form and table rendering is available only on the MVC and Angular screens listed above. For other entities or custom screens, read the extra property from the DTO and render it explicitly. diff --git a/docs/en/modules/cms-kit/marked-items.md b/docs/en/modules/cms-kit/marked-items.md index bd0db306eb..7d51e518b3 100644 --- a/docs/en/modules/cms-kit/marked-items.md +++ b/docs/en/modules/cms-kit/marked-items.md @@ -18,15 +18,15 @@ you can also customize the marking icons shown in the toggling components. ## Enabling the Marked Item Feature -By default, CMS Kit features are disabled. Therefore, you need to enable the features you want, before starting to use it. You can use the [Global Feature](../../Global-Features.md) system to enable/disable CMS Kit features on development time. Alternatively, you can use the ABP Framework's [Feature System](https://docs.abp.io/en/abp/latest/Features) to disable a CMS Kit feature on runtime. +By default, CMS Kit features are disabled. Therefore, you need to enable the features you want before using them. You can use the [Global Feature](../../framework/infrastructure/global-features.md) system to enable or disable CMS Kit features at development time. Alternatively, you can use the ABP [Feature System](../../framework/infrastructure/features.md) to disable a CMS Kit feature at runtime. -> Check the ["How to Install" section of the CMS Kit Module documentation](Index.md#how-to-install) to see how to enable/disable CMS Kit features on development time. +> Check the ["How to Install" section of the CMS Kit Module documentation](index.md#how-to-install) to see how to enable or disable CMS Kit features at development time. ## Options Marking system provides a simple approach to define your entity type with mark types like favorite or starred. For example, if you want to use the marking system for products, you need to define an entity type named `product` with the icon name. -`CmsKitMarkedItemOptions` can be configured in YourModule.cs, in the `ConfigureServices` method of your [module](https://docs.abp.io/en/abp/latest/Module-Development-Basics). Example: +`CmsKitMarkedItemOptions` can be configured in `YourModule.cs`, in the `ConfigureServices` method of your [module](../../framework/architecture/modularity/basics.md). Example: ```csharp Configure(options => @@ -42,7 +42,7 @@ Configure(options => `CmsKitMarkedItemOptions` properties: -- `EntityTypes`: List of defined entity types (`CmsKitMarkedItemOptions`) in the marking system. +- `EntityTypes`: List of defined entity types (`MarkedItemEntityTypeDefinition`) in the marking system. `MarkedItemEntityTypeDefinition` properties: @@ -53,8 +53,8 @@ Configure(options => The marking system provides a toggle widget to allow users to add/remove the marks from an item. You can place the widget with the item as shown below: -``` csharp -@await Component.InvokeAsync(typeof (MarkedItemToggleViewComponent), new +```csharp +@await Component.InvokeAsync(typeof(MarkedItemToggleViewComponent), new { entityId = "...", entityType = "product", @@ -65,6 +65,20 @@ The marking system provides a toggle widget to allow users to add/remove the mar * `entityId` should be the unique id of the product, in this example. If you have a Product entity, you can use its Id here. * `needsConfirmation` An optional parameter to let the user confirm when removing the mark. +The widget can be rendered for anonymous visitors, but toggling a mark requires an authenticated user. The mark state is stored for the current user, entity type and entity ID. + +### Customizing MVC Marked Item Icons + +The MVC widget resolves the configured icon name through `CmsKitUiOptions.MarkedItemIcons`: + +```csharp +Configure(options => +{ + options.MarkedItemIcons[StandardMarkedItems.Favorite] = + new LocalizableIconDictionary("fa fa-heart text-danger"); +}); +``` + ### Filtering on Marked Items Users can filter their marked items to easily find their favorites. Here's how to utilize the `GetEntityIdsFilteredByUserAsync` method to filter the user's marked items within your repository queries: @@ -97,7 +111,7 @@ var queryable = (await GetDbSetAsync()) #### Aggregates -This module follows the [Entity Best Practices & Conventions](https://docs.abp.io/en/abp/latest/Best-Practices/Entities) guide. +This module follows the [Entity Best Practices & Conventions](../../framework/architecture/best-practices/entities.md) guide. ##### UserMarkedItem @@ -107,7 +121,7 @@ A user markedItem represents a user has marking on the item. #### Repositories -This module follows the [Repository Best Practices & Conventions](https://docs.abp.io/en/abp/latest/Best-Practices/Repositories) guide. +This module follows the [Repository Best Practices & Conventions](../../framework/architecture/best-practices/repositories.md) guide. Following custom repositories are defined for this feature: @@ -116,7 +130,7 @@ Following custom repositories are defined for this feature: #### Domain services -This module follows the [Domain Services Best Practices & Conventions](https://docs.abp.io/en/abp/latest/Best-Practices/Domain-Services) guide. +This module follows the [Domain Services Best Practices & Conventions](../../framework/architecture/best-practices/domain-services.md) guide. ##### Marked Item Manager @@ -134,13 +148,13 @@ This module follows the [Domain Services Best Practices & Conventions](https://d ##### Table / collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ##### Connection string This module uses `CmsKit` for the connection string name. If you don't define a connection string with this name, it fallbacks to the `Default` connection string. -See the [connection strings](https://docs.abp.io/en/abp/latest/Connection-Strings) documentation for details. +See the [connection strings](../../framework/fundamentals/connection-strings.md) documentation for details. #### Entity Framework Core @@ -153,4 +167,3 @@ See the [connection strings](https://docs.abp.io/en/abp/latest/Connection-String ##### Collections - **CmsUserMarkedItems** - diff --git a/docs/en/modules/cms-kit/menus.md b/docs/en/modules/cms-kit/menus.md index 429e9226e6..263db66c28 100644 --- a/docs/en/modules/cms-kit/menus.md +++ b/docs/en/modules/cms-kit/menus.md @@ -35,7 +35,15 @@ Menus page is used to manage dynamic public menus in the system. The created menu items will be visible on the public-web side, as shown below: -![cms-kit-public-menus](../../images//cmskit-module-menus-public.png) +![cms-kit-public-menus](../../images/cmskit-module-menus-public.png) + +### Menu Item Behavior + +Menu items form an ordered tree. Moving an item changes its parent and position, and CMS Kit normalizes the sibling order. Inactive root or child items are omitted from the public menu. + +A menu item can target either a URL or a CMS Kit page. When it targets a page, CMS Kit stores the page relationship and updates the menu URL after the page slug changes. It can also define an icon, link target, element ID, CSS class and a required permission. The public menu contributor omits permission-protected items for users who do not have the configured permission. + +The public contributor builds the named `CmsKit.Public` menu. CMS Kit registers that name as a main menu and caches the ordered menu-item DTOs in the distributed cache. Creating, updating, moving or deleting a menu item invalidates the cache. ## Internals @@ -76,7 +84,7 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ##### Table / collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ##### Connection string @@ -94,4 +102,4 @@ See the [connection strings](../../framework/fundamentals/connection-strings.md) ##### Collections -- CmsMenuItems \ No newline at end of file +- CmsMenuItems diff --git a/docs/en/modules/cms-kit/pages.md b/docs/en/modules/cms-kit/pages.md index b2f428d9cd..7c3b1b3a10 100644 --- a/docs/en/modules/cms-kit/pages.md +++ b/docs/en/modules/cms-kit/pages.md @@ -33,9 +33,30 @@ CMS Kit module admin side adds the following items to the main menu, under the * ![pages-edit](../../images/cmskit-module-pages-edit.png) -After you have created pages, you can set one of them as a *home page*. Then, whenever anyone navigates to your application's homepage, they see the dynamic content of the page that you have defined on this page. +After you have created pages, you can set one of them as the *home page*. CMS Kit keeps at most one home page for the current tenant. Setting or clearing it requires the `CmsKit.Pages.SetAsHomePage` permission. ![pages-page](../../images/cmskit-module-pages-page.png) -Also when you create a page, you can access the created page via `/{slug}` URL. +Each page has a `Draft` or `Publish` status. Only published pages are returned by the public application service. A published home page is rendered at `/`, while any other published page is rendered at `/{slug}`. Draft pages return a not-found result on these public routes. +The public page lookup is cached. The home page has a one-hour absolute cache lifetime, and CMS Kit invalidates the relevant entries when an administrator creates, updates, deletes or changes the home page. + +### Layout and Custom Resources + +The optional **Layout Name** selects a layout from the current theme. A page can also contain CSS in its **Style** field and JavaScript in its **Script** field. CMS Kit adds the style to the page's style section and the script to its script section. + +> Page content, style and script are trusted administrator input. The built-in public page renders the content with HTML enabled and XSS prevention disabled, and writes the style and script without sanitization. Grant the page create and update permissions only to users who are allowed to publish executable content. + +## Internals + +### Domain Layer + +`Page` is a multi-tenant aggregate root. `PageManager` normalizes and checks slugs, changes publication status and enforces the single-home-page rule. + +### Application Layer + +`PageAdminAppService` provides permission-gated management operations. `PagePublicAppService` exposes only published pages and manages the distributed page cache. + +### Database Providers + +The Entity Framework Core table and MongoDB collection are named `CmsPages` by default. Use `AbpCmsKitDbProperties` to change the common prefix or the relational schema. diff --git a/docs/en/modules/cms-kit/ratings.md b/docs/en/modules/cms-kit/ratings.md index 492af1c803..9c2460aeb0 100644 --- a/docs/en/modules/cms-kit/ratings.md +++ b/docs/en/modules/cms-kit/ratings.md @@ -55,6 +55,8 @@ The ratings system provides a rating widget to allow users send ratings to resou `entityType` was explained in the previous section. `entityId` should be the unique id of the product, in this example. If you have a Product entity, you can use its Id here. +Reading grouped rating counts is anonymous. Creating, changing or deleting a rating requires an authenticated user. A user has at most one rating for an entity; submitting another value updates that rating. The built-in range is one through five stars. + # Internals ## Domain Layer @@ -81,7 +83,7 @@ Following custom repositories are defined for this feature: This module follows the [Domain Services Best Practices & Conventions](../../framework/architecture/best-practices/domain-services.md) guide. -##### Reaction Manager +##### Rating Manager `RatingManager` is used to perform some operations for the `Rating` aggregate root. @@ -97,7 +99,7 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ##### Table / collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ##### Connection string @@ -115,4 +117,4 @@ See the [connection strings](../../framework/fundamentals/connection-strings.md) ##### Collections -- **CmsRatings** \ No newline at end of file +- **CmsRatings** diff --git a/docs/en/modules/cms-kit/reactions.md b/docs/en/modules/cms-kit/reactions.md index 1db865e287..ec573d130f 100644 --- a/docs/en/modules/cms-kit/reactions.md +++ b/docs/en/modules/cms-kit/reactions.md @@ -49,7 +49,7 @@ Configure(options => `CmsKitReactionOptions` properties: -- `EntityTypes`: List of defined entity types (`CmsKitReactionOptions`) in the reaction system. +- `EntityTypes`: List of defined entity types (`ReactionEntityTypeDefinition`) in the reaction system. `ReactionEntityTypeDefinition` properties: @@ -70,6 +70,20 @@ The reaction system provides a reaction widget to allow users to send reactions `entityType` was explained in the previous section. `entityId` should be the unique id of the product, in this example. If you have a Product entity, you can use its Id here. +The summary can be read anonymously. Creating or removing a reaction requires an authenticated user. A user can select each configured reaction at most once for the same entity; repeating the create operation doesn't create a duplicate record. + +### Customizing MVC Reaction Icons + +The MVC widget resolves each reaction name through `CmsKitUiOptions.ReactionIcons`. Replace an existing icon or register an icon for a custom reaction in the web project: + +```csharp +Configure(options => +{ + options.ReactionIcons[StandardReactions.Heart] = + new LocalizableIconDictionary("fa fa-heart text-danger"); +}); +``` + # Internals ## Domain Layer @@ -112,7 +126,7 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ##### Table / collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ##### Connection string diff --git a/docs/en/modules/cms-kit/tags.md b/docs/en/modules/cms-kit/tags.md index 7b57a49b9b..a3ed3a373a 100644 --- a/docs/en/modules/cms-kit/tags.md +++ b/docs/en/modules/cms-kit/tags.md @@ -149,7 +149,7 @@ This module follows the [Domain Services Best Practices & Conventions](../../fra ##### Table / Collection prefix & schema -All tables/collections use the `Cms` prefix by default. Set static properties on the `CmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). +All tables/collections use the `Cms` prefix by default. Set static properties on the `AbpCmsKitDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). ##### Connection string