[[PlayerToc(rotator)]]

= Image Rotator API Calls =

The Image Rotator contains a small javascript API. It can be enabled by setting the flashvar ''enablejs=true''. When set, the rotator can be controlled by calling the function ''sendEvent()'' on the rotator. Additionally, the rotator will automatically send updates to a global ''getUpdate()'' javascript function.

== enablejs == 

Here's an example of an embed code that enables the rotator javascript API:

{{{
<embed 
    src="rotator.swf" 
    width="300" 
    height="300" 
    flashvars="file=playlist.xml&enablejs=true"
    name="rotator"
    id="rotator"
/>
}}}

The ''enablejs=true'' flashvar turns on the API. The ''name'' and ''id'' flashvar give the rotator a unique ID in the HTML DOM, so its ''sendEvent'' function can be called.

== sendEvent ==

The ''sendEvent'' function can be directly called upon the rotator. If the''name'' and ''id'' of the rotator is set to ''rotator'' (as in the above embed code), events can be sent like this:

{{{
function next() {
    // make the imagerotator jump to the next image.
    document.getElementById('rotator').sendEvent('next');
};
}}}

The following events are available:

 * '''getlink''' ''(index''): redirect the browser to the link of photo number ''index''. 
 * '''next''':  jump to the next image.
 * '''playitem''' (''index''): jump to image number ''index''. 
 * '''playpause''': pause or resume the rotator (acts like a toggle). 
 * '''prev''': jump to the previous image. 
 * '''volume''' (''percent''): set the volume of the audiotrack to ''percent'' (provided you use an audiotrack). 

== getUpdate == 

When the ''enablejs=true'' flashvar is set, the rotator automatically sends status updates to javascript. In order to receive those, you need to define a javascript function called ''getUpdate'' on your page:

{{{
function getUpdate(type,parameter1,parameter2) { 
    alert('Received a '+type+' update from the rotator');
    alert('Parameters: '+parameter1+' - '+ parameter2);
};
}}}

The rotator sends the following types of updates:

 * '''item''' (''index''): the rotator switches to image number ''index''. 
 * '''load''' (''percent''): the current image is loaded for ''percent'' percent. 
 * '''size''' (''width'',''height''): the current image has the dimensions ''width'' by ''height''. 
 * '''state''' (''index''): the current playback state is ''state'', whereby the ''state'' can be the following:
   *  '''0''': the rotatot is paused.
   * '''1''': the rotator is buffering for playback.
   * '''2''': the rotator is playing.
   * '''3''': the rotator has completed playback.
   * '''4''': the rotator is idle; has not started yet.
 * '''time''' (''elapsed'',''remaining''): the rotator has played the current image for ''elapsed'' seconds and has ''remaining'' seconds to go yet. 
 * '''volume''' (''percent''): the current volume of the rotator is ''percent''.