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.
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.
The final step is to invoke the cycle class on your <div>. Including your <div> it might look like this:
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.
ca.cycle has two display modes:
- 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.
- 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.
caUI.cycle defines three methods:
- 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.
- 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.
- addImage() : same as addImages()
- removeImages() : clears all images from the cycle.
The mandatory options for caUI.cycle are listed below. These are options that must be present no matter the display transition and mode:
|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.
|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|