The Page API enables you to retrieve all the elements of any Page in your dotCMS system. The elements may be retrieved in JSON format, or as fully rendered HTML; regardless of the format chosen, each element is returned separately within it's own JSON object, making it easy to retrieve and use all page elements with a single call.
Elements returned by the Page API include:
- Page information including URL and SEO
- Body Layout information as rows/columns
- Template/Theme information
- All Content Blocks, including what content types they can take
- Visitor Context Information (if a client side call)
- Rendered versions of the page and all content blocks (optional)
To see a simple example of the Page API's render mode in action, you can try a live variation of the Javascript single-page app featured in the example section:
Note: For additional information on the usage and benefits of the Page REST API and Layout-as-a-Service, please see the Layout as a Service (LaaS) post in the dotCMS blog.
Usage
Calls to the Page API take the following form:
https://{server_address}/api/v1/page/{format}/{page_path}[?param1=val1¶m2=val2]
Where:
{server_address}
is replaced with the address of your dotCMS server.{format}
specifies the format to return each page element in.- Acceptable values are
json
orrender
.
- Acceptable values are
{page_path}
is replaced with the path to the page
Below is an example URL returns the page response from a page on the demo site. You must be logged in to see the response (email:admin@dotcms.com
password:admin
).
Parameters
The Page API accepts the following URL parameters:
mode
— (LIVE
|WORKING
) if you want live or drafted content- Starting in 23.02, setting
mode
toEDIT_MODE
adds a newonNumberOfPages
property to all returned contentlets that appear on more than one Page, which displays the number of times this contentlet appears on Page assets. (This feature was made Edit Mode-only rather than enabled by default due to the expensive nature of the call.)
- Starting in 23.02, setting
host_id
— the ID of the site the page is on (if different from the one in the URL)language_id
— the ID of the language variant you want to retrievecom.dotmarketing.persona.id
— the ID of the persona variant you want to retrievefireRules
— (true
|false
) if you want to fire the rules set on the pagedepth
— (0
|1
|2
) allows access to related content via the Relationship fields of contentlets on a Page;0
(default) does not surface related content,1
surfaces immediate related contentlets, and2
shows one level of related content of related content — including content related to the Page asset itself. Other values throw an error.
Saving As Copy
The Page API also includes two endpoints capable of performing in-place content copying.
v1/page/copyContent
saves a Page with a copy of one of its included contentlets, allowing that Page's version of the content to differ from the version of the content that appears elsewhere. This is automatically used in the dotCMS user interface when editing content as a copy in Edit Mode.v1/page/{pageID}/_deepCopy
duplicates an entire page and all contentlets therein.
To call copyContent
directly, include a JSON payload with the following properties, as in the example below:
Property | Description |
---|---|
contentId | The identifier of the contentlet to be copied. |
pageId | The identifier of the Page containing the content. |
containerId | The identifier of the immediate Container holding the content. |
personalization | The identifier of a persona targeted by the content; for the default persona, use dot:default . |
relationType | A counter to distinguish between multiple instances of the same content, with default value of 1 . (Example: On a page with three different contentlets, all three of them will return relationType: 1 ; if all three are the same contentlet, they will instead be 1 , 2 , and 3 .) |
treeOrder | Maintains the dynamic relationship between Pages, Containers, and content on the multi_tree table. Defaults to 0 . |
variantId | Relates to a forthcoming feature; set to DEFAULT . |
```
curl -X 'PUT' \
'https://local.dotcms.site:8443/api/v1/page/copyContent' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"contentId": "d99ef5e5a64327896b849e165b2eaadf",
"pageId": "c7f8c15b7355ae088857e7220524a785",
"containerId": "//demo.dotcms.com/application/containers/default/",
"relationType": "1",
"personalization": "dot:default",
"variantId": "DEFAULT",
"treeOrder": 0
}'
To call _deepCopy
directly, no data payload is needed; just the Page id as the first path parameter, and _deepCopy
as the second:
curl -X 'PUT' \
'https://local.dotcms.site:8443/api/v1/page/c7f8c15b7355ae088857e7220524a785/_deepcopy' \
-H 'accept: application/json'
Examples
JSON Formatted Elements
The following call returns all the page elements of the dotCMS Demo site home page, with each page element being returned in JSON format:
(Remember: You must be logged into the Demo Site back end for this call to work.)
This call returns results which include all elements used to display the page, including the site, page, template, containers, content, and more. The following is a small sample of the information returned:
{
...
"site" : {
"lowIndexPriority" : false,
"indexPolicyDependencies" : "DEFER",
"default" : true,
"aliases" : "localhost\n127.0.0.1",
"inode" : "59bb8831-6706-4589-9ca0-ff74016e02b2",
"hostname" : "demo.dotcms.com",
...
"identifier" : "48190c8c-42c4-46af-8d1a-0cd5db894797",
"modDate" : 1634235141702,
"type" : "contentlet",
...
"folder" : "SYSTEM_FOLDER",
"archived" : false,
"languageId" : 1,
"working" : true,
"modUser" : "dotcms.org.1",
...
},
"template" : {
"iDate" : 1609946283995,
"type" : "template",
"owner" : "dotcms.org.1",
"inode" : "1b90c278-0dfc-4ecc-ac5b-1827522ae469",
"identifier" : "c6f813ef-f1f9-4759-a102-655bf441ec8e",
"source" : "DB",
"title" : "anonymous_layout_1609946283966",
"friendlyName" : "",
"modDate" : 1609946283996,
"modUser" : "dotcms.org.1",
...
Fully Rendered Elements
The following call returns all the page elements of the dotCMS Demo Site home page, with each page element returned as fully rendered HTML, encapsulated within a JSON obect:
(Remember: You must be logged into the Demo Site back end for this call to work.)
This call returns all of the same elements as the previous call, but returns displayable elements as fully rendered HTML. For an example, click the link above, and view the source of the rendered HTML page.
JavaScript Application Example
The following HTML code includes a full Javascript application which uses the Page REST API to pull and display the fully rendered contents of the dotCMS Demo Site index page. The app draws a page's slug from the url hash, fetches its content, and then resituates it into a simple template.
You can also try out a live variation on the page below, which has been extended to include dynamic, user-specified Page API calls.
<html>
<head>
<script>
function getUrl(){
var url = (window.location.hash.length==0)
? "/index" //// PATH/SLUG GOES HERE
: window.location.hash.substr(1);
if(!url.startsWith("/")){
url = "/" + url;
}
if(url.endsWith("/")){
url = url + "index";
}
window.location.hash = url;
// HERE IS THE API ENDPOINT TO GET THE LAYOUT as a SERVICE back,
// e.g. https://demo.dotcms.com/api/v1/page/render/index
return "https://demo.dotcms.com/api/v1/page/render" + url;
}
var url = getUrl();
console.log("reading:"+url);
function readJson(url, callback) {
var req = new XMLHttpRequest();
req.open("GET", url, true);
req.setRequestHeader("Authorization", "Basic " + btoa("admin@dotcms.com:admin"));
req.onreadystatechange = function() {
if (req.readyState === 4 && req.status == "200") {
callback(req.responseText);
}
}
req.send();
}
window.onload =
readJson(url, function(text){
var data = JSON.parse(text).entity;
if(window.location.search.indexOf("raw=")>-1){
document.body.innerHTML=text;
}
else if(data.layout){
writeLayoutDocument(data);
}
else{
writeRawDocument(data);
}
});
function writeRawDocument(data){
document.body.innerHTML=data.page.map.rendered;
}
function writeLayoutDocument(data){
var rows = data.layout.body.rows;
var myPage = document.createElement('div');
document.body.appendChild(myPage);
myPage.style.cssText = 'border:2px solid #9AB3CE;margin:10px;padding:10px;background:#E0E9F6';
myPage.innerHTML="reading from : <a href='" + url + "'>" + url + "</a>";
if(data.layout.header){
var header = document.createElement('div');
header.innerHTML="<h1>Including Header</h1>";
header.style.cssText = 'border:2px solid #9AB3CE;margin:10px;padding:10px;background:#E0E9F6';
document.body.appendChild(header);
}
for(i=0;i<rows.length;i++){
var row = rows[i];
var columns = row.columns;
var thisRow = document.createElement('div');
thisRow.style.cssText = 'display:flex;flex-direction:row;justify-content:space-between';
document.body.appendChild(thisRow);
for(j=0;j<columns.length;j++){
var column = columns[j];
var containers = column.containers;
var thisColumn = document.createElement('div');
thisColumn.style.cssText = 'flex-basis:' + (column.widthPercent-0) + '%;border:2px solid #9AB3CE;margin:10px;padding:10px;background:#EEF5F9';
thisRow.appendChild(thisColumn);
for(k=0;k<containers.length;k++){
var containerId = containers[k].identifier;
var containerUUID = containers[k].uuid;
var thisContainerInfo = document.createElement('div');
thisContainerInfo.style.cssText = "color:gray;text-align:right;"
thisColumn.appendChild(thisContainerInfo);
thisContainerInfo.innerHTML="{row:" + (i+1) + ",column:" + (j+1)+ ",width:" + column.widthPercent + "%}";
var thisContainer = document.createElement('div');
thisContainer.style.cssText = 'border:3px solid #9AB3CE;background:#ffffff;margin:10px;padding:10px;';
thisColumn.appendChild(thisContainer);
// add in the pre-rendered container content
console.log("rendered", containerUUID)
thisContainer.innerHTML=data.containers[ containerId ].rendered["uuid-" + containerUUID ];
}
}
}
if(data.layout.footer){
var footer = document.createElement('div');
footer.innerHTML="<h1>Including Footer</h1>";
footer.style.cssText = 'border:2px solid #9AB3CE;margin:10px;padding:10px;background:#E0E9F6';
document.body.appendChild(footer);
}
}
</script>
<base href="https://demo.dotcms.com">
</head>
<body></body>
</html>
Feel free to try out a few Page API calls for yourself!