Rotators Overview

by Justin Stayton | Last edited: 2/12/2013

The Rotators API provides a flexible interface for implementing image and video rotators. While this added flexibility allows for many different markup configurations, there is a small cost paid in complexity. Let's take a look.

Structure of show tags

A number of different show tags exist for flexibility in your desired markup. In order of their output:

  1. before_show
  2.    before_slide_show
  3.       slide_show
  4.       image_slide_show
  5.       video_slide_show
  6.    after_slide_show
  7.    before_slide_show_#
  8.       slide_show_#
  9.       image_slide_show_#
  10.       video_slide_show_#
  11.    after_slide_show_#
  12. after_show

The indentation illustrates the grouping of show tags and how the resulting markup can be structured. before_slide_show, slide_show, image_slide_show, video_slide_show, and after_slide_show can all be repeated any number of times (before_slide_show_2, slide_show_3, after_slide_show_4, etc.). The dynamic nature of these show tags allows for more complex markup in a single API call. Use however many are necessary to build your desired markup.

image_slide_show and video_slide_show provide the same tags as slide_show, but allow for customized output depending on whether the slide is an image or video.

Let's walk through a few examples to see how this works in practice.

JavaScript library

An important part omitted from the following examples is a JavaScript library used to do the rotating. Just to be sure it's completely apparent, a library such as jQuery Cycle must be used in addition to the getContent calls below. Feel free to use any library that fits your needs.

Example with basic image support

getContent(
  'rotator',
  'display:slides',
  'find:homepage-highlights',
  'before_show:<div id="rotator">',
  'before_show:<ol data-transition="__transitionms__">',
  'slide_show:<li>',
  'slide_show:<img src="__imageurl width='560' height='315'__">',
  'slide_show:<em>__title__</em>',
  'slide_show:</li>',
  'after_show:</ol>',
  'after_show:</div>'
);

For basic rotators, the different show tags are very straightforward. In this example, each slide is output as a list item, with the entire list wrapped in a <div> tag. The assumed constraint is that all slides are images.

Example using find with dynamic page identifier

getContent(
  'rotator',
  'display:slides',
  'find:' . $_GET['nav'],
  'before_show:<div id="rotator">',
  'before_show:<ol data-transition="__transitionms__">',
  'slide_show:<li>',
  'slide_show:<img src="__imageurl width='560' height='315'__">',
  'slide_show:<em>__title__</em>',
  'slide_show:</li>',
  'after_show:</ol>',
  'after_show:</div>'
);

While the previous example used a hard-coded slug to find the rotator, this one uses $_GET['nav'] to dynamically find the rotator assigned to the current page. This works great for supporting different rotators in a single page template.

Example with basic image and video support

getContent(
  'rotator',
  'display:slides',
  'find:homepage-highlights',
  'before_show:<div id="rotator">',
  'before_show:<ol data-transition="__transitionms__">',
  'image_slide_show:<li class="image">',
  'image_slide_show:<img src="__imageurl width='560' height='315'__">',
  'image_slide_show:<em>__title__</em>',
  'image_slide_show:</li>',
  'video_slide_show:<li class="video">',
  'video_slide_show:__videoembed width='560' height='315'__',
  'video_slide_show:<em>__title__</em>',
  'video_slide_show:</li>',
  'after_show:</ol>',
  'after_show:</div>'
);

Building on the first example, this rotator handles both images and embedded videos (YouTube/Vimeo). Notice the use of image_slide_show and video_slide_show. These show tags can be used instead of slide_show to output different markup depending on the type.

Example with separated content (using dynamic show tags)

getContent(
  'rotator',
  'display:slides',
  'find:homepage-highlights',
  'before_show:<div id="rotator">',
  'before_slide_show:<ol data-transition="__transitionms__">',
  'image_slide_show:<li class="image">',
  'image_slide_show:<img src="__imageurl width='560' height='315'__">',
  'image_slide_show:</li>',
  'video_slide_show:<li class="video">',
  'video_slide_show:__videoembed width='560' height='315'__',
  'video_slide_show:</li>',
  'after_slide_show:</ol>',
  'before_slide_show_2:<ol>',
  'slide_show_2:<li>',
  'slide_show_2:<em>__title__</em>',
  'slide_show_2:<p>__caption__</p>',
  'slide_show_2:</li>',
  'after_slide_show_2:</ol>',
  'after_show:</div>'
);

More complex rotators sometimes separate the image or video from the content of the slide (like title and caption). In this case, two separate lists are built using before_slide_show / after_slide_show and their dynamic counterparts before_slide_show_2 / after_slide_show_2. slide_show_2 is then used to output the slide content.

Example with YouTube/Vimeo API scripts

getContent(
  'rotator',
  'display:slides',
  'find:homepage-highlights',
  'before_show:<div id="rotator">',
  'before_show:<ol data-transition="__transitionms__">',
  'video_slide_show:<li>',
  'video_slide_show:__videoembed width='560' height='315'__',
  'video_slide_show:</li>',
  'after_show:</ol>',
  'after_show:__ifvideoyoutube__<script src="//www.youtube.com/iframe_api" />',
  'after_show:__ifvideovimeo__<script src="//a.vimeocdn.com/js/froogaloop2.min.js" />',
  'after_show:</div>'
);

While greatly abbreviated, this example demonstrates how to load the YouTube and Vimeo JavaScript APIs (once) if there's an embedded video in the rotator. You can then programmatically interact with the video players to, for example, pause a video if the slide is transitioned away. In the same vein, __ifvideohosted__ can be used to load a custom video player of your choosing for videos hosted by the CMS.