Content recommendations templates and styles

Content templates

Depending on the context, the term "render(ing) template" has various meanings:

• an HTML element using a simple templating language embedded in cx.js,

• an HTML file containing a template in the above sense (and a few other things), or

• a template object consisting of the inner HTML fragment using the templating language mentioned above.

In April 2014, the recommended way to present content recommendations changed. Instead of template files, use template and style objects. The "old approach" using template files is described on this page: Template files and the CDN (for Piano Content). To convert a template file, create a style object from the CSS and a template object from the template element's inner HTML.

Template objects

A template object describes how to convert content recommendations to HTML. This is formulated using a simple templating language. Template objects can be managed using the Piano Content API, but it is more convenient to use the editor in the Admin user interface (see Piano Content User Interface). When you create a new template object, the editor window is filled with an example template which you can use as a starting point. The example looks as follows:

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  %-->
  <div class="item">
    <a class="allclick" tmp:id="{{cX.clickTracker(item.click_url)}}" tmp:href="{{item.url}}" tmp:target="_top">
      <!--%
      cX.renderContainedImage({
        container: { width: 321, height: 160 },
        image: { src: item.dominantthumbnail, dimensions: item.dominantthumbnaildimensions }
      });
      %-->
      <h3>{{item.title}}</h3>
    </a>
  </div>
  <!--%
}
%-->

Here we use the templating language in order to create a div-element for each recommendation item.

Helper function: clickTracker

Observe that we set the id to the anchor elements using the function cX.clickTracker.

This has the effect that a user who clicks on the (recommendation) link is sent via item.click_url – not directly to item.url. This is important, as this is how the click gets registered by Piano Content.

Helper function: renderContainedImage 

The function cX.renderContainedImage is explained here: Image rendering helper function
In short, we use this function (instead of a simple img tag) to handle differences in sizes and aspect ratios.

Observe that in order to use this function, you have to specify the dimensions in the template code (rather than in the style, which might seem more natural).

Also observe that the fields available for a given recommendation item may only be a subset of the fields specified as 'resultFields' in the content configuration. If you only want to show recommendations that have a certain field, then this must be specified using a custom 'filter' parameter in the configuration. 

Style objects

A style object contains the CSS that should be used for a content widget. Style objects are most conveniently managed using the corresponding editor in the Admin user interface (see Piano Content User Interface). When you create a new style object, the editor window is filled with an example style which you can use as a starting point.

Last updated: September 10, 2026