Templates files and the CDN (for Piano Content)

Since April 2014 we recommend that you set up your recommendation widgets using template and style objects (see Content recommendations templates and styles), but the method described here (using template files) can still be used.

A normal template file for Cxense Content has the following form:

<!DOCTYPE HTML>
<html>
  <head>
    <style type="text/css">
      #templateElement {display:none}
    </style>
  </head>
  <body xmlns:tmp="javascript:">
    <script type="text/javascript" src="http://cdn.cxense.com/cx.js"></script>
    <div id="targetElement">
      <div id="templateElement">
        <!-- Display logic -->
      </div>
    </div>
    <script type="text/javascript">
      cX.insertWidget();
    </script>
  </body>
</html>

(In some example you will see that the templateElement is placed on the same level as targetElement, rather than inside this element. This is not important.)

Display logic

The display logic of a content template is usually something like this:

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
    var item = items[i];
%-->
  <div>
    <a tmp:id="{{cX.clickTracker(item.click_url)}}" tmp:href="{{item.url}}" tmp:target="_top"><img tmp:src="{{item.dominantthumbnail}}" alt=""></a>
    <a tmp:id="{{cX.clickTracker(item.click_url)}}" tmp:href="{{item.url}}" tmp:target="_top">{{item.title}}</a>
  </div>
<!--%
}
%-->

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

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 Cxense.

Also beware 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, for example, you only want to show recommendations that have a title, then this must be specified using a custom 'filter' parameter in the configuration.

Style

The styling of the widget is usually done by extending the style section in the head of the content template.

Local templates

It may take up to an hour from you upload a content template file until it is available on the CDN. Thus, when designing a content template it is common to work on a local copy.

If you specify the widget ID in the template, you can test it by simply opening the template in your browser, as in this example (simple-recs-improved.html).
However, we recommend that you instead load the template from another html file, like you would in production.
By leaving the widget ID out of the template, you may use the same template for many widgets.

<!DOCTYPE HTML>
<html>
  <body>
    <script type="text/javascript" src="http://cdn.cxense.com/cx.js"></script>
    <div style="float:left">
      <div style="float: left; width: 1210px; margin: 5px; height: 600px; background-color: #fff;">
        <div id="targetElement" style="display:none"></div>
        <script type="text/javascript">
          var cX = cX || {}; cX.callQueue = cX.callQueue || [];
          cX.callQueue.push(['insertWidget', {
              widgetId: 'd7e40132d390284da90266dde8713c75fbb9665e',
              insertBeforeElementId: 'targetElement',
              renderTemplateUrl: 'template.html',
              // resizeToContentSize: false,
              width: 1000, height: 500
          }]);
        </script>
      </div>
    </div>
  </body>
</html>

Templates on the CDN

It is recommended that you upload any templates you want to use in production to the Cxense CDN using the render template editor, which is documented here.
The render template documentation is written for Cxense Advertising, but much much of it also applies to Cxense Content (except that you should use 'insertWidget' instead of 'insertAdSpace'.)

You can also use the render template editor to set up a mapping from your widget ID to your template, so that you only have to specify the widget ID on your site.
See Showing the content widget on your site for further details.

Last updated: June 23, 2026