All About Renderers

What is a Renderer?

A Renderer is used by the ATG Recommendations service to turn data about recommendations into HTML on the page. Renderers give the developer a way to control how recommendations are placed into the DOM without having to worry about any of the underlying architecture.

A Renderer (blue) uses a Recommendation Builder (red) to create recommendations:

How can I use Renderers?

A Renderer should be used to specify the HTML structure of recommendations on the page and any special scripting. This is different than controlling page layout and styling as these should be left to CSS. This is also different from specifying the contents of individual recommendations, which should be handled by the Recommendation Builder.

There are a variety of Renderers provided out-of-the-box which all display recommendations in different ways. For example, choosing the List Renderer will cause the recommendations to appear in an unordered list, while choosing the Wiper Renderer will cause the recommendations to appear in blocks that are periodically moved to display other blocks.

Enabling a Different Renderer

The default Renderer is the Tiles Renderer. To use a different Renderer a parameter should be added to the recommendation slot. Add the -renderer parameter with the name of the desired Renderer as its value. The Renderer must also be registered with CleverSet.renderer() which we will cover below.

For Example:

<div id="cs-recslot" class="cs-slot">
    <dl class="cs-cfg" style="display: none">

      <dt>headerText</dt><dd>Recommended Products:</dd>

      <dt>numRecs</dt><dd>6</dd>

      <dt>-renderer</dt><dd>My_Custom_Renderer</dd>

    </dl>
</div>

 

Renderer Specification

A Renderer is a function that conforms to the Renderer API. It must be registered using the built-in function CleverSet.renderer(). It is passed certain parameters and should not return anything. It is expected to operate directly on the objects it is passed.

Parameters

this—the data object returned by the ATG Recommendation servers for this slot to display

{
  headerText: header text to display (optional)
  "rec-set": (internal use),
  "recs": array of data objects for CleverSet.build_rec()
}

wrapped_slot_element—a jQuery wrapped reference to the recommendation slot element where the recommendations should be displayed
(note: the DOM element may be accessed using the jQuery method .get(0))

jQuery—a reference to the included copy of jQuery

Returns

Void—directly appends content to the slot element

Utility Functions

There are a number of utility functions which may be used in the Renderer to implement common functions.

• CleverSet.build_rec(slot_name, data_object, recommendation_builder)

  Used to generate the HTML of the individual recommendations with a Recommendation Builder. This should be called for each index of this.recs[].

Parameters

slot_name—the id attribute of the recommendation slot element passed to the renderer

data_object—one index of this.recs[]

recommendation_builder—(optional) string containing the name of the Recommendation Builder to use by default

Returns

a DOM element containing the HTML to display for an individual recommendation

• CleverSet.fx.setInterval(id, function, period)

  Executes a function on an interval timer, and assigns a provided id that can be used to cancel it later. Protected from certain browser bugs that may occur with window.setInterval().

Parameters

id—a unique id to assign this timer

function—the function to execute

period—how many milliseconds to wait between executing the function

Returns

Void—begins executing the function after one period is elapsed

• CleverSet.fx.clearInterval(id)

  Clears an interval timer set by CleverSet.fx.setInterval() using the id provided as a parameter to that function.

Parameters

id—the unique id of the timer to clear

Returns

Void—if the function is executing it will complete but will not be called again

Example: Writing a New Renderer

In this example we register a new Renderer called “My_Custom_Renderer.”

/*
 * Register our new Renderer
 */
CleverSet.renderer("My_Custom_Renderer",
                   function (wrapped_slot_element, jQuery$) {

  // Get the non-jQuery wrapped slot_element
  var slot_element = wrapped_slot_element.get(0);

  // Check if there is headerText to display, if so display it
  if (this.headerText) {
    var header = document.createTextNode(this.headerText);
    slot_element.appendChild(header);
  }

  // Iterate through the recommendations calling CleverSet.build_rec() for each one
  // The default Recommendation Builder will return a DIV element
  for (var i = 0; i < this.recs.length; i++) {
    slot_element.appendChild(CleverSet.build_rec(slot_element.id, this.recs[i]));
  }

  // Append a DIV with style="clear:both" in case all of the contents are floated
  var clearing_div = document.createElement("div");
  clearing_div.style.clear = "both";
  slot_element.appendChild(clearing_div);

});