IBM Watson Content Hub rendering feature automatically generates HTML markup for content that is managed in Watson Content Hub. The generated HTML documents or fragments are automatically published to the CDN for efficient worldwide delivery. As a result, you can reference the rendered web assets through the wchtools command line interface with relative URLs. You can control the URL format for the generated documents and fragments with the URL templates.

To render the content:

  1. Create HTML templates to define the specific markup format that you want to generate for a specific type of content.
  2. Create layouts and layout mappings to define how to render formatted content in a site. You associate a template to a content type through the layout mappings. Content types are created in Watson Content hub.
  3. Upload the corresponding rendering templates to Watson Content Hub with the wchtools command line interface or the public REST API of Watson Content Hub.

Generated render results get pushed as static files to the WCH 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 Watson content hub 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.

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. The JSON record available in Watson Content Hub is called the rendering context.

The rendering context available to your Handlebars template has the same JSON structure as the JSON returned by the Delivery Content service. The Handlebars JSON is extended by 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 selector layout.
  • The Hub context – The context.hub context provides access to the API and static resource delivery URLs of your WCH service instance.
  • API URL Context – The context.hub.apiUrl context provides access to the API base URL.
    API URL path name

    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 my.digitalexperience.ibm.com
    context.hub.apiUrl.host The API URL host value. {{context.hub.apiUrl.host}} generates my.digitalexperience.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://my.digitalexperience.ibm.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://my.digitalexperience.ibm.com/api/e123456a-12c3-12d3-9f7b-0de12f345e67
  • Resource URL Context – The context.hub.deliveryUrl 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 my.digitalexperience.ibm.com
    context.hub.resourceUrl.host The resource URL host value. {{context.hub.resourceUrl.host}} generates my.digitalexperience.ibm.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://my.digitalexperience.ibm.com
    context.hub.resourceUrl.href The resource URL href value. {{context.hub.resourceUrl.href}} generates https://my.digitalexperience.ibm.com/e123456a-12c3-12d3-9f7b-0de12f345e67

    Example

    {
    "apiUrl": {
    "pathname": "/api/e123456a-12c3-12d3-9f7b-0de12f345e67",
    "hostname": "my.digitalexperience.ibm.com",
    "host": "my.digitalexperience.ibm.com",
    "protocol": "https:",
    "origin": "https://my.digitalexperience.ibm.com",
    "href": "https://my.digitalexperience.ibm.com/api/e123456a-12c3-12d3-9f7b-0de12f345e67"
    },
    "deliveryUrl": {
    "pathname": "/e123456a-12c3-12d3-9f7b-0de12f345e67",
    "hostname": "my.digitalexperience.ibm.com",
    "host": "my.digitalexperience.ibm.com",
    "protocol": "https:",
    "origin": "https://my.digitalexperience.ibm.com",
    "href": "https://my.digitalexperience.ibm.com/e123456a-12c3-12d3-9f7b-0de12f345e67"
    }
    }

    Accessing 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. Note: 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:

    1. When you use the default URL template, the render result is published to the following URL https://your-api-host/your-tenant-id/blue/id123.html
    2. When you define the urlTemplate property as urlTemplate:"/some/folder/{name}_{locale}.html", the render result is published to https://your-api-host/your-tenant-id/some/folder/name123_en.html
    3. When you define the urlTemplate property as urlTemplate:"/{templateLocation}/{name}/index.html", the render result is published to https://your-api-host/your-tenant-id/blue/name123/

    Join The Discussion

    Your email address will not be published. Required fields are marked *