Handlebars

Handlebars is an off the shelf templating technology that allows developers to specify the structure of the HTML generated from a piece of JSON content. The content rendering service includes the built-in handlebars features, such as loops, ifs and conditional branching, but also includes a number of other utilities, or helpers, that developers may find useful in structuring their templates.

Supported helpers

We have included most of the helpers defined in the handlebars helpers GitHub repository and the full list of supported helpers is shown below.

  • 'array'

  • 'collection'

  • 'comparison'

  • 'date'

  • 'html'

  • 'markdown'

  • 'math'

  • 'misc'

  • 'number'

  • 'object'

  • 'regex'

  • 'string'

  • 'uri'

Markdown helper

The markdown helper makes it easier for developers to convert text entered by users in markdown format, such as in a blog content item, to HTML.

Markdown text should be included within #markdown blocks in a handlebars template. In the example handlebars template below, the content type has a property called "blogtext" that contains markdown text.

{{#markdown blogtext}} 
{{/markdown}}

If the blogtext property contained the following markdown:

# This is heading 1
## This is heading 2
### This is heading 3

it would be converted into the following HTML:

<h1>This is heading 1</h1>
<h2>This is heading 2</h2>
<h3>This is heading 3</h3>

Handlebars templates

Templates are uploaded to Content Hub as .txt or .html files. You can also create the templates directly in Content Hub using the Text Editor app. A template must be published so that it can be used by the content rendering service.

An example template is shown below. This is used to structure the HTML for the tutorial banner slot and we've uploaded it to Content Hub as 'banner_slot_template.html'.

{{#with bannerslot}}
<div id="contentRender"></div>
  <div class="banner">
   <div class="banner-editorial">
     <div class="banner-header">{{headline}}</div>
       <div class="banner-subheader">{{strapline}}</div>
     </div>
     <img class="banner-background-image" 
       src="https://{{background.defaultHost}}/i/{{background.endpoint}}/{{background.name}}">
     <a class="banner-call-to-action" href="{{calltoactionurl}}">{{calltoactiontext}}</a>
   </div>
{{/with}}

If we know that a piece of content is a banner, then we can make a request to the content rendering service as follows:

https://c1.adis.ws/v1/content/ampproduct/content-item/7ba216e9-7db2-41fa-ba0b-e1833f162be0?template=banner_slot_template

where 7ba216e9-7db2-41fa-ba0b-e1833f162be0 is the slot ID of this piece of content and banner_slot_template is the name of the template. Replace "ampproduct" with the name of your store.

The disadvantage of referencing a specific handlebars template for a particular slot or type is that you have to know that the content is a banner. You would have to use a different URL for each content type and this makes the code more difficult to maintain. That's where the handlebars partials feature is useful.

Partials

Partials is a handlebars feature that allows one template to load another. This lets you create a structure where you have one or more top level templates and separate templates for each content type, so you can specify the same template in each call to the content rendering service.

Partials are a useful way of structuring templates to allow for re-usable code. Your content types are likely to load a number of partials that are shared between several different types. For example a banner might load a button partial or an image partial.

The partials syntax is as follows:

{{> partialName}}

In order to make full use of partials, you also need to be able to determine the content type, so you know which template to load in. You would then end up with a top level template such as:

{{#if (test this.[@type] (toRegex ".*/tutorialbanner")) }}
 {{> banner_template }}
{{/if}}
{{#if (test this.[@type] (toRegex ".*/featurevideo")) }}
 {{> video_template }}
{{/if}}

In this example banner_template and video_template could then load further partials depending on how you structured your templates. The template matches the content type with the corresponding handlebars template and then loads in the right one, in this case either a banner or a video. So, if we called our top level template 'top_template', we would make a request to the content rendering service.

https://c1.adis.ws/v1/content/ampproduct/content-item/cea10270-7c3f-44b8-88d3-475956d2a901?template=top_template

and the correct template would be chosen to render the content.

When a new content type is added, you'd just upload it to Content Hub and update the top level template, in this case content_template, with the new content type ID.

Referencing the content type in a handlebars template

The content type shown in the handlebars template above is the content type URI, specified when the content or slot type is registered with a hub. If you want to make use of partials to organise your handlebars templates, then you will need to name your content and slot types so you can choose the appropriate template based on the content type name.

Limitations

To maintain performance, there are certain limits imposed by the content rendering service. For each call, you are limited to 50 distinct templates. The service is limited to loading 50 distinct templates per call. 1000 partial loads. However, you are unlikely to hit these limits in normal usage.

results matching ""

    No results matching ""