Spry UI Content Slideshow

The Spry UI Content Slideshow is a widget that takes an set of repeating markup and transforms it into a slideshow, with options like automatic scrolling and navigation buttons.

It is designed to accept a wide variety of repeating markup and convert it into a functional, skinnable slideshow.

Setting up to use the Content Slideshow

Panel Markup

By default, the Content Slideshow is set up to look for a repeating markup structure.

For instance, in a structure such as:

<div class="product">     
 <h3>Local News</h3>    
 <img src="image.jpg" alt="Local News" class="placeholderImage" />      
 <p> Minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip.</p>    
</div> 
<div class="product">     
 <h3>National News</h3>    
 <img src="national.jpg" alt="National News" class="placeholderImage" />      
 <p> Minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip.</p>    
</div>

the repeating markup is clear. The widget will assume that every time it hits a new <div class="product"> it will be a new panel.

In the Spry UI world, there is a lot of talk about 'panels'. One of these repeating blocks is a 'panel'.

Once, the markup is specified, the widget should work as designed.

By default, there is no chrome on the widget. It is simply runs through the panels. Now it is just a matter of setting properties and styling the widget.

Properties

The Content Slideshow has a few properties you can set to control the basic functionality of the widget. By default, they are:

Autoplay: true. The slideshow will play as soon as the page is loaded. Set to false to change it.
displayInterval: 4000. In milliseconds, the images will show for 4 seconds before changing.
transitionInterval: 2000. In milliseconds, the time the transition will run as it switches between images.
injectionType: "replace". This means that the widget removes the existing markup and injects it's own. Other option is "inside", which injects the widget markup inside the widget container.
defaultSlide: Controls the index of the first slide to show. 0-based, so the third image would be '2'.
componentOrder: Controls the order in which the injected markup is added to the page. This helps with styling, as you can control, for example, whether the control buttons are placed at the top or bottom of the markup.

All of the properties in this constructor are overwriting the defaults found in the 'defaultConfig' object within SpryContentSlideShow.js. Any properties can be changed by overwriting the default within the constructor.

For instance:

var ImageSlideShow = new Spry.Widget.ContentSlideShow("#ImageSlideShow", {
	widgetID: "ImageSlideShow",
	injectionType: "replace",
	autoPlay: true,
	displayInterval: 4000,
	transitionDuration: 2000,
	componentOrder: ["view", "controls"],
	plugIns: [ Spry.Widget.ContentSlideShow.PanAndZoomPlugin ]
});

Slicing

Spry UI components are highly skinnable. This is achieved by injecting markup with levels of slicing controlled by the developer.

Slicing is a technique for styling page elements. It takes a page element and dynamically injects a set of <div>s around it to provides hooks for CSS styles.

These <div>s have established class names applied to them. Using these classes, developers can make scalable elements, add rounded corners or apply other styles.

There are a few levels of slicing: 2, 3-slicing and 9 slicing. The image above shows a 9-sliced element. Start with one and 8 are added. Note that the top and bottom-mid and -left are within the right div. This layout simplifies alignment and stretching.

3-slicing will only add 2 <div>s. In the above, it would be just the middle row.

2-slicing will wrap the content in 2 divs.

Slicemap

Slicing is done via the SliceMap. The SliceMap is a javascript constuctor that lists the elements to be sliced. By default, nothing is sliced. And note that not every element is sliceable...

If you look at the core widget javascript file, in this case SpryImageSlideshow.js, you will see the constuctor options object. Within it, you will see a list of class names:

 widgetClass: "ImageSlideShow",          // Sliceable
 playingClass: "CSSPlaying",
 nameClass: "CSSName",                   // Sliceable
 clipClass: "CSSClip",
 viewClass: "CSSView",
 slideClass: "CSSSlide",                 // Sliceable

This specifies which class handles which portion of the widget style. These can be customized as you wish by editing the default js file or overwrite this object with a custom object.

Below this list of classes is:

 sliceMap: {},

Empty by default, this object takes a list of class names and the slice type.

sliceMap:{classname: slicetype}

for example:

sliceMap:{ContentSlideShow: "9slice", CSSName:"3slice"}

This means that any element that has the class="ContentSlideShow" will get 9-sliced. Same for class="CSSName" with 3-slice.

Slicing options available:

"2slice" - Wraps the content element with 2 <div>s inside the top-level widget container.
"3slice" - Wraps the content element with 3 <div>s inside the top-level widget container.
"9slice" - Injects the content element with 9 <div>s inside the top-level widget container.

These <div>s are dynamically generated and only show up when you view the generated (DOM) source.

Methods

The Content Slideshow has the usual methods for controlling the slideshow.

Syntax is:

onclick="widgetname.method()"

where widgetname is the var name used in the constructor.

play()
stop()
togglePlayMode()
showFirstSlide()
showLastSlide()
showNextSlide()
showPreviousSlide()

Includes/Plugins

Spry UI departs from Spry 1.x in how dependent files are handled. While Spry 1.x had everything in one JS and one CSS file, for ease of use, Spry UI uses a more modular system.

Spry UI functionality is broken up into components, where a single javascript file will handle one piece of functionality.

So while the Spry widget is an entity on it's own, it can be thought of as a grouping of differing functionalities into a functioning widget.

This provides a couple advantages:

Function duplication - When using many Spry widgets on a single page, all the widgets can share the common core files. This ensures that functions aren't duplicated unneccessarily.
Build your own- Users can create their own widgets by hooking up these components in unique ways.

We also are now using a plugin model for customizing almost all pieces of the widget. A plugin is a piece of javascript that overwrites or extends existing functionality.

For instance, if you want to use a custom transition function, this can be written as a plugin and included in the constructor (using the 'plugins' array in the defaultConfig object).

Almost any functionality of the widget/component can be overwritten with a plugin. The fading or pan/zoom between panels are examples of plugins.

The includes used for the basic Content Slideshow.

SpryDomUtils.js - The selector model. This file does the selection and DOM traversing.
SpryDOMEffects.js - Handles DOM manipulation.
SpryWidget.js - The Spry UI base class. Handles core common functionality.
SpryPanelSelector.js - Finds the repeating markup converts it to panels the widget can consume.
SpryPanelSet.js - Handles the panels as a group.
SpryFadingPanels.js - Handles transitions between panels. If not used, panels instantly change. Extendable through plugins.
SpryContentSlideShow.js - The core widget file. Handles the binding of the components into a complete widget.

Spry.Widget.ContentSlideShow.slideTransitionPlugin

Replaces the default fading transition of the content slide show with a sliding transition.

Options

The plugin extracts the following options from the ContentSlideShow widget constructor options:

displayInterval – The amount of time in milliseconds each slide is displayed in play mode.
slideVisibleClass – The class name to place on the slide that is currently visible.
slideHiddenClass – The class name to place on all slides that are not currently visible.

Examples:

  var css = new Spry.Widget.ContentSlideShow(“#myContent”, { plugIns: [Spry.Widget.ContentSlideShow.slideTransitionPlugin ], displayInterval: 8000  });

Required Includes:

<script type="text/javascript"  src="../includes/SpryDOMUtils.js"></script>
<script type="text/javascript"  src="../includes/SpryDOMEffects.js"></script>
<script type="text/javascript"  src="../includes/SpryWidget.js"></script>
<script type="text/javascript"  src="../includes/SpryPanelSelector.js"></script>
<script type="text/javascript"  src="../includes/SpryPanelSet.js"></script>
<script type="text/javascript" src="../includes/SprySliderPanels.js"></script>
<script type="text/javascript"  src="../includes/SpryContentSlideShow.js"></script>

The plugin does not require an additional include since it is implemented within SpryContentSlideShow.js.