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


This is what the slideshow will look like after you have implemented it:


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.


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:


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


cycleIntervalThe time between slide transitions in milliseconds.
cycleSpeedThe speed of the transition effect in milliseconds.
wrapThis 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.

delayThe number of milliseconds to add onto, or subtract from, the time before the first slide transition occurs.
loopThe 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.


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