Styling the Scroller Renderer

What is the Scroller Renderer?

The ATG Recommendations service uses a configurable renderer to display your Product Recommendations. The Scroller Renderer is an interactive renderer that allows users to “scroll” the recommendations to reveal new ones not visible initially. Just like the other renderers, scroller can be configured using HTML and CSS to fit the look and feel of your website.

Deciding what to render

To use the Scroller Renderer you must specify an extra parameter in the Container <DIV> Element for Recommendations. To do this, add the renderer parameter and set scroller as its value.

The Scroller Renderer is highly configurable with several options that may be changed and a wealth of posibilities for advanced users.

• The -scroller-dir sets the orientation of the recommendations (horizontal, vertical) (default horizontal)
• The -scroller-speed sets the number of milliseconds each scroll motion takes to complete (default 500)
• The -scroller-endFunction is the name of a function that will be called to enable and disable the scroll buttons. See below for details.
• The -scroller-numVisible sets the number of recommendations that are visible (default 3). Note that this parameter does not actually force that number to be visible, it is used for other calculations. To change the number actually visible see the section below on “Styling using CSS.”

• The -inc-price option will include the price in the recommendations. (default off)

  <div id="cs-recslot" class="cs-slot">
    <dl class="cs-cfg" style="display: none">
      <dt>headerText</dt><dd>Your Text</dd>    
      <dt>numRecs</dt><dd>Number of Recommendations</dd>
      <dt>renderer</dt><dd>scroller</dd>

      <dt>-scroller-dir</dt><dd>horizontal</dd>
      <dt>-scroller-speed</dt><dd>500</dd>
      <dt>-scroller-endFunction</dt><dd>csScrollEnd</dd>
      <dt>-scroller-numVisible</dt><dd>4</dd>
      <dt>-inc-price</dt>
    </dl>
  </div>

Styling using CSS

The Scroller Renderer has six classes that should be modified to suit your needs.

• cs-header-text — a <div> tag that contains the header text defined in the Container Element
• cs-rec — <div> tags that contain the individual product recommendations
• cs-title — <span> tags that contain the titles of each product recommendation
• cs-price — <span> tags that contain the prices of each product recommendation
• scroll-container — <div> tag that contains the scroll-group
• scroll-group — <div> tag that contains the recommendations
• scroll-button-DIR — special button <div> tags where DIR can be left, right, up or down. To use different images, simply change the background-image property.

A further good idea is to style the <img> and <a> tags, as well as the container <div>.

  #cs-recslot {padding:5px; font:11px Verdana, Arial, Helvetica, sans-serif; height:200px; width:614px;}
  #cs-recslot .cs-header-text {font: bold 12px Arial, sans-serif; color:#000; text-transform:uppercase;}
  #cs-recslot .cs-rec {float:left; width:139px; text-align:center; display:inline;}
  #cs-recslot img {width:100px; border:0; margin:5px auto;}
  #cs-recslot a {text-decoration:none; color:#000;}
  #cs-recslot .cs-title {text-decoration:underline;}
  #cs-recslot a span {display:block; clear:both;}
  #cs-recslot .cs-price {margin:0; padding:0; text-decoration:none;}

  #cs-recslot .scroll-container {width: 560px; height:100%; overflow:hidden; float:left;}
  #cs-recslot .scroll-group {width: 1128px;}
  #cs-recslot .scroll-button-left {background:url(http://static.cleverset.com/images/left-arrow.gif) no-repeat top; width:22px; height:22px; display:inline; float:left; margin:50px 3px 0 0;}
  #cs-recslot .scroll-button-right {background:url(http://static.cleverset.com/images/right-arrow.gif) no-repeat top; width:22px; height:22px; display:inline; float:left; margin:50px 0 0 3px;}

To adjust the number of recommendations showing you will want to adjust the size of the .scroll-container class, as well as the recommendation slot itself.

Advanced Functionality

The Scroller renderer is highly customizable and allows significant use of custom augmentation. The two most important ways to augment the renderer are through custom buttons and end-functions.

Custom Buttons

Disabling the default buttons is as easy as setting display:none; in their CSS. Any element can be used as a button to scroll the Scroller renderer, it need only make a JavaScript call.

To scroll the renderer, call the CleverSet.fx.scroll(slot_id, direction, millis, number, function) function with up to five parameters. The five parameters are:

slot_id (required)

The id of the recommendation slot. In the examples above this would be the string ’#cs-recslot’.

direction (required)

The direction to scroll. This could be ‘left’, ‘right’, ‘up’ or ‘down’.

millis (required)

The time the scroll should take. This is a number in milliseconds.

number (required)

The number of recommendations showing. This is used for calculations and is important.

function (optional)

A reference to an End Function. This parameter is optional and is discussed further below.

For example:

  <a href="javascript: void(0);" onclick="CleverSet.fx.scroll('#cs-recslot', 'left', 500, 4);">&lt;</a>
  <a href="javascript: void(0);" onclick="CleverSet.fx.scroll('#cs-recslot', 'right', 500, 4);">&gt;</a>

Note that the scroll function will not function if the Renderer believes there are no more recommendations to display in that direction.

End Functions

A function may be defined that will be called each time the Scroller is scrolled. This function is intended to be used to change the appearance of scroll buttons and is passed parameters that concern the enabling and disabling of those buttons. This function is either defined in the recommendation slot as the parameter <dt>-scroller-endFunction</dt> or in a custom scroll function call as the fifth parameter.

This function is passed four parameters when it is called.

element

A reference to the default button dom element in question.

dir

The direction the button is pointing (left, right, up, down).

enable

Whether the button should be enabled (true) or disabled (false).

init

Whether the function call is from the renderer initialization (true) or from later interaction (false).

None of the parameters have to be used, they are simply there to provide information which could be useful to the developer. A sample function is given below. This function assumes that the default buttons are being used and that background images are being set for them. It will hide the button when it is disabled and show it when it is enabled. It utilizes the copy of jQuery that comes with the ATG Recommendations API.

  csScrollEnd = function (element, dir, enable, init) {
    var el = jQuery(element);
    if (el.size()) {
      if (enable) {
        if (el.css('backgroundImage') == "none")
          el.css('backgroundImage', element.button);
      }
      else {
        element.button = el.css('backgroundImage');
        el.css('backgroundImage', "none");
      }
    }
  };