Showing the content widget on your site

Prerequisites

The Cxense Content Integration Guide lists all the steps needed for setting up a content recommendation widget. Here we focus on the last of these steps: showing the widget on your site. Thus, we assume that you have already set up a widget object and a template.

You must also make sure that cx.js script is loaded (on the page where the recommendation widget should appear). This is already taken care of if the page contains the Cxense Analytics script (see the Platform primer). Otherwise, you can use the following script tag:

<script type="text/javascript">
  (function() { try { var scriptEl = document.createElement('script'); scriptEl.type = 'text/javascript'; scriptEl.async = 'async';
  scriptEl.src = ('https:' == document.location.protocol) ? 'https://scdn.cxense.com/cx.js' : 'http://cdn.cxense.com/cx.js';
  var targetEl = document.getElementsByTagName('script')[0]; targetEl.parentNode.insertBefore(scriptEl, targetEl); } catch (e) {};} ());
</script>

The recommended placement is at the very end of the page, e.g., just before </body>.

Insert a target element

Put an empty div-element with a unique ID where you want the widget to appear.

<div id="cxenseWidget1" style="display:none"></div>

Observe that

1. the widget will actually be injected right before this element,

2. by the term "widget ID", we do not mean the ID of this element (but of the widget object).

Include a small script

You must also include a small script. It is most common to place this right below the div-element, but it can appear anywhere on the page. In this script you express

1. that you want to insert a widget,

2. the widget ID,

3. the ID of the element where you want the widget to appear (described above),

4. whether to use an "embedded" or a "mapped" template (or the URL of the template that should be used), and

5. the initial size of the widget iframe (in pixels).

If you have specified template and style objects as part of your widget configuration, the script will look like this:

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

This is the recommended approach since April 2014.
Notice the line that says: renderTemplateUrl: 'auto'

If you have set up a "mapped render template" on the Cxense CDN, you should specify this instead:

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

If you have a CDN-based template but no mapping (or just want to try out a different template), you can specify the template URL directly instead:

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

By default, the size of the iframe is changed to the actual widget size as soon as the template is rendered. This can be disabled setting "resizeToContentSize: false":

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

Definition of a context-object

Explicit setting of a context-object as defined by /public/widget/data.

Best practice available: how to Using "context" as a dynamic parameter for content-configurations.

<script type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertWidget',{
      widgetId: 'd7e40132d390284da90266dde8713c75fbb9665e',
      insertBeforeElementId: 'cxenseWidget1',
	  renderTemplateUrl: 'auto',
      width: 1000, height: 500
  },
  { context: { pageclass: 'frontpage', categories: { taxonomy :'sports/motor/f1' } } }
  ]);
</script>

Automatic resizing

One reason you might want to disable automatic resizing is that it does not always work as expected "out of the box".

For resizing to work properly with CDN-based templates you should make sure that the  the rendered iframe contents does not have any (outer) margins.
(If you use template and style objects, this is already taken care of.)

Here is an example where resizing is set up to work correctly:  page-newsrecs-2013.html
Observe that in this example the template contains the following CSS:

html, body, div {width:400px; margin: 0; padding: 0; outline: 0}

 It is easier to set up resizing if you can keep either the width or the height fixed.

Last updated: February 04, 2022