Using Piano Content without a template object

The standard way to include a recommendations widget on your site is to render the template and style objects from a widget definition in a separate iframe.

In some cases, it makes sense to do things differently. Below we describe alternative options for integration, from high-level to low-level.

The "insertWidget" implementation and rendering techniques mirror those of "insertAdSpace"; both use the same internal functionality.

Creative template / Client-side template-based rendering could be a valuable additional source for advanced techniques and examples.

Template files

Template and style objects were introduced in April 2014. Before that, the usual way to include a widget was to use a separate template file.

A normal template file has the following form:

<!DOCTYPE HTML>
<html>
  <head>
    <style type="text/css">
      html, body { margin: 0; padding: 0; outline: 0; border: 0; }
      #templateElement {display: none}
      /* Style */
    </style>
  </head>
  <body xmlns:tmp="javascript:">
    <script type="text/javascript" src="http://cdn.cxense.com/cx.js"></script>
    <div id="targetElement"></div>
    <div id="templateElement">
      <!-- Template -->
    </div>
    <script type="text/javascript">
      cX.insertWidget();
    </script>
  </body>
</html>

Here the template element should contain the display logic that you would otherwise put in your template object. Similarly, you may add extra styling to the style element.

In order to use a template file with your widget (instead of template and style objects), you specify the URL of your template file as renderTemplateUrl in your call to insertWidget.

<script type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertWidget',{
      widgetId: 'd7e40132d390284da90266dde8713c75fbb9665e',
      insertBeforeElementId: 'cxenseWidget1',
      renderTemplateUrl: 'http://www.example.com/template.html',
      width: 200, height: 500
  }]);
</script>

Template files on the Piano Content CDN

Template files can be hosted anywhere. In particular, they can be hosted on the Piano Content CDN. You can put files on this CDN and edit them later using via the Admin application (under Rend.templ.). Beware that it may take up to 1 hour for changes to take effect.

If the file "abc.html" is put on the Piano Content CDN, it becomes available as http://cdn.cxpublic.com/abc.html. In other words, you can use this as your renderTemplateUrl.

You can also set up a mapping between your template and your widget ID, in which case you can drop the renderTemplateUrl parameter.

<script type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertWidget',{
      widgetId: 'd7e40132d390284da90266dde8713c75fbb9665e',
      insertBeforeElementId: 'cxenseWidget1',
      useMappedRenderTemplate: true,
      width: 200, height: 500
  }]);
</script>

Observe that you may host the template on the Piano Content CDN even if your web pages use HTTPS: If a render template URL starts with "'http://cdn.cxpublic.com/", then on secure web pages 'insertWidget' will use a secure alias instead.

Embedded render template / Rendering without an IFrame

By default, insertWidget renders the widget in a separate IFrame. This has several advantages, but a template element can be part of the article page itself.

Example

http://cdn.cxpublic.com/embedded-newsrecs-2013.html

This is similar to the example http://cdn.cxpublic.com/page-newsrecs-2013.html,
except that the template is on the same page and there is no iframe.

Choosing different IDs for the template and target elements

By default, 'insertWidget' looks for template and target elements with the IDs "templateElement" and "targetElement", respectively. However, when the template is not in a separate iframe, it may be safer to use different IDs.

<script type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertWidget',{
      widgetId: '69c0ca55586b5c0856d4286c623e3c66017b5ad5',
      templateElementId: 'templateElement4',
      targetElementId: 'targetElement4',
      width: 400, height: 500
  }]);
</script>

Using a render function instead of a template

Instead of template and target elements, you may provide a function that renders the widget.

<script type="text/javascript">
  function myRenderFunction(data, context) {
      alert('You received ' + data.response.items.length + ' recommendations.');
  }

  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertWidget',{
  widgetId: '69c0ca55586b5c0856d4286c623e3c66017b5ad5',
  renderFunction: myRenderFunction
  }]);
</script>

This function is then called as soon as the recommendations response arrives.

An explanation of this in the context of Cxense Advertising can be found here: JavaScript-only rendering

Calling /public/widget/data manually

Finally, you may make explicit calls to the API: /public/widget/data

On a web page, you can make a JSONP request by passing an argument named 'callback'. However, on a web page it is usually a better idea to use the 'insertWidget' function as explained above.

Explicit API calls are mainly used to deliver recommendations inside mobile Apps or other non-web applications.

Last updated: September 10, 2026