Difference between revisions of "API:Javascript:ca/ca.cycle.js"

From CollectiveAccess Documentation
Jump to: navigation, search
(Created page with "== About == ''ca.cycle.js'' is a caUI class that implements "cycling" (animated slideshows) between sets of images. It supports a variety transitions ...")
 
Line 89: Line 89:
 
|}
 
|}
  
[[Category:Setup_and_Configuration]]
+
[[Category:Specialized_Setup_and_Configuration]]

Revision as of 19:46, 1 November 2012

About

ca.cycle.js is a caUI class that implements "cycling" (animated slideshows) between sets of images. It supports a variety transitions and two display modes, described below in Options.

The class can be loaded for use in a request by registering cycle with the JavascriptLoadManager.

Use

To create an image animation using the ca.cycle class, first create a containing <div>. If you are using "conveyor" mode, described below, be sure that the <div> has its width and height set appropriately, and that CSS overflow is set to "hidden." You may add default content to the <div> if desired. It will be overwritten by the animation once ca.cycle is invoked.

Next create a Javascript array of <img> tags for the images you wish to use in the animation. You can also display images that link to pages by wrapping your <img> tags in <a> tags.

The final step is to invoke the cycle class on your <div>. Including your <div> it might look like this:

<div id="mySlideshow">Slideshow requires Javascript!</div>

<script type="text/javascript">
	var mySlideshowCycle = caUI.initCycle('#mySlideshow', { 
                     fx: 'fade', 
                     imageList: [
                             '<img src="images/dress_1.jpg" width="120" height="120"/>',
                              '<img src="images/dress_2.jpg" width="120" height="120"/>',
                              '<img src="images/dress_3.jpg" width="120" height="120"/>',
                              '<img src="images/dress_4.jpg" width="120" height="120"/>',
                              '<img src="images/dress_5.jpg" width="120" height="120"/>'
                     ],
                     timeout:3000 // 3 seconds between fades
         });
</script>

The above code would create a five image slideshow with a crossfade effect between slides. There would be a 3 second interval between frames.

The caUI.initCycle() function initializes the cycle and sets the images into the <div> specified by the first parameter using a standard jQuery selector. The second parameter is a collection of options. The fx and imageList options are always required and define the display effect and list of images to display respectively. The range of additional options is dependent upon the display effect set in fx. caUI.initCycle() returns an instance that can be used to control and modify the slideshow.

Display modes

ca.cycle has two display modes:

  1. Slideshow mode displays a single image at a time with optional transitions between images. In this mode ca.cycle simply wraps the jQuery jCycle plugin and supports all of the options that plugin provides.
  2. Conveyor mode lines up images horizontally and pans across them. The effect is much like a conveyor belt of images. This mode has its own set of options, distinct from those defined for slideshow mode by jCycle.

The display mode is determined by the fx option. If set to conveyorLeft or conveyorRight conveyor mode is used. Any other valid jCycle effect name will set slideshow mode.

Methods

caUI.cycle defines three methods:

  1. caUI.initCycle(container, options) : initializes and begins a slideshow/cycle. The container parameter is a standard jQuery selector for the <div> that will contain the slideshow. Options takes keys and values for rendering options. Mandatory options are fx and imageList; all others are dependent upon the values of fx.
  2. addImages(imageList) : adds images to the cycle. You can pass an array of <img> tags or a single tag as a string. Images will be displayed in the order they were added.
  3. addImage() : same as addImages()
  4. removeImages() : clears all images from the cycle.

Options

The mandatory options for caUI.cycle are listed below. These are options that must be present no matter the display transition and mode:

Option Description Mandatory
fx The name of the display effect. Yes
imageList A list of image tags to display in the cycle. It must define at least two images for successful use. Yes

If fx is equal to conveyorLeft or conveyorRight then "conveyor belt" mode is used. If fx is set to one of the standard jCycle transition effects then jCycle will be used for the slideshow and all jCycle options are supported.

In conveyor belt mode the following options are supported. These are distinct from the jCycle options.

Option Description Mandatory Default
duration How long the conveyor built will take to run though all images. Specify this value in milliseconds (1/1000ths of a second) No 2000
rewind If true conveyor will graphically "rewind" when it reaches the end of a scroll. No true
rewindDuration How long the conveyor built will take to rewind after display. Specify this value in milliseconds (1/1000ths of a second). No 1000
repetitions Maximum number of times to run through the conveyor built before stopping. No 0
margin The number of pixels to put between images in the conveyor belt. Set to zero to have the images line up size to side. No 0
easing Type of easing - "linear" or "swing" – to use in conveyor presentation. No Linear
Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools