Slideshow presentation (compact content widget)

The compact content widget can be initialised using a slideshow presentation. Visit the compact content widget page for links to a working demonstration and to download the required files.

How to use

There are two basic ways you can use the slideshow presentation.

Both methods require that you include the relevant compact widget scripts and styles first.

  1. Add the class slideshow to the compact container of the basic markup. For example:

    <div class="compact slideshow" id="example-slideshow">
    	...

    If using this approach, the widget will be initialised automatically when the DOM is ready.

  2. Alternatively, you can initialise the widget manually by selecting the container element using a jQuery selector then applying the compact() plugin and specifying the type option as ‘slideshow’.

    This initialisation can occur at any time after the HTML for the widget has been parsed.

    $('.compact').compact(options={
    	type : 'slideshow'
    });

    Other options for this instance can be passed during initialisation to overide the default values.

That’s it, all done!

Further options and configuration variables are detailed below, but the defaults are pretty good, so if you are looking for a quick installation, then read no further.

If you would like to tweak elements of the presentation, read on…

Initialisation options (unique per instance)

The options detailed below can be passed during the manual initialisation. For example:

$('.compact').compact(options={
	type           : 'slideshow',
	panelsLoop     : false,
	variableHeight : true
});
Slideshow compact content initialisation options
option values description
type
  • ‘slideshow’
This option is only required if you haven’t added the slideshow class to the compact container element.
variableHeight
  • true
  • false (default)
If set to true, the height of the widget will animate based on content of the currently visible panel. If set to false, the height of the widget will be set to the height of the tallest section. Note: All content images must have a height and width specified in img tag markup for this to work.
panelsLoop
  • true (default)
  • false
When slideshow or buttons get to the last panel, should it loop back to first panel? (and in reverse)
slideshowAutoStart
  • true (default)
  • false
Should the automatic slideshow start by default?
slideshowInterval
  • integer (default 6000)
Number of milliseconds till next slide is displayed.
controlsPosition
  • ‘before’ (default)
  • ‘after’
Controls (buttons) are inserted before or after content panels.
transitionSpeed
  • ‘slow’ (default)
  • ‘def’
  • ‘fast’
  • integer (ms)
The speed of animated transitions between content panels.
heightAdjustSpeed
  • ‘slow’
  • ‘def’
  • ‘fast’ (default)
  • integer (ms)
The speed of the animated adjustment of the height of the widget. Height adjustments occur when variableHeight is set to true. Adjustments can also occur when variableHeight is set to false, if the resizeEvents plugin is available and the window or text size changes.
cookieExpiryDays
  • integer (default 30)
The number of days the cookie will persist before expiring.
nextControlText
  • string (default ‘>’)
The text visible for the "next" control. To work with image replacement, this should ideally be a short ascii string illustrating the action "next section".
nextControlTitleText
  • string (default ‘Next section’)
The full expansion of the "next section" action.
prevControlText
  • string (default ‘<‘)
The text visible for the "previous" control. To work with image replacement, this should ideally be a short ascii string illustrating the action "previous section".
prevControlTitleText
  • string (default ‘Previous section’)
The full expansion of the "previous section" action.
pauseControlText
  • string (default ‘||’)
The text visible for the "pause" control. To work with image replacement, this should ideally be a short ascii string illustrating the action "pause slideshow".
pauseControlTitleText
  • string (default ‘Pause slideshow’)
The full expansion of the "pause slideshow" action.
playControlText
  • string (default ‘<>’)
The text visible for the "start" control. To work with image replacement, this should ideally be a short ascii string illustrating the action "start slideshow".
playControlTitleText
  • string (default ‘Start slideshow’)
The full expansion of the "start slideshow" action.
supportCSSImgReplace
  • true
  • false (default)

If you would like to replace the ascii control characters with images, set this to true and ensure the clearPixelImg is also set to point to a completely transparent gif or png file.

You should then style the clearPixel image to displace the text, so when images are disabled, the ascii characters become visible.

clearPixelImg
  • string (default ‘displacement.png’)
The relative path from the page containing the widget to a transparent gif or png file.

Global configuration (applies to all instances)

The configuration variables detailed below can be overridden by updating properties of the $.compact.slideshow object before initialising any tabbed widgets. For example:

$.compact.slideshow.contentsClass = 'contents';
$.compact.slideshow.windowClass = 'window';

These variables allow some flexibility in terms of the markup generated when the widget is initialised.

Note: Remember when overriding these variables, some of the default CSS will need to be updated to reflect the changed markup that is generated as a result.

Slideshow compact content global configuration variables
variable default description
containerSelector '.compact.slideshow' jQuery selector that can target the container element (usually by following the DOM upwards from within the widget to the first matching parent element).
activeClass 'active' class applied to container element after widget is initialised (allows independant styling of appearance when script is available and when its not).
cookieRefPrefix 'c.slideshow#' A prefix string that is used to identify cookies for compact content widgets with slideshow presentation.
currentRef 'current-slideshow-panel' Used as reference for $.data() stored on the container element.
contentsClass 'compact-contents' Class to add to a div element that will wrap the content of each slideshow panel.
windowClass 'viewport' Class for the outer wrapper element. Wraps all content sections.
sliderClass 'sliding-tray' Class for the inner wrapper element. Wraps all content sections.
sectionClass 'section' Class to match for each section of content (each section represents a panel of the slideshow).
controlsClass 'controlbar' Class to add to an element that will wrap all the controls/buttons (panel controls and action controls).
panelsClass 'panels' Class to add to an element that will wrap the panel controls/buttons. One control is generated for each section/panel of content.
currentClass 'current' Class to add to the list item wrapping the panel control/button that activates the currently visible section.
actionsClass 'actions' Class to add to an element that will wrap the action controls/buttons. These controls are: "Next section", "Previous section" and the "Start/Pause slideshow" toggle.
previousClass 'previous' Class added to the "Previous section" control/button.
nextClass 'next' Class added to the "Next section" control/button.
toggleClass 'toggle-animation' Class added to the "Start/Pause slideshow" toggle control/button.
animationOnClass 'animation-running' Class added to the container when the slideshow mode is active.
clearPixelClass 'for-css-replacement' Class added to the image element that embeds the transparent image in each control for use with image replacement. (only used if the supportCSSImgReplace option was set to true).

Default generated markup

Below is an example of the before and after markup transition that occurs for each slideshow widget when it is initialised.

Note: If you have customised the configuration variables the generated markup will differ. Also some initialisation options can affect the markup.

Before initialisation:

<div class="compact slideshow" id="example-slideshow">
    <div class="section" id="lorem-ipsum">
        <h2>Lorem ipsum dolor</h2>
        <p>Lorem ipsum dolor sit amet.</p>
    </div>
    <div class="section" id="in-a-orca">
        <h2>In a orci</h2>
        <p>In a orci. Aenean et mi quis dui semper nonummy.</p>
    </div>
    <div class="section" id="maecenas">
        <h2>Maecenas mattis</h2>
        <p>Maecenas mattis. In interdum pede in ipsum.</p>
    </div>
</div>

After initialisation (note ARIA roles, states and properties are embedded):

<div class="compact slideshow animation-running active" id="example-slideshow">
    <div class="controlbar">
        <ul role="wairole:menu" tabindex="0" class="panels controlset">
            <li><a role="wairole:menuitem" id="control-1" tabindex="-1" class="current" 
            	href="#lorem-ipsum" title="Lorem ipsum dolor"><span>1</span></a></li>
            <li><a role="wairole:menuitem" id="control-2" tabindex="-1" 
            	href="#in-a-orca" title="In a orci"><span>2</span></a></li>
            <li><a role="wairole:menuitem" id="control-3" tabindex="-1" 
            	href="#maecenas" title="Maecenas mattis"><span>3</span></a></li>
        </ul>
        <ul role="wairole:toolbar" tabindex="0" class="actions controlset">
            <li><a role="wairole:button" id="control-4" tabindex="-1" href="#" 
            	class="previous" title="Previous section"><span><</span></a></li>
            <li><a role="wairole:button" id="control-5" tabindex="-1" pressed="true" href="#" 
            	class="toggle-animation" title="Pause slideshow"><span>||</span></a></li>
            <li><a role="wairole:button" id="control-6" tabindex="-1" href="#" 
            	class="next" title="Next section"><span>></span></a></li>
        </ul>
    </div>
    <div class="compact-contents">
        <div style="height: 121px; display: block;" class="viewport"><div class="sliding-tray">
            <div style="overflow: hidden;" class="section" id="lorem-ipsum">
                <h2>Lorem ipsum dolor</h2>
                <p>Lorem ipsum dolor sit amet, </p>
            </div>
            <div style="overflow: hidden; display: none;" class="section" id="in-a-orca">
                <h2>In a orci</h2>
                <p>In a orci. Aenean et mi quis dui semper nonummy. </p>
            </div>
            <div style="overflow: hidden; display: none;" class="section" id="maecenas">
                <h2>Maecenas mattis</h2>
                <p>Maecenas mattis. In interdum pede in ipsum. </p>
            </div>
        </div></div>
    </div>
</div>

Image replacement

To enable maximum accessibility, it is good to ensure users who browse with images disabled are still able to do everything that other users are able to do, with similar ease.

If you wish to use CSS image replacement for UI controls, this can be a tricky task as most image replacement techniques fail when a user has CSS enabled, but no support for images. The slideshow widget supports a form of CSS image replacement that is still accessible to users without images.

This technique requires that a small (1x1px) transparent image be used to displace the content of an element, so that a background image can be displayed in its place.

To enable image replacement for the slideshow widget:

  1. Publish a transparent 1x1px gif or png to your server, for example: ‘displacement.png’.

  2. Initialise the widget with the supportCSSImgReplace options set to true and give the path to the transparent image in the clearPixelImg option. For example:

    $('.compact').compact(options={
    	type                 : 'slideshow',
    	supportCSSImgReplace : true,
    	clearPixelImg        : '/assets/images/displacement.png'
    });
  3. Publish UI images to your server to use when replacing the control text.

  4. Use CSS to complete the image replacement:

    .slideshow .actions img.for-css-replacement {
    	height: 2em;
    	width: 2em;
    }
    .slideshow .actions .next span {
    	background: transparent url(/assets/images/slideshow-next.png) left top no-repeat;
    	display: block;
    	width: 2em;
    	height: 2em;
    	overflow: hidden;
    	zoom: 1; /* for IE 6&7 */
    	text-align: center;
    }

When images aren’t supported, the transparent displacement image dissapears also, allowing the original content to be displayed.

Posted in

Leave a reply