Help Center

In BlueConic, you can create personalized content recommendations with a number of available templates to display articles collected with a content collector. This article describes how you can edit or add to these personalization templates in Dialogues.

Warning: You are entering the Developer Zone! Continue reading if you are comfortable working with HTML, CSS, and JavaScript.

Selecting or modifying an existing template for personalized recommendations

Sometimes you will want to modify an existing recommendations template. Start in the BlueConic Dialogue editor 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:

If the existing designs work fine with your website, great! However, in our experience, website designs vary greatly and the standard designs will likely not blend in perfectly with your website. Read on to learn how to best create a new template that will blend in perfectly.

Creating a new personalization template

The best way to integrate personalized recommendations into your website is to:

• Pick the position on the page where you want the recommendations to appear.
• Copy the HTML from that position.
• Make a template from the copied HTML.
• Have the BlueConic Dialogue appear on the position you picked.

This has several advantages:

• No need to cook up your own HTML - reuse what is already there.
• No need to add CSS - you're working with HTML originally from the website, so existing styling will automatically play well.
• No need to think of responsive design - the dialogue will be just as responsive as the original HTML was.

The example below illustrates how to create a new template from existing HTML.

Start by clicking the Add new template button underneath the template selection:

This will take you to the template editor. The template editor shows the three sources that together produce your content: the HTML template, CSS, and JavaScript. On the bottom right, a preview shows the resulting web page based on these 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.

Metadata

You can change the name of the template by editing its name, or click Show metadata 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}}&width=200&height=100" />{{/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}}&width=200&height=100" />

It is recommended to add width and height to serve a specific size of image, to minimize bandwidth usage for the visitor. 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.

{{#gated}}
    Gated content
{{/gated}}
{{^gated}}
    Free content
{{/gated}}

<div class="col-sm-3{{#isFirstItem}} first{{/isFirstItem}}">

<div class="col-sm-3{{#isLastItem}} last{{/isLastItem}}">

Pro tips:

• 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.
• If you collect properties that contain multiple values, you can iterate over the values and display them individually using the following example for a content collector that is collecting {{tags}}.

<div class="post-tags">    
    {{#tags}} // iterate over the tags property                                                                                                                                                                                                                                          
        <a href="https://www.taylor-store.com/tag/{{.}}" class="topstories-tag">{{.}}</a> //{{.}} will display the currenttly parsed value   
    {{/tags}}                                                                                                                                                                                                                                
</div>

CSS

The CSS source determines how the list of recommendations will look. This works the same way as regular HTML and CSS, but it's 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 recommendation 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}}&width=200&height=100" />{{/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 recommendation 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, for example:

/* 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 recommendation template has been rendered - i.e., the elements created by the template will exist by the time the script runs.