%META:TOPICINFO{author="ProjectContributor" date="1315479654" format="1.1" version="1"}%
%META:TOPICPARENT{name="JQueryPlugin"}%
---+ %TOPIC%
%JQPLUGINS{"cycle"
  format="
    Homepage: $homepage <br />
    Author(s): $author <br />
    Version: $version
  "
}%

%STARTSECTION{"summary"}%
The jQuery Cycle Plugin is a lightweight slideshow plugin. Its implementation
is based on the JQueryInnerFade Plugin by Torsten Baldes, the Slideshow Plugin by
Matt Oakes, and the jqShuffle Plugin by Benjamin Sterling. It supports
pause-on-hover, auto-stop, auto-fit, before/after callbacks, click triggers and
many transition effects. It also supports, but does not require, the Metadata
Plugin and the Easing Plugin.
%ENDSECTION{"summary"}%

---++ Usage

Add the ==jqCycle== class to the container holding the elements to be cycled. 

---++ Commands
The cycle function can be passed a command string in the form:

<verbatim class="js">
$('#slideshow').cycle('command');
</verbatim>

The following command strings are supported:

<verbatim class="js">
'pause'   // pauses the slideshow, slideshow can be resumed with 'resume' command 
'resume'  // resumes a paused slideshow 
'toggle'  // toggles the pause/resume state of the slideshow 
'next'    // advances slideshow to next slide 
'prev'    // advances slideshow to previous slide 
'stop'    // stops the slideshow 
'destroy' // stops the slideshow and unbinds all events 
</verbatim>

---++ Options
The following default options are provided by the plugin. They can be overridden by passing an options object to the cycle method, by using metadata on the container element, or by redefining these values in your own code. Lots of cool effects can be achieved by taking advantage of these options, but none of them are required. So override the ones you like and ignore the ones you don't care about.

<verbatim class="js">
// override these globally if you like (they are all optional) 
$.fn.cycle.defaults = { 
        activePagerClass: 'activeSlide', // class name used for the active pager link
        after:             null,  // transition callback (scope set to element that was shown):  function(currSlideElement, nextSlideElement, options, forwardFlag)
        allowPagerClickBubble: false, // allows or prevents click event on pager anchors from bubbling
        animIn:            null,  // properties that define how the slide animates in
        animOut:           null,  // properties that define how the slide animates out
        aspect:            false,  // preserve aspect ratio during fit resizing, cropping if necessary (must be used with fit option)
        autostop:          0,     // true to end slideshow after X transitions (where X == slide count)
        autostopCount:     0,         // number of transitions (optionally used with autostop to define X)
        backwards:         false, // true to start slideshow at last slide and move backwards through the stack
        before:            null,  // transition callback (scope set to element to be shown):     function(currSlideElement, nextSlideElement, options, forwardFlag)
        center:            null,  // set to true to have cycle add top/left margin to each slide (use with width and height options)
        cleartype:         !$.support.opacity,  // true if clearType corrections should be applied (for IE)
        cleartypeNoBg: false, // set to true to disable extra cleartype fixing (leave false to force background color setting on slides)
        containerResize:   1,       // resize container to fit largest slide
        continuous:        0,     // true to start next transition immediately after current one completes
        cssAfter:          null,  // properties that defined the state of the slide after transitioning out
        cssBefore:         null,  // properties that define the initial state of the slide before transitioning in
        delay:             0,     // additional delay (in ms) for first transition (hint: can be negative)
        easeIn:            null,  // easing for "in" transition
        easeOut:           null,  // easing for "out" transition
        easing:            null,  // easing method for both in and out transitions
        end:               null,  // callback invoked when the slideshow terminates (use with autostop or nowrap options): function(options)
        fastOnEvent:       0,         // force fast transitions when triggered manually (via pager or prev/next); value == time in ms
        fit:               0,     // force slides to fit container
        fx:                'fade', // name of transition effect (or comma separated names, ex: 'fade,scrollUp,shuffle')
        fxFn:              null,  // function used to control the transition: function(currSlideElement, nextSlideElement, options, afterCalback, forwardFlag)
        height:            'auto', // container height (if the 'fit' option is true, the slides will be set to this height as well)
        manualTrump:       true,  // causes manual transition to stop an active transition instead of being ignored
        metaAttr:          'cycle',// data- attribute that holds the option data for the slideshow
        next:              null,  // element, jQuery object, or jQuery selector string for the element to use as event trigger for next slide
        nowrap:            0,     // true to prevent slideshow from wrapping
        onPagerEvent:      null,  // callback fn for pager events: function(zeroBasedSlideIndex, slideElement)
        onPrevNextEvent:   null,// callback fn for prev/next events: function(isNext, zeroBasedSlideIndex, slideElement)
        pager:             null,  // element, jQuery object, or jQuery selector string for the element to use as pager container
        pagerAnchorBuilder: null, // callback fn for building anchor links:  function(index, DOMelement)
        pagerEvent:        'click.cycle', // name of event which drives the pager navigation
        pause:             0,     // true to enable "pause on hover"
        pauseOnPagerHover: 0, // true to pause when hovering over pager link
        prev:              null,  // element, jQuery object, or jQuery selector string for the element to use as event trigger for previous slide
        prevNextEvent:     'click.cycle',// event which drives the manual transition to the previous or next slide
        random:            0,     // true for random, false for sequence (not applicable to shuffle fx)
        randomizeEffects:  1,  // valid when multiple effects are used; true to make the effect sequence random
        requeueOnImageNotLoaded: true, // requeue the slideshow if any image slides are not yet loaded
        requeueTimeout:    250,  // ms delay for requeue
        rev:               0,     // causes animations to transition in reverse (for effects that support it such as scrollHorz/scrollVert/shuffle)
        shuffle:           null,  // coords for shuffle animation, ex: { top:15, left: 200 }
        skipInitializationCallbacks: false, // set to true to disable the first before/after callback that occurs prior to any transition
        slideExpr:         null,  // expression for selecting slides (if something other than all children is required)
        slideResize:       1,     // force slide width/height to fixed size before every transition
        speed:             1000,  // speed of the transition (any valid fx speed value)
        speedIn:           null,  // speed of the 'in' transition
        speedOut:          null,  // speed of the 'out' transition
        startingSlide:     0,         // zero-based index of the first slide to be displayed
        sync:              1,     // true if in/out transitions should occur simultaneously
        timeout:           4000,  // milliseconds between slide transitions (0 to disable auto advance)
        timeoutFn:         null,  // callback for determining per-slide timeout value:  function(currSlideElement, nextSlideElement, options, forwardFlag)
        updateActivePagerLink: null, // callback fn invoked to update the active pager link (adds/removes activePagerClass style)
        width:             null   // container width (if the 'fit' option is true, the slides will be set to this width as well)
};
</verbatim>

---++ Transition effects

Use these in the =fx= option.

   * blindX
   * blindY
   * blindZ
   * cover
   * curtainX
   * curtainY
   * fade
   * fadeZoom
   * growX
   * growY
   * none
   * scrollUp
   * scrollDown
   * scrollLeft
   * scrollRight
   * scrollHorz
   * scrollVert
   * shuffle
   * slideX
   * slideY
   * toss
   * turnUp
   * turnDown
   * turnLeft
   * turnRight
   * uncover
   * wipe
   * zoom

---++ Examples
%JQREQUIRE{"cycle"}%

<div class="pics jqCycle {fx:'scrollLeft', timeout:5000}">
<div>
  <img src="%ATTACHURLPATH%/beach1.jpg" />

  St Andrews State Park
</div>
<div>
  <img src="%ATTACHURLPATH%/beach2.jpg" />

  Located in the Florida panhandle
</div>
<div>
  <img src="%ATTACHURLPATH%/beach3.jpg" />

  Endless fun.
</div>
</div>

<style type="text/css">
.pics  {  
 width:232px;
 height:272px;
 padding:0;  
 margin:0;
 text-align:center;
}
.pics img {  
 padding: 15px;  
 border:  1px solid #ccc;  
 background-color: #eee;  
 width:  200px; 
 height: 200px; 
 top:  0; 
 left: 0 
} 
</style>
</literal>

%META:FILEATTACHMENT{name="beach1.jpg" attachment="beach1.jpg" attr="" comment="" date="1258379674" path="beach1.jpg" size="20327" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="beach2.jpg" attachment="beach2.jpg" attr="" comment="" date="1258379694" path="beach2.jpg" size="21480" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="beach3.jpg" attachment="beach3.jpg" attr="" comment="" date="1258379707" path="beach3.jpg" size="22629" user="ProjectContributor" version="1"}%
