@dotcms/angular 1.6.0 → 1.7.0

package/README.md

@@ -1,15 +1,18 @@
 # dotCMS Angular SDK
 
-The `@dotcms/angular` SDK is the DotCMS official Angular library. It empowers Angular developers to build powerful, editable websites and applications in no time.
+The `@dotcms/angular` SDK is the official dotCMS Angular library. It empowers Angular developers to build powerful, editable websites and applications in no time.
 
 ## Table of Contents
 
 -   [Prerequisites & Setup](#prerequisites--setup)
-    -   [dotCMS Instance](#dotcms-instance)
-    -   [Create a dotCMS API Key](#create-a-dotcms-api-key)
+    -   [Get a dotCMS Environment](#get-a-dotcms-environment)
     -   [Configure The Universal Visual Editor App](#configure-the-universal-visual-editor-app)
+    -   [Create a dotCMS API Key](#create-a-dotcms-api-key)
     -   [Installation](#installation)
-    -   [dotCMS Client Configuration](#dotcms-client-configuration)
+-   [Configuration](#configuration)
+    -   [Basic Configuration](#basic-configuration)
+    -   [Custom HTTP Client Configuration](#custom-http-client-configuration)
+    -   [Using the Client](#using-the-client)
     -   [Proxy Configuration for Static Assets](#proxy-configuration-for-static-assets)
     -   [Using dotCMS Images with Angular's `NgOptimizedImage` Directive (Recommended)](#using-dotcms-images-with-angulars-ngoptimizedimage-directive-recommended)
 -   [Quickstart: Render a Page with dotCMS](#quickstart-render-a-page-with-dotcms)
@@ -17,7 +20,7 @@ The `@dotcms/angular` SDK is the DotCMS official Angular library. It empowers An
 -   [SDK Reference](#sdk-reference)
     -   [DotCMSLayoutBody](#dotcmslayoutbody)
     -   [DotCMSEditableText](#dotcmseditabletext)
-    -   [DotCMSBlockEditorRenderer](#dotcmsblockeditorrenderer)
+    -   [DotCMSBlockEditorRendererNative](#dotcmsblockeditorrenderernative)
     -   [DotCMSShowWhen](#dotcmsshowwhen)
     -   [DotCMSEditablePageService](#dotcmseditablepageservice)
 -   [Troubleshooting](#troubleshooting)
@@ -160,7 +163,7 @@ export class MyComponent {
 
   ngOnInit() {
     this.dotcmsClient.page
-        .get({ url: '/about-us' })
+        .get('/about-us')
         .then(({ pageAsset }) => {
             console.log(pageAsset);
         });
@@ -345,13 +348,15 @@ The following example demonstrates how to quickly set up a basic dotCMS page ren
 
 ```typescript
 // /src/app/pages/dotcms-page.component.ts
-import { Component, signal } from '@angular/core';
+import { Component, inject, OnInit, signal } from '@angular/core';
 
-import { DotCMSLayoutBody, DotCMSEditablePageService} from '@dotcms/angular';
+import {
+    DotCMSClient,
+    DotCMSEditablePageService,
+    DotCMSLayoutBodyComponent
+} from '@dotcms/angular';
 import { getUVEState } from '@dotcms/uve';
-import { DotCMSPageAsset } from '@dotcms/types';
-
-import { DOTCMS_CLIENT_TOKEN } from './app.config';
+import { DotCMSPageAsset, DotCMSPageResponse } from '@dotcms/types';
 
 const DYNAMIC_COMPONENTS = {
     Blog: import('./blog.component').then(c => c.BlogComponent),
@@ -361,12 +366,12 @@ const DYNAMIC_COMPONENTS = {
 @Component({
     selector: 'app-pages',
     standalone: true,
-    imports: [DotCMSLayoutBody],
-    providers: [DotCMSEditablePageService, DOTCMS_CLIENT_TOKEN],
+    imports: [DotCMSLayoutBodyComponent],
+    providers: [DotCMSEditablePageService],
     template: `
         @if (pageAsset()) {
             <dotcms-layout-body
-                [pageAsset]="pageAsset"
+                [page]="pageAsset()!"
                 [components]="components()"
             />
         } @else {
@@ -374,29 +379,29 @@ const DYNAMIC_COMPONENTS = {
         }
     `
 })
-export class PagesComponent {
-    private readonly dotCMSClient: DotCMSClient = inject(DOTCMS_CLIENT_TOKEN);
+export class PagesComponent implements OnInit {
+    private readonly dotCMSClient = inject(DotCMSClient);
     private readonly editablePageService = inject(DotCMSEditablePageService);
     readonly components = signal(DYNAMIC_COMPONENTS);
     readonly pageAsset = signal<DotCMSPageAsset | null>(null);
 
     ngOnInit() {
         this.dotCMSClient.page
-            .get({ url: '/my-page' })
-            .then(({ pageAsset }) => {
-                if(getUVEState()) {
-                   this.#subscribeToPageUpdates(response);
-                   return;
-               }
+            .get('/my-page')
+            .then((pageResponse) => {
+                if (getUVEState()) {
+                    this.#subscribeToPageUpdates(pageResponse);
+                    return;
+                }
 
-                this.pageAsset.set(pageAsset);
+                this.pageAsset.set(pageResponse.pageAsset);
             });
     }
 
-    #subscribeToPageUpdates(response: DotCMSPageResponse) {
+    #subscribeToPageUpdates(pageResponse: DotCMSPageResponse) {
         this.editablePageService
-            .listen(response)
-            .subscribe({ pageAsset } => this.pageAsset.set(pageAsset));
+            .listen(pageResponse)
+            .subscribe(({ pageAsset }) => this.pageAsset.set(pageAsset));
     }
 }
 ```
@@ -433,26 +438,25 @@ All components, directives, and services should be imported from `@dotcms/angula
 #### Usage
 
 ```typescript
-import { Component, signal } from '@angular/core';
+import { Component, inject, OnInit, signal } from '@angular/core';
 import { DotCMSPageAsset } from '@dotcms/types';
-import { DotCMSLayoutBody } from '@dotcms/angular';
-
-import { DOTCMS_CLIENT_TOKEN } from './app.config';
+import { DotCMSClient, DotCMSLayoutBodyComponent } from '@dotcms/angular';
 
 @Component({
+    imports: [DotCMSLayoutBodyComponent],
     template: `
-        <dotcms-layout-body [page]="pageAsset()" [components]="components()" mode="development" />
+        <dotcms-layout-body [page]="pageAsset()!" [components]="components()" mode="development" />
     `
 })
-export class MyPageComponent {
+export class MyPageComponent implements OnInit {
     protected readonly components = signal({
         Blog: import('./blog.component').then((c) => c.BlogComponent)
     });
     protected readonly pageAsset = signal<DotCMSPageAsset | null>(null);
-    private readonly dotCMSClient = inject(DOTCMS_CLIENT_TOKEN);
+    private readonly dotCMSClient = inject(DotCMSClient);
 
     ngOnInit() {
-        this.dotCMSClient.page.get({ url: '/my-page' }).then(({ pageAsset }) => {
+        this.dotCMSClient.page.get('/my-page').then(({ pageAsset }) => {
             this.pageAsset.set(pageAsset);
         });
     }
@@ -491,7 +495,7 @@ const DYNAMIC_COMPONENTS = {
 |--------------|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `contentlet` | `T extends DotCMSBasicContentlet`  | ✅       | The contentlet containing the editable field                                                                                                   |
 | `fieldName`  | `keyof T`                     | ✅       | Name of the field to edit, which must be a valid key of the contentlet type `T`                                                                |
-| `mode`       | `'plain' \| 'full'` | ❌       | `plain` (default): Support text editing. Does not show style controls. <br/> `full`: Enables a bubble menu with style options. This mode only works with [`WYSIWYG` fields](https://dev.dotcms.com/docs/the-wysiwyg-field). |
+| `mode`       | `'plain' \| 'full'` | ❌       | `plain` (default): Supports text editing. Does not show style controls. <br/> `full`: Enables a bubble menu with style options. This mode only works with [`WYSIWYG` fields](https://dev.dotcms.com/docs/the-wysiwyg-field). |
 | `format`     | `'text' \| 'html'`  | ❌       | `text` (default): Renders HTML tags as plain text <br/> `html`: Interprets and renders HTML markup                                                                                                                          |
 
 #### Usage
@@ -535,24 +539,30 @@ export class MyBannerComponent {
 #### Editor Integration
 
 -   Detects UVE edit mode and enables inline TinyMCE editing
--   Triggers a `Save` [workflow action](https://dev.dotcms.com/docs/workflows) on blur without needing full content dialog.
+-   Triggers a `Save` [workflow action](https://dev.dotcms.com/docs/workflows) on blur without needing the full content dialog.
+
+### DotCMSBlockEditorRendererNative
+
+`DotCMSBlockEditorRendererNative` is the recommended renderer for [Block Editor](https://dev.dotcms.com/docs/block-editor) content. It emits **clean semantic HTML** — `<ul><li><p>…</p></li></ul>` — with no custom wrapper elements between semantic tags.
 
-### DotCMSBlockEditorRenderer
+> The original `DotCMSBlockEditorRenderer` is deprecated and retained for backward compatibility. See the component's TSDoc and [`MIGRATION.md`](./MIGRATION.md#migrating-to-the-semantic-block-editor-renderer) for the migration path — it's a one-line swap.
 
-`DotCMSBlockEditorRenderer` is a component for rendering [Block Editor](https://dev.dotcms.com/docs/block-editor) content from dotCMS with support for custom block renderers.
+#### Why it matters
+
+The host element is the real semantic tag (`<ul>`, `<li>`, `<p>`, `<h1>`–`<h6>`, ...) and recursion is done through `ng-template` outlets that render as HTML comment nodes (invisible to the accessibility tree), so `<li>` stays a true DOM child of `<ul>` — the relationship the HTML spec and assistive technology require, and that accessibility scanners flag when broken. This applies inside table cells and grid columns too: `<td><ul><li>…` stays intact.
 
 | Input             | Type                 | Required | Description                                                                                                |
 |-------------------|----------------------|----------|------------------------------------------------------------------------------------------------------------|
-| `blocks`          | `BlockEditorContent` | ✅       | The [Block Editor](https://dev.dotcms.com/docs/block-editor) content to render                             |
-| `customRenderers` | `CustomRenderer`     | ❌       | Custom rendering functions for specific [block types](https://dev.dotcms.com/docs/block-editor#BlockTypes) |
-| `className`       | `string`            | ❌       | CSS class to apply to the container                                                                        |
-| `style`           | `CSSProperties`      | ❌       | Inline styles for the container                                                                            |
+| `blocks`          | `BlockEditorNode`               | ✅       | The [Block Editor](https://dev.dotcms.com/docs/block-editor) content to render                             |
+| `customRenderers` | `CustomRenderer`                | ❌       | Custom rendering functions for specific [block types](https://dev.dotcms.com/docs/block-editor#BlockTypes) |
+| `class`           | `string`                        | ❌       | CSS class to apply to the container                                                                        |
+| `style`           | `string \| Record<string, string>` | ❌   | Inline styles for the container                                                                            |
 
 #### Usage
 
 ```typescript
 import { DotCMSBasicContentlet } from '@dotcms/types';
-import { DotCMSBlockEditorRenderer } from '@dotcms/angular';
+import { DotCMSBlockEditorRendererNativeComponent } from '@dotcms/angular';
 
 const CUSTOM_RENDERERS = {
     customBlock: import('./custom-block.component').then((c) => c.CustomBlockComponent),
@@ -561,9 +571,9 @@ const CUSTOM_RENDERERS = {
 
 @Component({
     selector: 'app-your-component',
-    imports: [DotCMSShowWhen],
+    imports: [DotCMSBlockEditorRendererNativeComponent],
     template: `
-        <dotcms-block-editor-renderer
+        <dotcms-block-editor-renderer-native
             [blocks]="contentlet.myBlockEditorField"
             [customRenderers]="customRenderers()" />
     `
@@ -576,12 +586,8 @@ export class MyBannerComponent {
 
 #### Recommendations
 
--   Should not be used with [`DotCMSEditableText`](#dotcmseditabletext)
--   Take into account the CSS cascade can affect the look and feel of your blocks.
--   `DotCMSBlockEditorRenderer` only works with [Block Editor fields](https://dev.dotcms.com/docs/block-editor). For other fields, use [`DotCMSEditableText`](#dotcmseditabletext).
-
-📘 For advanced examples, customization options, and best practices, refer to the [DotCMSBlockEditorRenderer README](https://github.com/dotCMS/core/tree/master/core-web/libs/sdk/angular/src/lib/components/DotCMSBlockEditorRenderer).
-
+-   Should not be used with [`DotCMSEditableText`](#dotcmseditabletext).
+-   Keep in mind that the CSS cascade can affect the look and feel of your blocks.
 
 ### DotCMSShowWhen
 
@@ -594,20 +600,24 @@ export class MyBannerComponent {
 #### Usage
 
 ```typescript
+import { Component } from '@angular/core';
+
+import { DotCMSShowWhenDirective } from '@dotcms/angular';
 import { UVE_MODE } from '@dotcms/types';
-import { DotCMSShowWhen } from '@dotcms/angular';
 
 @Component({
     selector: 'app-your-component',
-    imports: [DotCMSShowWhen],
+    imports: [DotCMSShowWhenDirective],
     template: `
-        <div *dotCMSShowWhen="UVE_MODE.EDIT">Only visible in edit mode</div>
+        <div *dotCMSShowWhen="uveMode.EDIT">Only visible in edit mode</div>
     `
 })
-export class YourComponent {}
+export class YourComponent {
+    readonly uveMode = UVE_MODE;
+}
 ```
 
-📚 Learn more about the `UVE_MODE` enum in the [dotCMS UVE Package Documentation](https://dev.dotcms.com/docs/uve).
+📚 Learn more about the `UVE_MODE` enum in the [dotCMS UVE Package Documentation](https://dev.dotcms.com/docs/universal-visual-editor).
 
 ### DotCMSEditablePageService
 
@@ -639,14 +649,22 @@ import { Component, OnDestroy, OnInit, signal, inject } from '@angular/core';
 
 import { getUVEState } from '@dotcms/uve';
 import { DotCMSPageAsset } from '@dotcms/types';
-import { DotCMSLayoutBody, DotCMSEditablePageService, DotCMSClient } from '@dotcms/angular';
+import {
+    DotCMSClient,
+    DotCMSEditablePageService,
+    DotCMSLayoutBodyComponent
+} from '@dotcms/angular';
+
+const DYNAMIC_COMPONENTS = {
+    Blog: import('./blog.component').then((c) => c.BlogComponent)
+};
 
 @Component({
-    imports: [DotCMSLayoutBody],
+    imports: [DotCMSLayoutBodyComponent],
     providers: [DotCMSEditablePageService],
     template: `
         @if (pageAsset()) {
-            <dotcms-layout-body [page]="pageAsset()" [components]="components()" />
+            <dotcms-layout-body [page]="pageAsset()!" [components]="components()" />
         } @else {
             <div>Loading...</div>
         }
@@ -654,12 +672,13 @@ import { DotCMSLayoutBody, DotCMSEditablePageService, DotCMSClient } from '@dotc
 })
 export class PageComponent implements OnInit, OnDestroy {
     private subscription?: Subscription;
-    private readonly dotCMSClient = inject(DOTCMS_CLIENT_TOKEN);
+    private readonly dotCMSClient = inject(DotCMSClient);
     private readonly editablePageService = inject(DotCMSEditablePageService);
+    readonly components = signal(DYNAMIC_COMPONENTS);
     readonly pageAsset = signal<DotCMSPageAsset | null>(null);
 
     ngOnInit() {
-        this.dotCMSClient.page.get({ url: '/about-us' }).then((pageResponse) => {
+        this.dotCMSClient.page.get('/about-us').then((pageResponse) => {
             // Only subscribe to changes when in the editor
             if (getUVEState()) {
                 this.subscription = this.editablePageService
@@ -779,7 +798,7 @@ We offer multiple channels to get help with the dotCMS Angular SDK:
 -   **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
 -   **Community Forum**: Join our [community discussions](https://community.dotcms.com/) to ask questions and share solutions.
 -   **Stack Overflow**: Use the tag `dotcms-angular` when posting questions.
--   **Enterprise Support**: Enterprise customers can access premium support through the [dotCMS Support Portal](https://helpdesk.dotcms.com/support/).
+-   **Enterprise Support**: Enterprise customers can access premium support through the [dotCMS Support Portal](https://www.dotcms.com/support).
 
 When reporting issues, please include:
 
@@ -844,8 +863,8 @@ provideDotCMSClient({
 
 ## Licensing
 
-dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://www.dotcms.com/cms-platform/features).
+dotCMS is available under either the [Business Source License 1.1 (BSL)](https://www.dotcms.com/bsl) or a commercial license.
 
-This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).
+Under the BSL, dotCMS can be used at no cost by individual developers, small businesses or agencies under $5M in total finances, and by larger organizations in non-production environments. Every BSL release automatically converts to GPL v3 four years after its release date. For full terms and FAQs, visit [dotcms.com/bsl](https://www.dotcms.com/bsl) and [dotcms.com/bsl-faq](https://www.dotcms.com/bsl-faq).
 
-[Learn more ](https://www.dotcms.com)at [dotcms.com](https://www.dotcms.com).
+Production use in larger organizations, along with access to managed cloud, SLAs, support, and enterprise capabilities, is available under a commercial license from dotCMS. For details on commercial plans, features, and support options, see [dotcms.com/pricing](https://www.dotcms.com/pricing).