The Cycle2 plugin has a rich set of functions which it invokes in order to initialize and run a slideshow. This API is fully customizable so that you can both replace existing implementation bits and also create new transition effects.

Methods

All API methods can be replaced with custom implementations by binding to the cycle-bootstrap event and replacing the appropriate property on the API object. Example:

$( '#mySlideshow' ).on( 'cycle-bootstrap', function( e, optionHash, API ) {
    // replace "advanceSlide" method with custom impl
    API.advanceSlide = function( numberOfPositions ) {
        // custom implementation
    }
});

It is also possible to retrieve the API object at any time by using the data method on the slideshow container.

var API = $( '#mySlideshow' ).data( 'cycle.API' );
NameDescription / Signature
addThis method adds slides to the slideshow. It is invoked during initialization of the slideshow and whenever the add command is issued to an already running slideshow.
function( slides )
slides can be a string, an array, or a jQuery object
addInitialSlidesThis method handles finding and adding the initial slideset.
function()
advanceSlideSets the nextSlide property of the optionHash and stages the next transition.
function( numberOfPositions )
numberOfPositions can be negative to move backward in the slidehow, or positive to move forward.
buildPagerLinkCreates a pager link for each slide and binds the pagerEvent to the slide.
function( slideOptionHash, slide )
buildSlideOptsBuilds an option hash for an individual slide inheriting from the slideshow options for properties not defined on the slide.
function( slide )
calcFirstSlideSets properties for the initial slideshow state, including the first slide to be displayed as well as the nextSlide.
function()
calcNextSlideSets properties for currSlide and nextSlide after a transition is started.
function()
calcTxdetermines the name of the transition based on the fx and manualFx properties and the value of the manual flag.
function( slideOptions, manual )
destroyReverts a slideshow to its original state by removing elements and event bindings added by Cycle2. This method is invoked when the destroy command is issued programmatically to the slideshow.
function()
doTransitionBegins a transition from one slide to another
function( slideOptions, currEl, nextEl, fwdFlag, callback )
  • currEl: the slide element that is currently showing
  • nextEl: the slide element that is to be displayed next
  • fwdFlag: flag indicating it the transition should move forward or backward
  • callback: function to invoke after the transition completes
getComponentReturns the component(s) for the requested name. This is used internally to find the pager, caption, and overlay elements.
function( nameOfComponent )
getSlideIndexReturns the zero-based slide index of the element passed.
function( slideElement )
getSlideOptsReturns the optionHash for a specific slide.
function( slideIndex )
gotoAdvances the slideshow to a specific slide index (zero-based).
function( index )
This function is invoked whent the goto command is issued to the slideshow.
initSlideInvoked as each slide is added to the slideshow to set initial styles.
function( slideOptions, slide, suggestedZindex )
initSlideshowHandled one-time initialization logic for the slideshow.
function()
logLogs a slideshow message. Used internally to log important information to the javascript console.
function( arg1, arg2, arg3, ... )
Arguments are concatenated into a space-delimited string.
nextAdvances the slideshow to the next slide.
function()
Invoked by next controls and when the next command is issued programmatically.
pageAdvances the slideshow to a specific index based on the target element of the pagerEvent.
function( pagerEl, targetEl )
pausePauses a slideshow.
function()
Invoked when the pause command is issued to the slideshow.
postInitSlideshowInvoked after the main initialization logic has been run.
function()
preInitSlideshowInvoked before main initialization logic runs but after initial slides have been added to the slideshow.
function()
prepareTxPrepares the next transition.
function( manualFlag, fwdFlag )
prevAdvances the slideshow to the previous slide. Invoked by prev controls and when the prev command is issued programmatically.
function()
queueTransitionStages the next transition preparation.
function( slideOptions )
reinitReinitializes the slideshow.
function()
This function is invoked when the reinit command is issued to the slideshow.
removeRemoves a slide from the slideshow.
function( slideIndexToRemove )
resumeResumes a paused slideshow.
function()
This function is invoked when the resume command is issued to the slideshow.
stackSlidesRezindexes the slide deck in preparation for the next transition.
function( currEl, nextEl, fwdFlag )
stopTerminates a running slideshow.
function()
This function is invoked when the stop command is issued to the slideshow.
stopTransitionStops any transitions currently in progress.
function()
tmplPerforms token replacement on a template string.
function( templateString, optionHash, slideEl )
triggerTriggers an event on the slideshow container.
function( eventName, args )
updateViewUpdates visible data for the slideshow. Sets the active class on the appropriate slide element and triggers the cycle-update-view event.
function()

Transitions API

Custom transitions are created by extending Cycle2's transitions object with an object that implements some or all of the transition API. For example:

$.fn.cycle.transitions.myNewTransition = {
    before: function( opts, curr, next, fwd ) {
        // assign properties to the opts object
    }
}

A transition's before function is invoked prior to starting a transition from one slide to the next. Typically defining the before function is adequate for defining a new transition effect, however you may also define any of the other functions described below.

Once a new transition is defined, it can be used by assigning it's name to Cycle2's fx option.

$('.cycle-slideshow').cycle({
    fx: 'myNewTransition'
});

The following table describes Cycle2's transition API:

NameDescription/Signature
afterInvoked after the transion has completed.
function( slideOptions, currEl, nextEl, fwdFlag )
beforeInvoked immediately before a transition is started.
function( slideOptions, currEl, nextEl, fwdFlag )
postInitInvoked once immeidately after the slideshow is initialized
function( optionHash )
preInitInvoked once immediately before the slideshow is initialized
function( optionHash )
stopTransitionInvoked when a transition should be stopped immediately.
function( optionHash )
transitionInvoked in order to perform the transition. This allows Cycle2's core transition logic to be completely overridden.
function( slideOptions, currEl, nextEl, fwdFlag, callback )
The callback function MUST be invoked by the transition function.

Useful properties to set on the optionHash in the before method:

NameTypeDescription
animInobject hash An object which defines css properties that should be applied to the slide as it is being animated in.
animOutobject hash An object which defines css properties that should be applied to the slide as it is being animated out.
cssAfterobject hash An object which defines css properties that should be applied to the slide immediately after it has animated out.
cssBeforeobject hash An object which defines css properties that should be applied to the slide immediately before it is animated in.