dotCMS's Universal Visual Editor (UVE) allows full in-context editing for headless websites, single-page applications, and other remote web apps built using dotCMS as their data source. UVE can edit pages in any external hosting service — including Vercel, AWS Amplify, etc.
Through the UVE, you can use the same tools on a remote site or app as on a native dotCMS page.
This feature both simplifies and improves upon its predecessor, Edit Mode Anywhere. It features fewer technical requirements and a more natural, library-based integration through dotCMS's new JavaScript SDK.
Configuration
To begin setting up the Universal Visual Editor:
- Browse to Settings -> Apps
- Select the built-in integration for UVE - Universal Visual Editor.
- Select the site that will be feeding the destination pages.
Under Configuration, add a JSON object with the property config, whose value is an array of JSON objects that specify the URLs and path patterns with which the UVE is intended to interact.
Below is a simplified version of the sample config provided in the menu:
{
"config":[
{
"pattern":"/blogs/(.*)",
"url":"https://myspa.blogs.com:3000"
},
{
"pattern":".*",
"url":"https://myspa.com:3000",
"options": {
"allowedDevURLs": [
"http://localhost:3000",
"http://localhost:3001",
"https://myspa.dev.com"
]
}
}
]
}
Each object in the array contains the following properties:
| Property | Description |
|---|---|
url | The URL of the website to interact with the UVE. |
pattern | A regular expression that specifies a site path pattern. This matches the addresses of all the pages you want to edit with UVE. |
options | An object specifying further options via child properties. The Options Property table below contains valid contents. |
| Options Property | Description |
|---|---|
allowedDevURLs | An array of strings, each consisting of a URL allowed for use with the clientHost URL parameter. See the section below for more information. |
The remote site must also be configured through the JavaScript SDK's client library, requiring, at the very least:
- The URL of the dotCMS instance
- A dotCMS API token
For more information, see the client library documentation.
The clientHost Parameter
Using the clientHost URL parameter, you can supply the same dotCMS page and content to a different headless environment. This can be useful, e.g., when transitioning between frameworks, comparing implementations, etc.
After using the allowedDevURLs configuration option to define an array of URLs, these values can be supplied to the URL query parameter clientHost; for instance, your URL might include a parameter such as &clientHost=http://localhost:3000, as in the example below:
https://some-dotcms-server.com/dotAdmin/#/edit-page/content?url=index&language_id=1&device_inode=&com.dotmarketing.persona.id=modes.persona.no.persona&clientHost=http://localhost:3000
This will display the specified page in the context of the headless environment specified in the URL. This environment should also be built to dotCMS specifications; see our JavaScript SDK section for more information.
Note that this will not work with the page editor in the traditional context; this feature is currently exclusive to headless development.
Troubleshooting
If something goes wrong, the UVE will strip the clientHost parameter and then show the default environment you set for the page. In that case, check both the configuration of the App in Settings -> Apps -> UVE and the value passed to the clientHost parameter, to ensure they align.
To ensure the client displayed is your local environment, you can add console.log() calls to its code and look for them in your browser console.
Development
Once the client can successfully connect to dotCMS, you can continue to develop per your chosen framework — e.g., if you’re an Angular developer, you’re just writing Angular code, without any special conventions, required directory structures, etc.
The JavaScript SDK makes available rendering libraries, such as its React library, to simplify API calls and component construction. However, these are not necessary; you can also build your own rendering libraries, using only the dotCMS client library to return data.
The key data structures to get to know are the JSON response objects returned by the API calls:
- Page API: Returns information about the basic properties of a Page, its containers, content, template and layout, etc.
- Navigation API: returns information on the current host, folder, and child/grandchild folders
- Content API: returns content items
