The PageAPI 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
jsonorrender.
- 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
modetoEDIT_MODEadds a newonNumberOfPagesproperty 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 page
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!
