We’ve migrated our documentation to a new site, which means some URLs have changed.
Audience
Audience
Breadcrumbs

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 associated with a widget definition in a separate IFrame.

In some cases, however, it makes sense to do things a bit differently. Here we discuss some of the alternative options – from high-level to low-level integration.

The "insertWidget" implementation and rendering techniques are very similar to the "insertAdSpace", in fact they are implemented both based on 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 Cxense CDN

Template files can be hosted anywhere. In particular, they can be hosted on the Cxense 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 Cxense 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 Cxense CDN even if your web pages use HTTPS: If a render template URL that 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 specify a function, which is then responsible for the rendering 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: