dotCMS logodotCMS logo

SDK: Angular Example

This Angular project demonstrates how to implement editable dotCMS pages using Angular Client-Side Rendering (CSR). It showcases best practices for integrating dotCMS content management with Angular's client-side rendering capabilities.

Content Management Features#

  • Dynamic Page Rendering: Automatic page generation from dotCMS routing
  • Content Type Components: 10+ pre-built components for common content types
  • Block Editor Integration: Rich text content with dotCMS Block Editor
  • Image Management: Optimized image handling with dotCMS image API
  • GraphQL Queries: Advanced content filtering and search capabilities

Visual Editing (UVE)#

  • Live Content Editing: Edit content directly in the browser
  • Visual Page Builder: In-context editing experience
  • Contentlet Editing: Direct editing of individual content pieces

Technical Integration#

  • Client-Side Rendering: Full CSR with Angular standalone components
  • Type Safety: Complete TypeScript interfaces for all content types
  • Modern Angular: Using Angular signals, control flow, and latest patterns

For the official Angular documentation, visit: Angular Documentation

Prerequisites#

Getting Started#

Setup#

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

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:

    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#

Development Server#

ng serve

Navigate to http://localhost:4200/. The application will automatically reload when source files are modified.

Building for Production#

ng build

Build artifacts are stored in the dist/ directory with performance optimizations.

Running Tests#

ng test
ng e2e

Architecture Overview#

Routing Strategy#

The application uses a strategic combination of catch-all and specific routing in app.routes.ts:

  • Specific routes: Custom pages like /blog/post/:slug, /activities/:slug
  • Catch-all route (**): Handles all dotCMS-generated pages through a single PageComponent

This approach eliminates the need to duplicate dotCMS folder/page structure in Angular routing, preventing developer intervention for every new route.

Page Rendering#

Pages are rendered using the <dotcms-layout-body> component from @dotcms/angular library. This component:

  • Renders all page rows, columns, and content
  • Accepts a component map via the components input
  • Maps content type variable names to Angular components
  • Automatically passes full content objects to components

Example component mapping:

const DYNAMIC_COMPONENTS = {
  Banner: BannerComponent,
  Product: ProductComponent,
  Activity: ActivityComponent
};

Folder Structure#

src/app/
├── components/           # Standard site-wide components
│   ├── header/
│   ├── footer/
│   └── navigation/
└── dotcms/              # dotCMS-specific components
    ├── pages/           # Page components (see app.routes.ts)
    ├── components/      # Content type components
    └── types/           # TypeScript interfaces

Development Workflow#

  1. New Content Types: Add component mapping to DYNAMIC_COMPONENTS in page.ts
  2. Custom Pages: Create specific routes in app.routes.ts
  3. Site Components: Add to components/ folder for site-wide usage
  4. dotCMS Components: Add to dotcms/components/ for content rendering

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:

Authentication errors (401 Unauthorized)

This often occurs when the environment variables are not set correctly.

Solution:

  • Double-check that you've updated the authToken in src/environments/environment.development.ts with a valid token.
  • Ensure the token has the necessary permissions (at least read access) for the content you're trying to fetch.
  • Verify that the token hasn't expired. If it has, generate a new one in the dotCMS UI.
Connection issues

If you're having trouble connecting to the dotCMS instance:

Solution:

  • Verify that the dotcmsUrl in src/environments/environment.development.ts is correct.
  • Check if you can access the dotCMS instance directly through a web browser.
  • If using https://demo.dotcms.com, remember it restarts every 24 hours. You might need to wait or try again later.
  • Ensure your network allows connections to the dotCMS instance (check firewalls, VPNs, etc.).
Missing pages or content

If you're getting 404 errors for pages that should exist:

Solution:

  • Ensure the page exists in your dotCMS instance. For example, if you're trying to access /about, make sure an "about" page exists in dotCMS.
  • Check if the content types used in the example match those in your dotCMS instance.
  • Verify that the content has been published and is not in draft status.
Outdated dependencies or version conflicts

If you're experiencing unexpected behavior or errors related to dependencies:

Solution: Perform a clean reinstall of all dependencies by running:

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

This command will:

  1. Remove the node_modules directory
  2. Delete the package-lock.json file
  3. Perform a fresh install of all dependencies

After this, restart your development server:

ng serve
Build errors or stale cache

If you're experiencing build errors or changes aren't reflected in the running application:

Solution: Clear the Angular build cache and rebuild the project:

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

This sequence of commands will:

  1. Clear the Angular build cache
  2. Rebuild the project with development configuration
  3. Start the development server

This is recommended when:

  • You've made significant changes to your project configuration
  • You're experiencing unexplainable build errors
  • Your changes aren't reflected in the running application despite saving and restarting the dev server
  • You've recently updated Angular or other critical dependencies
Universal Visual Editor (UVE) not working

If the Universal Visual Editor is not functioning as expected:

Solution:

  • Ensure you've correctly configured the UVE in your dotCMS instance as described in the Universal Visual Editor section.
  • Verify that your Angular application is running on http://localhost:4200 (or update the UVE configuration if using a different port).
  • Check that you're accessing the dotCMS edit mode from the correct URL.
  • Clear your browser cache and try again.

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.

Additional Resources#

Source: examples/angular/README.md
Branch: main

Found an issue with this documentation? Report it on GitHub