Javascript SDK

To assist in building websites headlessly with the Universal Visual Editor, dotCMS has created a Software Development Kit (SDK) to integrate with popular Javascript frameworks. The SDKs simplify the process of data retrieval through dotCMS REST APIs, enabling developers to concentrate on their front-end code for faster development.

The Javascript SDK consists of two types of library: a dotCMS client that interacts securely with the dotCMS instance API, and rendering libraries that contain components and utilities to render the content and interact with the Universal Visual Editor.

The dotCMS client library is known simply as @dotcms/client. Currently, there is also one rendering library — @dotcms/react — which supports sites and applications built using ReactJS.

Additional rendering libraries are planned to extend support for further frameworks in future releases, such as a Vue.js library currently under development. It is also possible to build one's own custom library to support frameworks not yet listed here.

dotCMS Client Library

The @dotcms/client library is responsible for interacting directly with the dotCMS back end, securely performing Page API and Navigation API calls from a remote site's host and passing the resulting data to a rendering library for display.

Installation

Installation can be performed via package manager. Choose any of the following commands:

npm install @dotcms/client

pnpm install @dotcms/client

yarn add @dotcms/client

Initialization and Usage

First, you need to import the dotcmsClient, which creates a dotCMS client.

import { dotcmsClient } from '@dotcms/client';

dotcmsClient exposes an init method that that takes a configuration object with the following keys:

For example:

import { dotcmsClient } from '@dotcms/client';

const client = dotcmsClient.init({
    dotcmsUrl: process.env.NEXT_PUBLIC_DOTCMS_HOST,
    authToken: process.env.DOTCMS_AUTH_TOKEN,
    siteId: '59bb8831-6706-4589-9ca0-ff74016e02b2',
    requestOptions: {
        cache: 'no-cache'
    }
});

Once initialized, the client contains two properties, page and nav — i.e., one for each API. Each property exposes a single asynchronous get method. Additional methods covering other API endpoints, such as delete or update operations, are planned for future releases.

Each takes a distinctive object as its argument, the full specifications are provided in the following subsections.

client.page.get(opts) Method

A call to this method might look like this:

const data = await client.page.get({
    path: '/blog',
    language_id: 1,
    personaId: '34b720af-4b46-4a67-9e4b-2117071d01f1'
});

client.nav.get(opts) Method

An example of a call:

const nav = await client.nav.get({
    path: '/',
    depth: 2,
    languageId: 1
});

React Library

The @dotcms/react library provides React components and hooks designed to work with dotCMS, making it easy to build pages and applications with ReactJS that are fully interoperable with the dotCMS Universal Visual Editor.

Installation

Installation can be performed via package manager. Choose any of the following commands:

npm install @dotcms/react

pnpm install @dotcms/react

yarn add @dotcms/react

DotcmsLayout Component

The main structural component of the React library is the DotcmsLayout component. This component implements further built-in components, such as Row, Column, and Container, which handle the correspondingly named elements of a dotCMS Page's Template or Layout.

The DotcmsLayout component creates a global React context with response data from the Page API, referred to in the library as PageProviderContext.

It accepts two data properties:

An example usage of DotcmsLayout might look like this:

import { DotcmsLayout } from '@dotcms/react';

const MyPage = ({ entity }) => {
    return <DotcmsLayout entity={entity} />;
};

Within entity, a components property accepts a map of components to Content Types, where each key is the Content Type variable and the value is the name of the React component in charge of its rendering.

If the data from the client's .page.get() call were passed by the name data, a DotcmsLayout can include both the component map and the Page API response entity through use of the spread operator on the latter, as below:

<DotcmsLayout
    entity={{
        components: {
            webPageContent: WebPageContent,
            Banner: Banner,
            Activity: Activity,
            Product: Product,
            Image: ImageComponent,
        },
        ...data,
    }}
/>

For a more elaborate treatment, see the my-page.js component in the Universal Visual Editor's NextJS example, which implements the React library.

useDotcmsPageContext Hook

The useDotcmsPageContext hook allows a component to access the data context created by the DotcmsLayout component.

import { useDotcmsPageContext } from '@dotcms/react';

const MyComponent = () => {
    const context = useDotcmsPageContext();
    // Use the context
};

For more elaborate examples, see the Content Type components in the NextJS example.