Managing Structures and Templates by Using the REST API

Web Content Structures define the information included in a Web Content article. Structures facilitate creating and managing Web Content, while ensuring that the content includes all the required information. You can associate a Structure with a Web Content Template. A Template determines how content fields are rendered on a Page. The following table summarizes the available options using the Liferay DXP REST API with Web Content Structures and Templates:

Available Options	Unavailable Options
Gather Structures and Templates information Replace Structures permissions	Create Structures or Templates Delete Structures or Templates

Here, you’ll use a pre-built Liferay DXP Docker image with several cURL code samples to learn how to manage Structured Content. You can learn about the following topics:

Setting Up Your Environment
Identifying the Service to Consume
Getting the Site Structures
Getting the Site Templates
Getting the Structure Permissions
Replacing the Structure Permissions

Setting Up Your Environment

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u55

Sign in to Liferay at http://localhost:8080 using the email address [email protected] and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip the sample project:
```
curl https://resources.learn.liferay.com/dxp/latest/en/content-authoring-and-management/web-content/developer-guide/liferay-m7b1.zip -O
```
```
unzip liferay-m7b1.zip
```
note

These scripts use basic authentication and are designed for testing. Do not use basic authentication in a production Liferay DXP environment.
Complete the following steps to set up the environment:

Identifying the Site ID

Open the Site menu () and go to Configuration → Site Settings.
Under the Platform section, click Site Configuration.
Find the Site identifier under Site ID.

Create the Structure and Template Samples

note

You cannot create a Structure or Template programmatically using the REST API.

To create the Structure, read Creating Structures. To create the Template, read Creating Web Content Templates and create a Template based on the sample Structure. This tutorial uses a basic Structure with a single Text field to demonstrate the ContentStructure service.

Basic sample Structure using a single Text field.

Identifying the Sample Structure and Template

Open the Site menu () and go to Content & Data → Web Content.
Click the Structures tab.
Under the ID column, identify the ID for your Structure.

You can also identify the Structure ID programmatically. For more information, read Managing Structures and Templates by Using the REST API.

Identifying the Service to Consume

Use the StructuredContent service in the Liferay DXP Headless Delivery API to manage Web Content. To identify this service and all the different HTTP methods, use the Liferay API Explorer. For more information, see Consuming REST Services.

Getting the Site Structures

The ContentStructures_GET_FromSite.sh cURL script lists the existing Site Structures. This script uses the ContentStructure service with the GET HTTP method, using the Site ID as the only parameter.

   ./ContentStructures_GET_FromSite.sh 20125

Parameter #	Description
$1	`siteId`

The following code shows the JSON output generated by the script. The script returns all the Structures in the Site. In this example you can see a single Structure identified by an id and a name.

   {
    "actions" : { },
    "facets" : [ ],
    "items" : [ {
        "availableLanguages" : [ "en-US" ],
        "contentStructureFields" : [ {
        "dataType" : "string",
        "inputControl" : "text",
        "label" : "Text",
        "localizable" : true,
        "multiple" : false,
        "name" : "Text86549034",
        "nestedContentStructureFields" : [ ],
        "options" : [ ],
        "predefinedValue" : "",
        "repeatable" : false,
        "required" : false,
        "showLabel" : true
        } ],
        "creator" : {
        "additionalName" : "",
        "contentType" : "UserAccount",
        "familyName" : "Bowman",
        "givenName" : "David",
        "id" : 20129,
        "name" : "David Bowman"
        },
        "dateCreated" : "2021-08-02T13:15:42Z",
        "dateModified" : "2021-08-02T13:16:57Z",
        "description" : "",
        "id" : 41837,
        "name" : "Simple Structure",
        "siteId" : 20125
    } ],
    "lastPage" : 1,
    "page" : 1,
    "pageSize" : 20,
    "totalCount" : 1
   }

The Structure has a single Text field described in the dataType section under contentStructureFields. When you include more elements on the Structure, you can see additional sections under contentStructureFields. Below is the partial JSON output for a Structure with a Text ("dataType" : "string") and Image fields ("dataType" : "image"):

   {
    "actions" : { },
    "facets" : [ ],
    "items" : [ {
        "availableLanguages" : [ "en-US" ],
        "contentStructureFields" : [ {
        "dataType" : "string",
        "inputControl" : "text",
        "label" : "Text",
        "localizable" : true,
        "multiple" : false,
        "name" : "Text86549034",
        "nestedContentStructureFields" : [ ],
        "options" : [ ],
        "predefinedValue" : "",
        "repeatable" : false,
        "required" : false,
        "showLabel" : true
        }, {
        "dataType" : "image",
        "label" : "Image",
        "localizable" : true,
        "multiple" : false,
        "name" : "Image96876678",
        "nestedContentStructureFields" : [ ],
        "options" : [ ],
        "predefinedValue" : "{}",
        "repeatable" : false,
        "required" : false,
        "showLabel" : true
        } ],

Getting the Site Templates

The ContentTemplates_GET_FromSite.sh cURL script lists the existing Site Templates. This script uses the ContentTemplate service with the GET HTTP method, using the Site ID as the only parameter.

   ./ContentTemplates_GET_FromSite.sh 20125

cURL script parameters:

Parameter #	Description
$1	`siteId`

Below is the partial JSON output generated by the script. The script returns all the Templates in the Site. In this example you can see a single Template identified by an id and a name. The contentStructureId corresponds to the associated Structure ID and the templateScript corresponds to the FreeMarker Template Language describing the Template.

   {
    ...
        "availableLanguages" : [ "en-US" ],
        "contentStructureId" : 41837,
        "creator" : {
        "additionalName" : "",
        "contentType" : "UserAccount",
        "familyName" : "Bowman",
        "givenName" : "David",
        "id" : 20129,
        "name" : "David Bowman"
        },
        "dateCreated" : "2021-08-02T13:24:32Z",
        "dateModified" : "2021-08-02T14:33:24Z",
        "description" : "",
        "id" : "41847",
        "name" : "Simple Template",
        "programmingLanguage" : "ftl",
        "siteId" : 20125,
        "templateScript" : "<#if (Text86549034.getData())??>\n\t${Text86549034.getData()}\n</#if>"
    } ],
    "lastPage" : 1,
    "page" : 1,
    "pageSize" : 20,
    "totalCount" : 1
   }

note

For more information about Templates, read Creating Web Content Templates.

Getting the Structure Permissions

The ContentStructure_GET_Permissions.sh cURL script lists the Structure’s permission. This script uses the ContentStructure service with the GET HTTP method, using the Structure ID as the only parameter.

Method	Service	Endpoint
PUT	`ContentStructure`	`/v1.0/content-structures/{contentStructureId}/permissions`

   ./ContentStructure_GET_Permissions.sh 41837

cURL script parameters:

Parameter #	Description
$1	Structure `id`

The JSON output includes the permissions under the items section. In this example, there is only one Role with permissions on the sample Structure in roleName, with the list of permission in actionIds:

    {
    "actions" : {
        "get" : {
        "method" : "GET",
        "href" : "http://localhost:8080/o/headless-delivery/v1.0/content-structures/41837/permissions"
        },
        "replace" : {
        "method" : "PUT",
        "href" : "http://localhost:8080/o/headless-delivery/v1.0/content-structures/41837/permissions"
        }
    },
    "facets" : [ ],
    "items" : [ {
        "actionIds" : [ "DELETE", "PERMISSIONS", "UPDATE", "VIEW" ],
        "roleName" : "Owner"
    } ],
    "lastPage" : 1,
    "page" : 1,
    "pageSize" : 2,
    "totalCount" : 2
    }

note

To learn how to manage permissions, see [Assigning Permissions to Web Content Structures and Templates] (../assigning-web-content-structures/assigning-permissions-to-structures-and-templates.md).

Replacing the Structure Permissions

Use the PUT HTTP method with the ContentStructure service to replace the original Structure permission. This script example uses the Structured Content identifier id to include the DELETE and VIEW permissions for the Power User Role:

Method	Service	Endpoint
PUT	`ContentStructure`	`/v1.0/content-structures/{contentStructureId}/permissions`

   ./ContentStructure_PUT_Permissions.sh 41837

cURL script parameters:

Parameter #	Description
$1	Structure `id`

The JSON output shows two entries under the items section, one for each Role:

    {
    "actions" : {
        "get" : {
        "method" : "GET",
        "href" : "http://localhost:8080/o/headless-delivery/v1.0/content-structures/41837/permissions"
        },
        "replace" : {
        "method" : "PUT",
        "href" : "http://localhost:8080/o/headless-delivery/v1.0/content-structures/41837/permissions"
        }
    },
    "facets" : [ ],
    "items" : [ {
        "actionIds" : [ "DELETE", "PERMISSIONS", "UPDATE", "VIEW" ],
        "roleName" : "Owner"
    }, {
        "actionIds" : [ "DELETE", "VIEW" ],
        "roleName" : "Power User"
    } ],
    "lastPage" : 1,
    "page" : 1,
    "pageSize" : 2,
    "totalCount" : 2
    }

Managing Structures and Templates by Using the REST API

Not finding what you're looking for?