Getting Started


Reference jQuery and SpriteSpin scripts

<script src='jquery-1.4.2.js' type='text/javascript' />
<script src='spritespin.js' type='text/javascript' />

Create a container for SpriteSpin

<div id='mySpriteSpin'/>

Initialize the plugin

<script type='text/javascript'>
$("#mySpriteSpin").spritespin({
  // path to the source images.
  source: [
  "path/to/frame_001.jpg",
  "path/to/frame_002.jpg",
  "path/to/frame_003.jpg",
  "path/to/frame_004.jpg",
  "path/to/frame_005.jpg",
  "path/to/frame_006.jpg",
  "path/to/frame_007.jpg",
  "path/to/frame_008.jpg",
  "path/to/frame_009.jpg",
  "path/to/frame_010.jpg",
  ],
  width   : 480,  // width in pixels of the window/frame
  height  : 327,  // height in pixels of the window/frame
});
</script>

Options

There are many options that can be used to initialize the plugin. The following is a set with default values and their meaning. However, it is recommended to take a look at the examples where the options are described with more detail.

Spin.defaults = {
  source            : undefined,    // Stitched source image or array of files
  width             : undefined,    // actual display width
  height            : undefined,    // actual display height
  frames            : undefined,    // Total number of frames
  framesX           : undefined,    // Number of frames in one row of sprite sheet (if source is a spritesheet)
  lanes             : 1,            // Number of 360 sequences. Used for 3D like effect.
  module            : '360',        // The presentation module to use
  behavior          : 'drag',       // The interaction module to use
  renderer          : 'canvas',     // The rendering mode to use
  lane              : 0,            // The initial sequence number to play
  frame             : 0,            // Initial (and current) frame number
  frameTime         : 40,           // Time in ms between updates. 40 is exactly 25 FPS
  animate           : true,         // If true starts the animation on load
  reverse           : false,        // If true animation is played backward
  loop              : true,         // If true loops the animation
  stopFrame         : 0,            // Stops the animation at this frame if loop is disabled
  wrap              : true,         // If true wraps around the frame index on user interaction
  wrapLane          : false,        // If true wraps around the lane index on user interaction
  sense             : 1,            // Interaction sensitivity used by behavior implementations
  senseLane         : undefined,    // Interaction sensitivity used by behavior implementations
  orientation       : 'horizontal', // Preferred axis for user interaction
  detectSubsampling : true,         // Tries to detect whether the images are downsampled by the browser.
  scrollThreshold   : 50,           // Number of pixels the user must drag within a frame to enable page scroll (for touch devices)
  preloadCount      : undefined,    // Number of frames to preload. If nothing is set, all frames are preloaded.
  onInit            : undefined,    // Occurs when plugin has been initialized, but before loading the source files
  onProgress        : undefined,    // Occurs when any source file has been loaded
  onLoad            : undefined,    // Occurs when all source files have been loaded
  onFrame           : undefined,    // Occurs when the frame number has been updated (e.g. during animation)
  onDraw            : undefined     // Occurs when all update is complete and frame can be drawn
};

API Object

SpriteSpin offers an API object with functions that simplify certain tasks.

var api = $("#mySpriteSpin").spritespin({
  // initialization options
}).spritespin("api");

For the available API methods take a look at the annotated source code.

You can add your own methods to the api.

SpriteSpin.extendApi({
  myCustomFunction: function(){
    this.data.customValue = 'i have added something to the sprite spin data object';
  }
});

Data Object

You can access the data object that represents the state of the SpriteSpin instance and manipulate it directly.

var data = $("#mySpriteSpin").spritespin({
  // initialization options
}).data("spritespin");

Most of the initialization parameters are available in the data object. However, changing some of them may break the instance. For example you can not change the source images or the size properties directly. Those options need a special processing by the plugin before they can be actively used.