Render HTML pages

In Content, you can now use Handlebars-based templates that reference elements within content items to generate custom HTML pages from that content. Existing public Content samples on github.com show how to use Handlebars in client browser JavaScript to combine templates with content. This tutorial describes how to use the new pre-rendering feature of Content to combine templates, layouts, layout mappings, and content to render custom HTML pages during content publishing to the delivery services and CDN.
Your company has a new product, which is set to be available in the spring in various models. Your product team, the information architect, channel manager/content creator, and the creative designer are working on the new content for a marketing flyer. They collaborated on a comprehensive design with the creative design team. The design shows how the product is displayed. As a developer, you need to create a template. Using your preferred local IDE, create a handlebars template, with references to your content elements. Create a layout, specifying metadata for your template. Then, create a layout mapping, which specifies the mapping between your layout, and a content type. Using wchtools, then push all of these artifacts to Content.

Before you begin

To get started, you need:

• Your Acoustic Content subscription.
• Content developer tools. For more information on how to download and install the Content tools, see wchtools readme
• The design requirements from the creative design team. For example, a flyer page with a title, image, and description.
• The sample-article-content sample. Download and push the sample "Article" type, assets, image profiles, content, categories, and renditions, along with sample article content.

Retrieve the element keys for the content type

You can get the keys for the elements from the JSON for the type. You can get the JSON by downloading the content type with the CLI or from the Acoustic Content UI.

Retrieve the JSON information from Content UI:

1. Log in to the Content UI and from Developer > Content types.

📘

Note:

You must log in as an admin or manager to access the content type that is created by your information architect.

2. Open the content type that you want and click API information icon and then View JSON.

Create the web asset

Build the web assets for all of the new layouts in your development environment and add them to /assets/ folder.

Under the assets:

1. Create a project with web artifacts that you want to publish including the CSS classes, images, icons, and JS code as needed to control the style, look, and dynamic behavior.
2. Create a handlebars template under working-dir/assets/templates/article.hbs for the "Article" content type.
3. Reference the elements in your content item from the handlebars template by adding the keys that you retrieved from the content type JSON.

<div>  
              ...  
                <img src="{{elements.image.url}}" alt="" width="360" height="225">  
              ...  
                <h4 style="color:#000;padding:25px 0px 5px 0px">  
                    <a>{{elements.title.value}}</a>  
                </h4>  
    </div>

Create the layout

The layout files map to the handlebar files and provides the metadata around the Handlebar files such as name, template and etc. Template is the path name to where the Handlebar files are located. Create an ID for the layout to reference the layout in the layout mappings. Set the prerender field to true for the Content to prerender the content.

📘

Note:

The default is false that is the content layout is ignored by Content and the content is not prerendered. For more information about creating layouts, see API Reference.

Example: Create the following layout metadata in working-dir/layouts/templates/article.json

{  
     "id": "mylayout"  
     "name":"Default Article Layout",  
     "prerender": true,  
     "template":"/templates/article.hbs"  
      
    }

In the layout JSON file, add a description and a thumbnail for the layout out to display in the Content UI. The content composers can then select a layout that displays in the Content UI when they create content. For more information about selecting a layout for the content, see Content: Compose with consistency.

{  
     "id": "mylayout",  
     "name": "Default Article Layout",  
     "description": "This is the default layout",  
     "prerender": true,  
     "thumbnail": {  
     "id": "16da978c-60e6-401d-b51a-6665faaa885f",  
     "url": "/authoring/v1/resources/8ba9371eaa301921af8c70de4eb91163?fit=inside%7C220:145",  
     "path": "/dxdam/16/16da978c-60e6-401d-b51a-6665faaa885f/bald\_eagle.jpg"  
     },  
     "template": "/templates/article.hbs",  
     "templateType": "handlebars"  
    }

Create the layout mapping

Layout mapping files map the layout to the content type.

📘

Note:

You need to create separate mapping files to map layout for different content types. For example, you have two different content items with different images and text. To map the layout for the flyer to both the content items you have, you would need to create two separate mapping files.

Example: Create the following layout mapping metadata in working-dir/layout-mappings/templates/articleMappings.json
Map to the type
Example layout mapping to type

{  
     "id": "articleLayoutmappings"  
     "name":"Article Layout mappings",  
     "type":{  
       "name": "Article"  
    }

Map to the layout
Example layout mappings to layout

"mappings": \[  
       {  
        "defaultLayout": {  
           "id": "defaultArticleLayout",  
           "name":"Default Article Layout"  
    }

After you create the layout mapping, it should have the following information

{  
     "id": "articleLayoutmappings"  
     "name":"Article Layout mappings",  
     "type":{  
     "name": "Article"  
    },  
    "mappings": \[  
     {  
     "defaultLayout": {  
     "id": "defaultArticleLayout",  
     "name":"Default Article Layout"  
    },  
    "layouts":\[  
     {  
         "id":"defaultArticleLayout",  
         "name":"Default Article Layout"  
        }  
       \]
        
      }
       
     \]  
    }

Upload the web assets to Content

Push the web assets, layout, and layout mappings to Content using the wchtools 1.3 or a newer version. When the content and content types that are referenced in the handlebar files and layout mappings are ready, Content publishes and renders the content into the CDN. 

wchtools push -A --dir <path-to-working-directory>

📘

Note:

To upload web resource assets, place them below the assets folder in your working directory anywhere except under assets/dxdam/... path.

Publishing and rendering content

Content is published and rendered if it has a valid layout mapping when the status is changed from draft to ready state. If the article content was in the ready state before you created and pushed the templates, layout, and layout mapping, then that content was published before these artifacts were known to Content. To republish content for rendering, change each content item to draft and then back to ready state, or use the new wchtools render -r command to create a publishing job. The publishing job renders already published content without having to republish that content.

Access the rendered content

The content is rendered in the following URL template by default. You can access the rendered content by creating the URL as follows

https://{Delivery URL}/templatelocation/Item ID.html

To get the Delivery URL, go to Developer > URL information page.

The template location is the location of the Handlebar file in your working directory. For example, for a Handlebars template that is located in working-dir/assets/templates/, the template location for the default URL generation is /templates.
You can get the item ID by opening the content item and clicking API Information.

📘

Note:

You can define the URL for the rendered content by providing the URL template in the corresponding layout. For more information, see Rendering.

Expected outcome

The rendered content displays the content as an HTML page with the markup defined in the layout template based on the design.