Adding a Slideshow

This recipe shows how to configure and use the integrated Slideshow macro in Viewport.

Requirements

In order to get the slideshow to work, you need to include cycle2 and jquery in your scripts. (For more information regarding embedding jQuery and other files into your theme, see Referencing JS/CSS and Image Files.)

If you're using the Scroll WebHelp Theme, the slideshow is already configured and will start automatically.

Adding a Slideshow

With Viewport installed, two macros called Viewport Slideshow and Viewport Slide for Slideshow are added to Confluence.

Use the Slideshow macro as the container, and the Slide macro for the individual slides. You can include any content, not only images.

Options

The slideshow can be configured by passing an options hash to the cycle method, or by using the data-cycle attributes. The example below sets some attributes and initializes the slideshow by calling the cycle() function:

custom.js

CODE

$('.sp-slideshow').each(function (index) {
    $(this).attr("data-cycle-pause-on-hover", "true")
           .attr("data-cycle-swipe", "true")
           .cycle();
});

Parameters

Property	Description
cycleInterval	The time between slide transitions in milliseconds.
cycleSpeed	The speed of the transition effect in milliseconds.
wrap	This option determines whether or not a slideshow can advance from the last slide to the first (or vice versa). If set to `false` then once a slideshow reaches its last slide it can no longer be advanced forward, it can only advance backward. Likewise, when a slideshow is displaying the first slide it can not advance backward. By default, a slideshow will advance seamlessly from the last slide to the first.
delay	The number of milliseconds to add onto, or subtract from, the time before the first slide transition occurs.
loop	The number of times an auto-advancing slideshow should loop before terminating. If the value is less than 1 then the slideshow will loop continuously.

You can find more information about the API on the official API Docs Page.

Adding a Slideshow Pager

The code below shows you how to create a pager for each slideshow in the page. The appearance of the pager can be modified through CSS.

custom.js

CODE

$('.sp-slideshow').each(function (index) {
        var pagerName = "pager-" + index;
        var pager = $('<div></div>');
        $(pager).addClass(pagerName + " sp-pager");
        $(this).after($(pager));
        $(this).attr("data-cycle-pager", "." + pagerName);      
    });