Rendering CCE Modules | Documentation

Rendering CCE Modules: Presentation and Click Tracking

CCE utilizes and extends standard Cxense Content template and style objects (see Content recommendations templates and styles). Hence the presentation class of /widget APIs described at Cxense Content API apply to CCE as well.

Usage

Everything needs a target div id. Even if there is no direct message to deliver into that div, the code looks for it to at least put (invisible) templates in there.
As the template object is injected into the DOM, it is important that it does not create invalid HTML or has a visible appearance / may cause the browser to fetch things. Hence use tmp: namespace on things like classes, ids and image src attributes. When the template "runs" it will remove all tmp: usage.
For things like click tracking we register event listeners, so any use of jquery click handlers etc will break tracking / execution. Always use the cx click tracker for capturing clicks, and use the callback if you want to do something else in addition.
Sequence of events for inserting a widget:
1. Call cX.CCE.run()
  1. /public/widget/data is invoked under the hood using JSONP
2. When API response comes, template is injected into the template div.
  1. All custom code is invoked, so make sure code that is to be run based on result data is wrapped in functions and called from within the template itself.
3. The template code is run with the API data as context (typically a for loop over items), injecting the actual results either within the same parent div
  1. It is possible to invoke custom functions within the template itself when it runs, but if it accesses the dom for the html that is currently being generated, make sure to wrap the function with a window.requestAnimationFrame so it is executed when the template has completed and dom is updated.
4. If the parent page that added the code into the page (calling cX.CCE.run) also has custom code to run, the third parameter to cX.CCE.run() can include a callback method that is invoked once everything has been rendered into the page and DOM has been updated.

Click Tracking

As seen in Content recommendations templates and styles, the clickTracker helper function should be used in the anchor element, for example:

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  %-->
  <div class="item">
    <a tmp:id="{{cX.CCE.clickTracker(item)}}" 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>
  <!--%
}
%-->

The client-side library cx.cce.js extends cx.js's native click tracking functionality to also support Ajax style applications where clicks may not trigger page navigation.

If you would like to add URL parameters to the target URL, you can pass key-value pairs to the helper function:

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  var param = {'key1': 'value1'};
  %-->
  <div class="item">
    <a tmp:id="{{cX.CCE.clickTracker(item, undefined, param)}}" tmp:href="{{item.url}}" tmp:target="_top">
[...]

When a user clicks on the link, the URL the user gets redirected to will have the parameter like this:

https://www.example.com/article/cxense_announces_new_product_offerings.html?key1=value1#cxrecs_s

When you click on the anchor elements like the sample codes above, it first takes you to a click tracking URL then immediately redirects you to the recommended article. If you would like to avoid this redirect (but still would like to track clicks), use the clickTracker with a callback (the second parameter):

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  %-->
  <div class="item">
    <a tmp:id="{{cX.CCE.clickTracker(item, onClick)}}" tmp:href="{{item.url}}" tmp:target="_top">
[...]

You will then write the callback function in the Custom JavaScript section of the CCE "Presentation & display" section:

function onClick(item) {
  window.location.href = item.url;
}

Adding personalized content into a web page

Content is inserted into the page invoking cX.CCE.run(), specifying at least a widget id and a target div.

    cX.CCE.run({
        widgetId: '189f829ad43b558e45cfd2a2ae9e618721f8696a',
        targetElementId : 'cx-frame-target'
});

The object specified as input to this method supports many of cx.js' insertWidget's parameters. Similar to cx.js it also supports additional context specified as a second javascript object. It also supports a callback function to be specified as the third parameter.

In the cx.cce.js script, visibility tracking of widgets is built-in, thus no special coding on the page is needed to make it work. The only prerequisite is that the target element must conform to either one of the following:

Proper height is given to the target element
Class `cx-visibility-element` is given to an element (with non-zero height) to be used to track visibility

Note that a widget is considered "visible" when more than 50% becomes visible on the browser window. If the widget is too large for the device, the visible impression will not be counted. In such cases, you can instruct CCE to count visible impressions when a fraction of the widget becomes viewable by adding the following line to the module script:

cX.CCE.callQueue.push(['setVisibilityField',"timeSome"]);

Placing the content within an iframe

By default the content will be placed directly into the DOM of the parent page. To instead place the content within an iframe, these additional parameters can be specified:

renderTemplateUrl: 'auto'
Specify initial width and height of widget.
Set resizeToContentSize to true or false.
- false: Keep initial size of frame independent of size of content. Size content will remain unchanged and no elements on page will 'bounce" but content may be clipped/there may be white space surrounding content.
- true: Resize the frame after content is available to match the size of the displayed content. There may be some "bouncing" of page elements after content is available, but content will fit better in with rest of page

Example:

    cX.CCE.run({
        widgetId: '189f829ad43b558e45cfd2a2ae9e618721f8696a',
        targetElementId : 'cx-frame-target',
        renderTemplateUrl: 'auto',
        width: 650,
        height: 1000
        resizeToContentSize: false,
    });

Last updated: January 25, 2022