Content recommendations templates

The content recommendations come with a number of templates to display articles collected with a content collector. The same goes for product recommendations and the product collector. This article describes how these templates can be edited or added.

Warning: you are entering the Developer Zone!

If you are comfortable working with HTML, CSS and Javascript, proceed. If not... It's not too late to turn back!

Start by editing the object and opening the "Design" tab. Here you can select an existing template, or you can edit a template by clicking its name or the edit icon:

design.png

Alternatively, while selecting a template, click the [Add Template] button underneath the template selection:

select.png

This will take you to the template editor. The template editor shows the three sources that together combine to a result: the HTML template, CSS and Javascript. In the bottom right you see a preview of the resulting web page based off the three sources. 

The preview will update as you change the sources. You will see randomly chosen content recommendations emulating what the recommendations would look like in the actual dialogue.

The preview is missing the actual CSS of the page the dialogue will appear on. This means the preview may very well look different from the end result that you will see in the dialogue.

Meta data

You can change the name of the template by editing its name, or click "Show meta data" and edit the description of the template and its preview image (for use in the template selection gallery).

HTML template

The HTML template consists of a combination of HTML and Mustache tags for the control flow. Here is a very basic example of a recommendations template:

<ul>
    {{#recommendations}}
       <li>
           {{#image}}<img src="{{image}}" />{{/image}}
           {{name}}
       </li>
    {{/recommendations}}
</ul>

This template builds a list of recommendation items consisting of an optional image and a name.

Let's break down this template by its Mustache tags. First there is the loop over all recommendation items using the recommendations Mustache tags:

    {{#recommendations}}
         ...
    {{/recommendations}}

Then, for each recommendation item determine if an image URL is available using the image Mustache tags: 

        {{#image}} ... {{/image}}

When a URL exists for the item, use the image Mustache tag to fill the src attribute: 

            <img src="{{image}}" />

Also display the name of the item:

            {{name}}

The table below displays all Mustache tags that are available for each recommendation item. Note that Mustache tag names are case sensitive.

Tag Name Description
gated true if the recommendation item is gated from access to the general public, false otherwise.

Example usage:
{{#gated}}
    Gated content
{{/gated}}
{{^gated}}
    Free content
{{/gated}}
score The calculated recommendation score for the item, e.g. 1.0
image The URL of an image for the recommendation item, if available. E.g.: https://dogfood.blueconic.com/rest/contentStores/315ac9c5-666a-48dc-84ac-741d4f4da3e9/items/www.blueconic.com%252Fbenefits%252F/image?etag=1499708703368
name The name or title of the recommendation item, e.g. BlueConic - Know the Individual. Drive Better Outcomes.
description The description of the recommendation item, e.g. Use BlueConic to recognize an individual at each interaction, and synchronize their intent across the marketing ecosystem.
ID The unique identifier for the recommendation item, e.g. www.blueconic.com/pricing/
recommendationId The BlueConic identifier for the recommendation item, e.g. 8890a595-aa56-454f-a2d0-abb28f7c2ebf
category The categories for the recommendation item, e.g. customer engagement, customer experience management, marketing management software, user behavior analytics
URL The URL for the recommendation item, e.g. https://www.blueconic.com/pricing/
isFirstItem true if the item is the first of the list, false otherwise.

Example usage:
<div class="col-sm-3{{#isFirstItem}} first{{/isFirstItem}}">
isLastItem true if the item is the last of the list, false otherwise.

Example usage:
<div class="col-sm-3{{#isLastItem}} last{{/isLastItem}}">
index The index of the item in the list of recommendation items, e.g. 0
creator The name of the creator of the recommendation item, e.g. BlueConic
Data field ID of any field Use the Data field ID of any field you added in the content collector connection to retrieve its value.

Pro tip: To best blend in recommendations on a page, find a block of items that looks the way you want, inspect it and copy/paste the HTML of that block into a new template. Then add {{#recommendations}} ... {{/recommendations}}, reduce the number of items to 1 and replace {{name}} and other Mustache tags as needed. Your template will fit right in the page and play nice with its CSS!

 

CSS

The CSS source determines what the list of recommendations will look like. This works like regular HTML and CSS, but it is important to remember that the recommendations will be shown on an existing page that has its own HTML and CSS. Chances are the page styling will interfere with your styling of the recommendations or vice versa. 

This is why the best practice is to "namespace" the recommendations with a unique class name on the outer element. This allows you to uniquely override page styling with specific recommendations styling, while also making certain page styling is left untouched.

Here is an example of how to apply a namespace "basic-list" to the basic template we showed earlier:

<ul class="basic-list">
    {{#recommendations}}
       <li>
           {{#image}}<img src="{{image}}" />{{/image}}
           {{name}}
       </li>
    {{/recommendations}}
</ul>

In the CSS we apply the namespace class to every rule in our source. This will prevent styling from bleeding over into the rest of the page.

ul.basic-list {
    ...
}
.basic-list li {
    ...
}
.basic-list img {
    ...
}

While this namespacing prevents our content recommendations styles from bleeding over into the rest of the page, the reverse is not true. There still may be styling rules on the page that have an unwanted effect on the recommendations.

To deal with this, inspect the culprit in the browser using the right mouse button, and determine the rules that set the offending CSS properties.

For example, if the inspector shows that our ul element inherits a margin-bottom of 20px from the page:

We can counter this by adding our own, namespaced version of this rule to our CSS code:

ul.basic-list {
    margin-bottom: 0;
}

The same technique would also work with more complex rules; copy the selector from the browser and make it more specific with your namespace, e.g.:

/* Overruling selector "body nav.suggestions ul li" */
body nav.suggestions ul.basic-list li {
    background-color: #fff;
}

 

Javascript

In the Javascript source you can optionally add Javascript that should be executed after the recommendations template has been rendered - i.e. the elements created by the template will exist by the time the script runs.