Render content
Acoustic Content rendering feature automatically generates HTML markup for content that is managed in Content. The generated HTML documents or fragments are automatically published to the CDN for efficient worldwide delivery. You can control the URL for the generated documents and fragments with the URL templates.
Check out the Handlebars Template Rendering sample. Preview the Sample articles with content spot rendering
.
To render the content:
- Create HTML templates to define the specific markup format that you want to generate for a specific type of content. These templates can use Handlebars to insert the properties of the content into the HTML.
- Create layouts and layout mappings to define how to render formatted content on a site. For more information, see Render HTML pages. You associate a template to a content type through the layout mappings. Content types are created in Content.
- Upload the corresponding rendering templates to Content with the wchtools command-line interface or the public REST API of Content.
Generated render results get pushed as static files to the Content CDN (Akamai) and are cached as your other static files. Therefore, new versions of your render results do not become visible to your clients immediately, but only after cache expiration on the CDN.
Note:
For checking individual render results, you can bypass the cache on the CDN by loading the resource with the delivery resource service public API:
/delivery/v1/resource?path= resource path
.
Note:
If updates are made to the ready versions of your content, the Content auto-publish feature rerenders the updated content to overwrite the rendered content.
You can pre-render parts of your content into HTML documents or fragments that can either directly or indirectly be used on your website or JavaScript applications. That is, when a content item is published, Content makes it available at the URL defined by the urlTemplate. If pre-rendering is false, the /delivery/v1/rendering/render/content/{id} API can still be used to get the rendered content.
Note:
The
prerender
field in the layout must be set to true for the content to be pre-rendered. By default, the content layout is ignored and the content is not pre-rendered.
For more information on how to manage web assets, layouts, and layout mappings, go to wchtools documentation and the layout service REST API documentation.
Generating markup by using Handlebars templates
Handlebars templates operate on a JSON record. The JSON record provides the dynamic data that is merged into the static markup in the template file. This JSON record that contains the content and the dynamic data that is made available in Content is called the rendering context
.
The rendering context available to your Handlebars template has the same JSON structure as the JSON returned by the API /delivery/v1/content/{id}. The rendering context JSON also contains the following additional information:
-
The markup context - contains the render result of other content items that are referenced by content reference elements. The render result is generated by applying the default layout to the referenced content item.
Example: Assume that you have a content item with a content reference element named "mycontent" pointing to a "my content item". The render result for the "my content item" can be referenced through{{{elements.mycontent.markup}}}
. -
The layout context - The layout context provides the layout information for the current content item. The value follows the same structure as the JSON served by the authoring layout service under the route:
authoring/v1//layouts/by-content/{id}
. The layout context is contained in the rendering context at the selectorlayout
. -
The hub context - The
context.hub
context provides access to the API and static resource delivery URLs of your Acoustic Content service instance. -
API URL context - The
context.hub.apiUrl
context provides access to the API base URL.
API URL pathname
JSON Selector | Description (Values as defined in "https://url.spec.whatwg.org/#urlutils-members") | Example |
---|---|---|
context.hub.apiUrl.pathname | The API URL path name value. | {{context.hub.apiUrl.pathname}} generates /api/e123456a-12c3-12d3-9f7b-0de12f345e67 |
context.hub.apiUrl.hostname | The API URL host name value. | {{context.hub.apiUrl.hostname}} generates content-XX_N.content-cms.com |
context.hub.apiUrl.host | The API URL host value. | {{context.hub.apiUrl.host}} generates content-XX_N.content-cms.com |
context.hub.apiUrl.protocol | The API URL protocol value. | {{context.hub.apiUrl.protocol}} generates https: |
context.hub.apiUrl.origin | The API URL origin value. | {{context.hub.apiUrl.origin}} generates https://content-XX_N.content-cms.com |
API URL href
JSON Selector | Description (Values as defined in "https://url.spec.whatwg.org/#urlutils-members") | Example |
---|---|---|
context.hub.apiUrl.href | The API URL href value. | {{context.hub.apiUrl.href}} generates https://content-XX_N.content-cms.com/api/e123456a-12c3-12d3-9f7b-0de12f345e67 |
- Resource URL Context - The
context.hub.resourceUrl
context provides access to the delivery base URL that serves static resources.
Resource URL path name
JSON Selector | Description (Values as defined in "https://url.spec.whatwg.org/#urlutils-members") | Example |
---|---|---|
context.hub.resourceUrl.pathname | The resource URL path name value. | {{context.hub.resourceUrl.pathname}} generates /e123456a-12c3-12d3-9f7b-0de12f345e67 |
context.hub.resourceUrl.hostname | The resource URL host name value. | {{context.hub.resourceUrl.hostname}} generates content-XX-N.content-cms.com |
context.hub.resourceUrl.host | The resource URL host value. | {{context.hub.resourceUrl.host}} generates content-XX-N.content-cms.com |
context.hub.resourceUrl.protocol | The resource URL protocol value. | {{context.hub.resourceUrl.protocol}} generates https: |
context.hub.resourceUrl.origin | The resource URL origin value. | {{context.hub.resourceUrl.origin}} generates https://content-XX_N.content-cms.com |
context.hub.resourceUrl.href | The resource URL href value. | {{context.hub.resourceUrl.href}} generates https://content-XX_N.content-cms.com/e123456a-12c3-12d3-9f7b-0de12f345e67 |
Example
{
"apiUrl": {
"pathname": "/api/e123456a-12c3-12d3-9f7b-0de12f345e67",
"hostname": "content-XX_N.content-cms.com",
"host": "content-XX_N.content-cms.com",
"protocol": "https:",
"origin": "https://content-XX_N.content-cms.com",
"href": "https://content-XX_N.content-cms.com/api/e123456a-12c3-12d3-9f7b-0de12f345e67"
},
"resourceUrl": {
"pathname": "/e123456a-12c3-12d3-9f7b-0de12f345e67",
"hostname": "content-XX_N.content-cms.com",
"host": "content-XX_N.content-cms.com",
"protocol": "https:",
"origin": "https://content-XX_N.content-cms.com",
"href": "https://content-XX_N.content-cms.com/e123456a-12c3-12d3-9f7b-0de12f345e67"
}
}
Access rendering results
After you map a template to a content type, all future updates that are made to the ready content of that type trigger a rendering of the corresponding content item. Draft content is not rendered. The URL under which the render result can be accessed is defined by the URL template that is defined in the corresponding layout.
The layout descriptor JSON record supports an optional a property named urlTemplate
.
The URL template is used to define the URL for a rendering result document or fragment. The template supports the following replacement tokens that are resolved during rendering:
{name}: The name property of the currently rendered content item.
{id}: The ID property of the currently rendered content item.
{locale}: The locale property of the currently rendered content item. <strong>Note:</strong> If the locale is not set for the content item, the {locale} token resolves to an empty string.
{templateLocation}: The path to the folder that holds the current template web asset.
Note:
If no
urlTemplate
property is defined, the following URL template is assumed:/{templateLocation}/{id}.html
Examples
When you render a content item with ID id123
, name name123
, and locale en
by applying a template that is named myBlueTemplate.hbs
located in folder /blue
, the rendering result becomes available as follows:
- When you use the default URL template, the render result is published to the following URL
{Delivery URL}/blue/id123.html
. You can get the {Delivery URL} from Developer > URL information. - When you define the
urlTemplate
property asurlTemplate:"/some/folder/{name}_{locale}.html"
, the render result is published to{Delivery URL}/some/folder/name123_en.html
. You can get the {Delivery URL} from Developer > URL information. - When you define the
urlTemplate
property asurlTemplate:"/{templateLocation}/{name}/index.html"
, the render result is published to{Delivery URL}/blue/name123/
. You can get the {Delivery URL} from Developer > URL information.
Updated over 1 year ago