Angular

This guide teaches you how to integrate an Angular application with dotCMS, and then manage its content with the Universal Visual Editor.

Overview

dotCMS integrates with Angular to support a wide assortment of features. We'll be focusing on:

Creating and authenticating an Angular front end for use with the dotCMS back end
Configuring your site to integrate with the Universal Visual Editor (UVE)
Editing page layout and content with the UVE

Prerequisites

Node.js & npm: Ensure you have Node.js (version 18 or higher) installed.
Angular Client: Install the Angular client globally using npm install -g @angular/cli
Basic Knowledge: Familiarity with Angular fundamentals and REST/API concepts.

Step 1: Create Your Angular Application

Use the official dotCMS Angular sample site to create your Angular application locally in one of the following ways:

You can obtain the application files using a git sparse checkout:

git clone -n --depth=1 --filter=tree:0 https://github.com/dotCMS/core
cd core
git sparse-checkout set $(git sparse-checkout list) --no-cone examples/angular
git pull origin main

Or, you can directly download it from https://github.com/dotCMS/core/tree/main/examples/angular

Step 2: Configure and Run

Generate an API Token

Before creating your Angular application, access the demo.dotcms.com instance (or your local instance) and generate an API Access Token for the Admin User:

If accessing the dotCMS demo instance:
- https://demo.dotcms.com/dotAdmin
  - User: admin@dotcms.com
  - PW: admin
- Note: The demo instance is reset twice per day
Create an API Access Token:
- Navigate to Settings > Users
- Select the Admin User
- Click the API Access Tokens tab
- Click the Request New Token button.

Configure the Connection to dotCMS

In your IDE, open the Angular project. Navigate to src/environments and open the environment.development.ts file.

Update the following variables:

authToken: This is the API Access Token you generated for the Admin user in the previous step.
dotcmsUrl: This is the URL for the dotCMS instance — such as https://demo.dotcms.com, http://localhost:8443, or whatever else you may have configured it to be.

Your config file might end up looking roughly like this:

Run the Application

Run the Angular application locally to see it in your browser. Navigate to the root directory of the application (such as core/examples/angular) and execute the following:

npm install

ng serve

Note: If there are errors, you may need to run npm update and then rerun ng serve.

Your terminal will output the following:

Now, when you browse to http://localhost:4200, you’ll see the dotCMS Angular example application running.

🎉 Congratulations! The application is running. Now, let's complete the integration by getting the editor involved.

Step 3: Universal Visual Editor

The DotCMS Universal Visual Editor (UVE) provides a seamless editing experience directly on your Angular website. This editor offers a powerful way to build pages, with features including, but not limited to:

In-context editing: Edit content directly on your website
Drag-and-drop interface: Easily arrange components on the page
Responsive design tools: Preview and edit for different screen sizes

Enabling the Universal Visual Editor

Now, we need to configure the Universal Visual Editor application within your dotCMS instance. This will allow it to recognize the Angular application and render it in the UVE.

In dotCMS, navigate to Settings > Apps and click on “UVE - Universal Visual Editor”
Click the plus button at the right of the site we're integrating (i.e., demo.dotcms.com).
In the Configuration field, add the following JSON object, which contains the URL for your local Angular application:

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

Click Save.

Now, navigate to Site > Pages > Home to check out the Angular application integrated with dotCMS!

Editing Content in the Universal Visual Editor

Now, let’s edit the Home page.

Inline text editing

Navigate to Site > Pages > Home if you are not already there.
- Click the title ("Explore the World") and note the in-line editing interface.
- Add some text!
- Click out of the banner area and note the auto-save notification that pops up.
Click on the dropdown at the top left of the screen (which currently says "Draft").
- Select Published; the screen will refresh to the currently published version.
  - This will not show the change you just made — it hasn't been published, yet.
- Now select Preview from the same dropdown.
  - Your draft changes will be visible without the editing controls.
Select Draft from the same dropdown to return to Edit Mode.

Drag and Drop Content

Click on the X icon at the top right of the Explore the World banner
- This will remove the banner once you Accept the change.
  - You will now see an empty container on the page.
In the Content Palette, on the right, browse into the Banner content type by clicking its corner arrow.
Drag a new Banner contentlet into the empty box on the page.
The new banner will render and the page will be saved.

Adjust Layout of the Page

Click on the Layout tool in the rightmost panel.
Drag a Row from the toolbar and drop it below the first existing row.
Grab two more Box items and drag them into the new row.
Resize them all to be equal widths.
Click the Content button in the right panel, and see the four empty containers.

Add Content

Let’s fill the new boxes! Click on the Product content type on the Content Palette.
- If you can't find it, use the search field at the top.
Drag some Products into the empty slots.
Click the mode dropdown in the top left, and select Preview to see how it looks without UVE controls.
Click back to Draft to get back to Edit Mode.
Click the blue Publish button on the top right corner of the screen.

Check Your App!

Now refresh the browser window that has the Angular application running (localhost:4200), and you will see the changes you made from the back end.

Before

After

You are now up and running — your Angular site is fully integrated with dotCMS!