Defining templates
What is a template?
Templates define the page's structure.
For example, a template divides the page into:
- Header
- Main section
- Footer
Templates can nest layouts and modules, but not other templates.
The next paragraph describes the JSON fields that define templates.
Defining templates
The templates' definition is a JSON array of template definitions.
The fields that define a template are:
| Name | Type | Is Mandatory | Description |
|---|---|---|---|
| key | Object | Yes | Represents the unique human-readable identifier of the template |
| slots | Array of string | Yes | List of container names (slots) that can contain layouts or modules |
| label | String | Yes | Friendly name of the template shown on the Page Builder |
| description | String | No | Description of the template shown as helper in the Page Builder |
| design | Object | Yes | It defines the template's structure in terms of number of rows. For each row, it defines the row's number of columns. In turn, each column can be split in rows. The rows definition is recursive. |
| properties | Object | Yes | Properties defined on this module |
key (object fields)
| Name | Type | Is Mandatory | Description |
|---|---|---|---|
| id | String | Yes | Unique identifier (PascalCase, no spaces) |
| namespace | String | Yes | Group of templates the template belongs to. By convention, use the format {page-type-name}_Template. |
design (object fields)
Based on the slot names, the design object defines the structure in which the slots are located within templates and layouts.
The model structure consists of an array of rows. Each row consists of an array of columns whose Name property must match the name of a slot.
In the example below, the design object contains the object rows with three rows corresponding to the header, main, and footer slots. Each row contains an object columns with a single column. The Name field of each column contains the slot's name. The header and footer columns have elementType=1 to setting that those slots are not available (Slot Locked) in the Page Builder design page to host layouts and modules.
| name | Type | Is Mandatory | Description |
|---|---|---|---|
| rows | Array of columns | Yes | List of columns in the containing row |
columns (object fields)
columns is an array of objects defined each by:
| Name | Type | Is Mandatory | Description |
|---|---|---|---|
| elementType | Integer | Yes | It sets if the slot is available in the Page Builder design page to host layouts and modules (0), if the slot is locked (1), if the column contains nested rows (2) |
| name | String | No | Name of the area represented by the column, must match slot name |
| description | String | No | Description of the area shown in editing view |
| width | Integer | Yes | The width value is interpreted as a fraction of the sum of the widths in a row. For example, in a row with 3 columns, which have width values of 20, 40, and 10, the design draws columns with a percentage width of 20/(20+40+10)=28.6%, 40/(20+40+10)=57.1%, and 10/(20+40+10)=14.3% |
| rows | Array of columns | Yes | Nested rows within this column |
properties (object fields)
properties is an array of objects defined each by:
| Name | Type | Is Mandatory | Description |
|---|---|---|---|
| name | String | Yes | Unique identifier of the property |
| typeName | String | Yes | Type of data assigned to the property. Supported values: String, Int32, Boolean or extended types offered by FORGE) |
| category | String | No | Group representing the category of this property |
| description | String | No | Helper text shown in Page Builder |
| displayName | String | No | Friendly name shown in Page Builder |
| isBrowsable | Boolean | Yes | Field visibility on the UI |
| pickList | Object | No | List of possible values for the property |
| contentPicker | Object | No | Configuration for content selector to assign to property |
Configuration to Avoid
When defining templates, avoid the following common configuration issues:
- Duplicate property names: Each property in
propertiesmust have a uniquename. Duplicate names are not allowed. - Conflicting controls: A property cannot have both
ContentPickerandPickListdefined at the same time. - PickList type restriction: The
PickListcan only be used with properties wheretypeNameisString. - ContentPicker type restriction: The
ContentPickercan only be used with properties wheretypeNameisStringorCmsArray.
Sample
The simplest template — let's call it Default — defines three rows:
-
Header: A single column row that the Page Builder design page cannot fill with layouts and modules.
Pages with this template must define a variable — let's call it
page_header— containing the path of the page the front-end must render within the header slot. This variable can have a default value and change where a different header is needed. -
Main: A single column row that the Page Builder design page can fill with layouts and modules.
-
Footer: A single column row that the Page Builder design page cannot fill with layouts and modules.
Pages with this template must define a variable — let's call it
page_header— containing the path of the page the front-end must render within the footer slot. This variable can have a default value and change where a different footer is needed.
The Default template's JSON definition is the following: