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:
Key | Value |
---|---|
dotcmsUrl | URL for the dotCMS instance the remote website or application will be calling. For security reasons, we highly recommend passing this value through an environment file variable. |
authToken | dotCMS API token. For security reasons, we highly recommend passing this value through an environment file variable. |
siteId | Optional. The identifier for the dotCMS Site to be accessed. If not specified, falls back to the default site of the instance. |
requestOptions | Optional. An object containing options to pass via the JavaScript Fetch API, used by the library to make its calls to dotCMS. Note that body and method options are not taken into account. |
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.
Method | Argument | Response |
---|---|---|
{client}.page.get(options) | PageApiOptions object | A Promise that resolves to a JSON object containing a Page API response. |
{client}.nav.get(options) | NavApiOptions object | A Promise that resolves to a JSON object containing a Navigation API response. |
Each takes a distinctive object as its argument, the full specifications are provided in the following subsections.
client.page.get(opts)
Method
PageApiOptions Property | Value | Description |
---|---|---|
path | String | The path of the page to access. |
siteId | String | Optional. The identifier of the Site being accessed. If not provided, it will fall back to the one configured for the client object. |
language_id | Number | Optional. The Page's numeric language identifier. Defaults to the Site's default language. |
personaId | String | Optional. The identifier of the persona for which the Page should be retrieved. |
fireRules | Boolean | Optional. Whether to fire rules on the Page. Defaults to false . |
depth | Number | Optional. Includes related content via Relationship fields, by up to as many steps as the number specified. Defaults to 0 . |
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
NavApiOptions Property | Value | Description |
---|---|---|
path | String | The root path from which to begin traversing the directory tree. |
depth | Number | Optional. Depth of the folder tree to return. A value of 1 (default) returns only the element specified in the path property; 2 includes any children, if the path specifies a folder; and 3 includes all children and grandchildren. |
language_id | Number | Optional. The Page's numeric language identifier. Defaults to the Site's default language. |
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:
Property | Description |
---|---|
entity | An object containing the context data for the Page. This corresponds to the entity property returned by a Page API call, such as via the client library's {client}.page.get() method.DotcmsLayout additionally looks for the definition of a components child property within entity , described below. |
config | Optional. An object with two 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.