SDK: Angular Example

This example project demonstrates how to build manageable dotCMS pages headlessly using the Angular framework. It showcases the integration between dotCMS and Angular, providing a practical implementation of content-driven web applications.

Prerequisites#

Before you begin, ensure you have the following:

1. Access to a dotCMS instance (you can use https://demo.dotcms.com if you don't have your own)
2. A valid AUTH token for the target dotCMS instance (How to create an API token)
3. Node.js (version 18 or higher) and npm installed
4. A terminal application
5. A code editor of your choice

Getting Started#

Obtaining the Example Code#

You can get the code in two ways:

1. Direct download:

   https://github.com/dotCMS/core/tree/main/examples/angular

2. Using Git sparse checkout:

   git clone -n --depth=1 --filter=tree:0 https://github.com/dotCMS/core
   cd core
   git sparse-checkout set --no-cone examples/angular
   git checkout

The example files will be in the examples/angular folder.

Configuration#

To configure the Angular app to use your dotCMS instance:

1. Open the project folder in your code editor

2. Navigate to src/environments

3. Open environment.development.ts and update the following variables:

   • authToken: Your dotCMS auth token
   • dotcmsUrl: URL of your dotCMS instance (e.g., https://demo.dotcms.com)

   export const environment = {
     production: false,
     authToken: 'YOUR_AUTH_TOKEN_HERE',
     dotcmsUrl: 'https://demo.dotcms.com',
   };

⚠️ Security Note: Ensure that the authToken used here has read-only permissions to minimize security risks in client-side applications.

Running the Application#

Once configured, follow these steps to run the app:

1. Open a terminal in the project root directory
2. Install dependencies: npm install
3. Start the development server: ng serve
4. Open your browser and navigate to http://localhost:4200

🎉 Congratulations! Your dotCMS Angular example is now running.

Note: When accessing localhost:4200/about, ensure that the /about page exists in your dotCMS instance.

Project Structure#

.
└── src/
    └── app/
        ├── content-types/
        │   ├── activity
        │   ├── banner
        │   ├── product
        │   └── ...other-content-types
        ├── pages/
        │   ├── components
        │   └── services
        └── shared/
            └── contentlets-wrapper/
                └── contentlet/  

• content-types/: Components for rendering specific dotCMS content types
• pages/: Main application component for rendering pages based on their path and pageAsset
• shared/: Reusable components
  • contentlets-wrapper/: Component for displaying lists of Contentlets
    • contentlet/: Component for rendering individual Contentlets

Key Features#

How dotCMS Routes Pages#

dotCMS allows a single page to be accessed via multiple URL paths (e.g., / and /index for the same "Home" page). This flexibility means your Angular application needs to handle these variations.

To ensure all paths to the same content are properly managed and to prevent 404/500 errors, we recommend using a catch-all route strategy in Angular.

How to Implement in Angular:

Configure a wildcard route (**) as the last route in your Angular application's routing configuration. This route will capture any undefined paths, allowing you to fetch content from dotCMS based on the full URL.

You can learn more about Angular routing strategies here

Handling Vanity URLs#

This example demonstrates how to integrate dotCMS Vanity URLs with Angular routing. Vanity URLs in dotCMS provide alternative paths to internal or external URLs, enhancing site maintenance and SEO.

For implementation details, refer to the DotCMSPagesComponent in the example code, which handles routing and Vanity URL redirection.

Universal Visual Editor#

To enable the Universal Visual Editor in dotCMS, follow these steps:

1. In your dotCMS instance, navigate to the "Apps" page
2. Find the "UVE - Universal Visual Editor" app and click on it
3. Then locate the site where you want to enable the UVE and click on it
4. In the configuration field add the following:

{
  "config": [
    {
      "pattern": ".*",
      "url": "http://localhost:4200"
    }
  ]
}

1. Click on the "Save" button to save the changes.
2. Now edit any page and you will see the UVE.

If you want more information about the UVE, please refer to the dotCMS UVE Documentation.

Troubleshooting#

If you encounter issues while setting up or running the dotCMS Angular example, here are some common problems and their solutions:

rm -rf node_modules && rm package-lock.json && npm install

ng serve

ng cache clean
ng build --configuration=development
ng serve

If you continue to experience issues after trying these solutions, please check the dotCMS documentation or reach out to the dotCMS community for further assistance.

Further Resources#

• Angular CLI Documentation
• dotCMS Documentation
• dotCMS REST API Authentication

For more assistance with Angular, use ng help or visit the Angular CLI Overview and Command Reference page.