feat(sdk-angular): Improve documentation in @dotcms/angular and angul…

…ar-example (#29884) ### Proposed Changes * Removed unused code * Moved some folders to improve code reading * Updated README in `@dotcms/angular` and `examples/angular` Note: I haven't updated the version number of the libs yet, I'll do it before the merge to avoid conflicts --------- Co-authored-by: Kevin Davila <[email protected]>
dotCMS · Sep 6, 2024 · acdc068 · acdc068
1 parent 90d78fc
commit acdc068
Show file tree

Hide file tree

Showing 35 changed files with 568 additions and 197 deletions.
diff --git a/core-web/libs/sdk/angular/README.md b/core-web/libs/sdk/angular/README.md
@@ -1,17 +1,31 @@
 # @dotcms/angular
 
-`@dotcms/angular` is the official set of Angular components, services and resolver designed to work seamlessly with dotCMS, making it easy to render dotCMS pages an use the page builder
+`@dotcms/angular` is the official Angular library designed to work seamlessly with dotCMS. This library simplifies the process of rendering dotCMS pages and integrating with the [Universal Visual Editor](dotcms.com/docs/latest/universal-visual-editor) in your Angular applications.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#provider-setup)
+  - [Provider Setup](#provider-setup)
+  - [Client Usage](#client-usage)
+- [Components](#components)
+  - [DotcmsLayoutComponent](#dotcmslayoutcomponent)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Licensing](#licensing)
 
 ## Features
 
--   A collection of  Angular components, services and resolver  tailored to render  
-    dotCMS pages.
--   Streamlined integration with dotCMS page editor.
--   Improved development experience with comprehensive TypeScript typings.
+- A set of Angular components developer for dotCMS page rendering and editor integration.
+- Enhanced development workflow with full TypeScript support.
+- Optimized performance for efficient rendering of dotCMS pages in Angular applications.
+- Flexible customization options to adapt to various project requirements.
 
 ## Installation
 
-Install the package via npm:
+Install the package using npm:
 
 ```bash
 npm install @dotcms/angular
@@ -23,111 +37,147 @@ Or using Yarn:
 yarn add @dotcms/angular
 ```
 
-## Provider
-```
+## Configutarion
+### Provider Setup
+We need to provide the information of our dotCMS instance
+
+```javascript
+
+import { ClientConfig } from '@dotcms/client';
+
 const DOTCMS_CLIENT_CONFIG: ClientConfig = {
     dotcmsUrl: environment.dotcmsUrl,
     authToken: environment.authToken,
     siteId: environment.siteId
 };
 ```
-Add the dotcms config in the Angular app ApplicationConfig 
-```
+And add this config in the Angular app ApplicationConfig.
+
+`src/app/app.config.ts`
+```javascript
+import { InjectionToken } from '@angular/core';
+import { ClientConfig, DotCmsClient } from '@dotcms/client';
+
+export const DOTCMS_CLIENT_TOKEN = new InjectionToken<DotCmsClient>('DOTCMS_CLIENT');
+
 export const appConfig: ApplicationConfig = {
     providers: [
-        provideDotcmsClient(DOTCMS_CLIENT_CONFIG),
         provideRouter(routes),
+        {
+            provide: DOTCMS_CLIENT_TOKEN,
+            useValue: DotCmsClient.init(DOTCMS_CLIENT_CONFIG),
+        }
     ],
 };
 ```
-## Resolver
-```javascript
-export const routes: Routes = [
-  {
-    path: '**',
-    resolve: {
-      // This should be called `context`.
-      context: DotCMSPageResolver,
-    },
-    component: DotCMSPagesComponent,
-    runGuardsAndResolvers: 'always' // Run the resolver on every navigation. Even if the URL hasn't changed.
-  },
-];
-```
+This way, we will have access to `DOTCMS_CLIENT_TOKEN` from anywhere in our application.
 
-Then, in your component, you can read the data using
+### Client Usage
+To interact with the client and obtain information from, for example, our pages
 
 ```javascript
-protected readonly context = signal(null);
-
-ngOnInit() {
-    // Get the context data from the route
-    this.route.data.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(data => {
-        this.context.set(data['context']);
-    });
-}
+private readonly client = inject(DOTCMS_CLIENT_TOKEN);
+
+this.client.page
+    .get({ ...pageParams })
+    .then((response) => {
+        // Use your response 
+    })
+    .catch((e) => {
+      const error: PageError = {
+        message: e.message,
+        status: e.status,
+      };
+      // Use the error response
+    })
 ```
-## Components
+For more information to how to use DotCms Client, you can visit the [documentation](https://github.com/dotCMS/core/blob/master/core-web/libs/sdk/client/README.md)
 
-### `DotcmsLayoutComponent`
+## DotCMS Page API
 
-A component that renders a layout for a dotCMS page.
+The `DotcmsLayoutComponent` requires a `DotCMSPageAsset` object to be passed in to it. This object represents a dotCMS page and can be fetched using the `@dotcms/client` library.
 
-#### Inputs
+- [DotCMS Official Angular Example](https://github.com/dotCMS/core/tree/master/examples/angular)
+- [`@dotcms/client` documentation](https://www.npmjs.com/package/@dotcms/client)
+- [Page API documentation](https://dotcms.com/docs/latest/page-api)
 
--   **entity**: The context for a dotCMS page.
--   **components**: An object with the relation of contentlets and the component to render each.
+## Components
 
+### DotcmsLayoutComponent
 
-#### Usage
+The `DotcmsLayoutComponent` is a crucial component for rendering dotCMS page layouts in your Angular application.
 
-```javascript
-    <dotcms-layout [entity]="pageAsset" [components]="components()" />
-
-    DYNAMIC_COMPONENTS: { [key: string]: DynamicComponentEntity } = {
-    Activity: import('../pages/content-types/activity/activity.component').then(
-        (c) => c.ActivityComponent,
-    ),
-    Banner: import('../pages/content-types/banner/banner.component').then(
-        (c) => c.BannerComponent,
-    ),
-    Image: import('../pages/content-types/image/image.component').then(
-        (c) => c.ImageComponent,
-    ),
-    webPageContent: import(
-        '../pages/content-types/web-page-content/web-page-content.component'
-    ).then((c) => c.WebPageContentComponent),
-    Product: import('../pages/content-types/product/product.component').then(
-        (c) => c.ProductComponent,
-    ),
+#### Inputs
+
+| Name         | Type                 | Description                                                           |
+|--------------|----------------------|-----------------------------------------------------------------------|
+| `pageAsset`  | `DotCMSPageAsset`    | The object representing a dotCMS page from PageAPI response.          |
+| `components` | `DotCMSPageComponent`| An object mapping contentlets to their respective render components.  |
+| `editor`     | `EditorConfig`       | Configuration for data fetching in Edit Mode.                         |
+
+#### Usage Example
+
+In your component file (e.g., `pages.component.ts`):
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { DotCMSPageComponent, EditorConfig } from '@dotcms/angular';
+
+@Component({
+    selector: 'app-pages',
+    templateUrl: './pages.component.html',
+})
+export class PagesComponent {
+    DYNAMIC_COMPONENTS: DotCMSPageComponent = {
+        Activity: import('../pages/content-types/activity/activity.component').then(
+            (c) => c.ActivityComponent
+        ),
+        Banner: import('../pages/content-types/banner/banner.component').then(
+            (c) => c.BannerComponent
+        ),
+        // Add other components as needed
     };
+
+    components = signal(this.DYNAMIC_COMPONENTS);
+    editorConfig = signal<EditorConfig>({ params: { depth: 2 } });
+
+    // Assume pageAsset is fetched or provided somehow
+    pageAsset: DotCMSPageAsset;
+}
+```
 
-components = signal(DYNAMIC_COMPONENTS);
+In your template file (e.g., `pages.component.html`):
+
+```html
+<dotcms-layout 
+    [pageAsset]="pageAsset" 
+    [components]="components()" 
+    [editor]="editorConfig()" 
+/>
 ```
 
-## Contributing
+This setup allows for dynamic rendering of different content types on your dotCMS pages.
 
-GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the [dotCMS Contributor's Agreement](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
+## Best Practices
 
-## Licensing
+1. **Lazy Loading**: Use dynamic imports for components to improve initial load times.
+2. **Error Handling**: Implement robust error handling for API calls and component rendering.
+3. **Type Safety**: Leverage TypeScript's type system to ensure proper usage of dotCMS structures.
+4. **Performance Optimization**: Monitor and optimize the performance of rendered components.
 
-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 a number of enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://dotcms.com/cms-platform/features).
+## Troubleshooting
 
-## Support
+If you encounter issues:
 
-If you need help or have any questions, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
+1. Ensure all dependencies are correctly installed and up to date.
+2. Verify that your dotCMS configuration (URL, auth token, site ID) is correct.
+3. Check the browser console for any error messages.
+4. Refer to the [dotCMS documentation](https://dotcms.com/docs/) for additional guidance.
 
-## Documentation
+## Contributing
 
-Always refer to the official [DotCMS documentation](https://www.dotcms.com/docs/latest/) for comprehensive guides and API references.
+GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the [dotCMS Contributor's Agreement](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
 
-## Getting Help
+## Licensing
 
-| Source          | Location                                                            |
-| --------------- | ------------------------------------------------------------------- |
-| Installation    | [Installation](https://dotcms.com/docs/latest/installation)         |
-| Documentation   | [Documentation](https://dotcms.com/docs/latest/table-of-contents)   |
-| Videos          | [Helpful Videos](http://dotcms.com/videos/)                         |
-| Forums/Listserv | [via Google Groups](https://groups.google.com/forum/#!forum/dotCMS) |
-| Twitter         | @dotCMS                                                             |
-| Main Site       | [dotCMS.com](https://dotcms.com/)                                   |
+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 a number of enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://dotcms.com/cms-platform/features).
diff --git a/core-web/libs/sdk/angular/package.json b/core-web/libs/sdk/angular/package.json
@@ -1,11 +1,11 @@
 {
   "name": "@dotcms/angular",
-  "version": "0.0.1-alpha.37",
+  "version": "0.0.1-alpha.38",
   "peerDependencies": {
     "@angular/common": "^17.1.0",
     "@angular/core": "^17.1.0",
     "@angular/router": "^17.1.0",
-    "@dotcms/client": "0.0.1-alpha.37",
+    "@dotcms/client": "0.0.1-alpha.38",
     "@tinymce/tinymce-angular": "^8.0.0",
     "rxjs": "^7.8.0"
   },

diff --git a/core-web/libs/sdk/angular/src/lib/components/no-component/no-component.component.ts b/core-web/libs/sdk/angular/src/lib/components/no-component/no-component.component.ts
@@ -3,8 +3,10 @@ import { ChangeDetectionStrategy, Component, HostBinding, Input } from '@angular
 import { DotCMSContentlet } from '../../models';
 
 /**
- * This is part of the Angular SDK.
- * This is a component for the `NoComponentComponent` component.
+ * This component is responsible to display a message when there is no component for a contentlet.
+ *
+ * @export
+ * @class NoComponent
  */
 @Component({
     selector: 'dotcms-no-component',
@@ -16,6 +18,14 @@ import { DotCMSContentlet } from '../../models';
     changeDetection: ChangeDetectionStrategy.OnPush
 })
 export class NoComponent {
+    /**
+     * The contentlet object containing content data.
+     * The component displays a message based on the content type of this contentlet.
+     */
     @Input() contentlet!: DotCMSContentlet;
+
+    /**
+     * The data-testid attribute used for identifying the component during testing.
+     */
     @HostBinding('attr.data-testid') testId = 'no-component';
 }
diff --git a/core-web/libs/sdk/angular/src/lib/layout/column/column.component.ts b/core-web/libs/sdk/angular/src/lib/layout/column/column.component.ts
@@ -4,6 +4,13 @@ import { DotPageAssetLayoutColumn } from '../../models';
 import { getPositionStyleClasses } from '../../utils';
 import { ContainerComponent } from '../container/container.component';
 
+/**
+ * This component is responsible to display a column with containers.
+ *
+ * @export
+ * @class ColumnComponent
+ * @implements {OnInit}
+ */
 @Component({
     selector: 'dotcms-column',
     standalone: true,
@@ -17,7 +24,19 @@ import { ContainerComponent } from '../container/container.component';
     changeDetection: ChangeDetectionStrategy.OnPush
 })
 export class ColumnComponent implements OnInit {
+    /**
+     * The column object containing the containers.
+     *
+     * @type {DotPageAssetLayoutColumn}
+     * @memberof ColumnComponent
+     */
     @Input() column!: DotPageAssetLayoutColumn;
+
+    /**
+     * The data-testid attribute used for identifying the component during testing.
+     *
+     * @memberof ColumnComponent
+     */
     @HostBinding('class') containerClasses = '';
 
     ngOnInit() {