Bill Bellon - SSEC, UW-Madison

JSani - a simple JavaScript animator

About JSani

JSani is a free, lightweight, fast JavaScript/jQuery based animation tool. It is meant to animate a series of images (JPEGs, PNGs, GIFs ...) by switching between them like a flip book, creating an animation. It can also be used as a slideshow. Because it uses JavaScript, HTML and CSS only, it works well on smartphones (iPhone, Android ...). JSani is structured after Tom Whittaker's AniS Java applet.

Contact me if you have questions, need to report a bug or want to be put on a mailing list to be kept informed of new versions to JSani.

Examples

Real-Time U.S. Composite Satellite Animation

Download

Download code (version: 1.30)
Changes:
- Added two new parameters (see below for more information about them): first_frame_pause and frame_pause
Previous Changes: (show | hide)
- Ability to pause on last frame (using a parameter called last_frame_pause) implemented
- bug fix: A previous change broke the Refresh button so that it did not actually force the browser to reload images from server - the Refresh button should now work again.
- bug fix: animation will now continue preloading images and and work if images are missing. See missingimages parameter below
- modified JSani so that hidden input form field names (i.e., the parameter names) are now case insensitive
- added parameter: file_of_filenames as an alternative to filenames parameter
- fixed a bug with IE not displaying animation unless F5 button is pressed
- zoom button with image panning / dragging while zooming
- added mobile browser detection
- zoom button made to not be displayed when mobile browser detected
- changed all hidden input field names to lowercase
- change dwell rates to milliseconds
- added GNU license headers
- released as first public version
- made some minor changes to jsani.loader.js
- added looprock
- the corresponding slower or faster button now becomes grayed out when the max or min dwell rate is reached.
- disabled text highlighting / selection on the buttons so that the button text no longer becomes highlighted when a button is double clicked.
- removed jsani/jquery/ui/
- made buttons larger
- added the word Loading to the loading progress bar
- added a control for just minus/plus speed buttons
- hidden input field parameters in the #jsani container are not overwritten now
- parameterized animation speed config (dwell and nstep params)
- parameterized controls
- changed visual format of speed slider to be a thin white line and made some other minor tweaks
- utils.printDebug() now will create a debug container after the animation if it doesn't exist and only if debug=true in query string
- improved speed slider bar - you can now click on the bar and not just the +/- buttons.
- bug fix: hit the Refresh button when the animation is stopped and then try to stop animation after animation frames reload - can't stop animation anymore
- fixed refresh button so that it now stops animation and then preloads images to restart animation properly
- removed jquery/ui/ from jsani.loader.js

Documentation

Step by step instructions for deploying JSani

Download the JSani code, unpack the files and upload them to your web server
refering to the general documentation and examples below, add the appropriately configured <form></form> JSani container into your web page
add

<script language="javascript" type="text/javascript" src="jsani/jsani.loader.js"></script>

to the <head></head> section of your web page.
in the above <script> tag that you add to your web page, modify the src="" attribute to point to the location where you put the jsani/ folder containing the JSani code (if you put it in the same folder as your web page then the above example should work).
edit the following two lines in the jsani/jsani.loader.js file so that they specify the correct locations for the JSani and jQuery code:

var jsani_dir = 'jsani'; // no trailing /
var jquery_dir = 'jsani/jquery'; // no trailing /

If you put the jsani/ folder in the same folder where your web page is, then you shouldn't have to modify these lines.

General documentation

Example:

<html>

         <head>

         <script language="javascript" type="text/javascript" src="jsani/jsani.loader.js"></script>

         </head>

         <body>

         <form name="jsani" id="jsani" action="#" style="width:
         800px; height: 640px;">

             <input type="hidden" name="filenames" value="image0.jpg,
         image1.jpg, image2.jpg, image3.jpg">

             <input type="hidden" name="imgbaseurl" value="images">

             <input type="hidden" name="imgwidth" value="800">

             <input type="hidden" name="imgheight" value="600">

             <input type="hidden" name="controls"

                    value="previous,
         stopplay, next, looprock, slowfast, zoom, refresh">

             <input type="hidden" name="maxdwell" value="1400">

             <input type="hidden" name="mindwell" value="100">

             <input type="hidden" name="initdwell" value="300">

             <input type="hidden" name="nsteps" value="8">

             <input type="hidden" name="last_frame_pause" value="3">         


             <input type="hidden" name="first_frame_pause" value="2">         

             <input type="hidden" name="frame_pause" value="2:4,3:5">         

         </form>

         </body>

         </html>

The above is an example of how JSani can be used in a web page. Let's start with:

<script language="javascript" type="text/javascript" src="jsani/jsani.loader.js"></script>

This creates the necessary <link></link> and <script></script> tags in the header to link to the JSani and supporting JavaScript and CSS files. The jsani.loader.js must be linked to in the <head></head> section of your page or it will not work.

The actual container for your animation is dynamically generated inside this container:

<form name="jsani" id="jsani" action="#" style="width:
         800px; height: 640px;">

         </form>

It must have an id="jsani". It should also have a width and height specified for it, either via the style="" attribute or via CSS elsewhere (i.e., your own stylesheet or <style></style> section in the page). JSani will automatically resize the images in your animation to fit within the <form id="jsani"></form> container.

Configuring JSani

JSani is configured via hidden form fields like this:

<input type="hidden" name="filenames" value="image0.jpg,
         image1.jpg, image2.jpg, image3.jpg">

If you have used AniS then you will be familiar with this concept, though instead of <param> tags <input type="hidden"> tags are used.

The configuration is comprised of a set of parameter names (the value for the name attribute in the above <input type="hidden"> tag) such as "filenames" and a corresponding value for that parameter (the value of value attribute in the above tag). In the above example, this would be "image0.jpg, image1.jpg, image2.jpg, image3.jpg".

The value of the name attribute in the hidden input fields (i.e., the parameter names) are case insensitive (but the values are NOT).
For example,

<input type="hidden" name="filenames" value="image0.jpg, image1.jpg, image2.jpg, image3.jpg">
and

<input type="hidden" name="FileNames" value="image0.jpg, image1.jpg, image2.jpg, image3.jpg">
will be treated the same. However

<input type="hidden" name="FileNames" value="IMAGE0.jpg, image1.JPG, Image2.jpg, image3.jpg">
is NOT the same.

Parameters - required

filenames: a comma separated list of the filenames of the images comprising your animation.
Example: "image1.jpg, image2.jpg, image3.jpg"

or

file_of_filenames: the URL (relative or absolute) of a text file that contains the filenames for the animation.
Example: "file_of_filenames.txt"

The format of the file_of_filenames should be one filename per line in the order that you want them to appear in the animation. Example:
image1.jpg image2.jpg image3.jpg
imgheight: the height (in pixels) of your images. Example: "800"
imgwidth: the width (in pixels) of your images. Example: "640"
controls: a list of the animation controls you want displayed. Example: "previous, stopplay, next"
Required controls:
- stopplay: the Stop/Play button - will show as "stop" when the animation is playing and when clicked on it will stop the animaiton and change to a "play" button.
Optional controls:
- previous: a previous frame button. Clicking on it will stop the animation and advance to the previous frame of the animation.
- next: a next frame button. Clicking on it will stop the animation and advance to the next frame of the animation.
- looprock: a button that allows the user to toggle between the default loop mode and a rock mode. The rock mode will make the animation rock back and forth between the beginning and end of the animation - when the end of the animation is reached in rock mode, the animation reverses direction until it reaches the first frame at which point it starts going forward again.
- slowfast: two buttons, "slower" and "faster". Clicking on "slower" slows down the animation and clicking on the "faster" button will ... yep, speed up the animation.
- refresh: a refresh button that when clicked on will reload the animation images from the server (useful if you are serving real-time images).
- zoom: when clicked a zoom mode is enabled where the user can zoom in by clicking on the animation or zoom out by CTRL-clicking. Note: the zoom button will not be displayed and is disabled if a mobile browser is detected viewing the animation.

Parameters - optional

imgbaseurl:the URL (relative, absolute ...) of where your images are located. There should NOT be a trailing slash (/). If this parameter is omitted then the current folder where your web page resides is assumed where your images reside. Example: "images".
maxdwell: Maximum dwell rate. Clicking on the "slower" button will keep increasing the dwell rate (how many seconds to dwell on each frame/image in the animation) until the maxdwell rate is reached - this is the slowest the animation can be animated. Units are in milliseconds. Example: "1400". Note: for backwards compatibility, if this value is less than 2.0, it is assumed to be seconds and is multiplied by 1000 to be converted to milliseconds internally.
mindwell: Minimum dwell rate. Clicking on the "faster" button will keep decreasing the dwell rate (how many seconds to dwell on each frame/image in the animation) until the mindwell rate is reached - this is the fastest the animation can be animated. Units are in seconds. Example: "100". Note: for backwards compatibility, if this value is less than 2.0, it is assumed to be seconds and is multiplied by 1000 to be converted to milliseconds internally.
initdwell: Initial dwell rate. Example: "300". Note: for backwards compatibility, if this value is less than 2.0, it is assumed to be seconds and is multiplied by 1000 to be converted to milliseconds internally.
nsteps: How many dwell rate steps are allowed between the mindwell and maxdwell dwell rates when clicking on the "slower" and "faster" buttons. Example: "8"
missingimages: Specifies whether to show or hide missing images in the animation. Set either to "show" or "hide". Default: "hide"
last_frame_pause: Pause on last frame for N*D seconds where N is specified in the value attribute for this parameter and D is the current dwell rate as set by the user using the slowfast controls.

Example:
<input type="hidden" name="last_frame_pause" value="5">

will make JSani pause on the last frame 5 times the current dwell rate. So if for example the user has set the animation speed so that each frame is shown for 1 second then the last frame would be shown for 5 seconds.
first_frame_pause: Pause on the first frame - works the same as last_frame_pause.
frame_pause: Similar to first_frame_pause and last_frame_pause, but you can specify any frame to pause on. The value is a comma separated list of values of the form n:m where n is the frame number (first frame is 0) and m is an integer specifying how much to pause that frame. Example:

<input type="hidden" name="frame_pause" value="2:4,4:2,0:3">

Dwell on the 2nd frame 4 times longer than the current dwell rate,
dwell on the 4th frame 2 times longer, and
dwell on the 0th frame (which is the first frame), 3 times as long.

Note: first_frame_pause and last_frame_pause override this parameter - i.e., if you use this parameter to specify a dwell/pause rate for the first frame, and you use first_frame_pause to specify an different dwell/pause rate, that value will be used for the first frame.

Future Improvements

Overlays
Frame labels and controls
and more ...

Contact me if you wish to be put on a mailing list for announcements regarding future improvements.

Contact info

You can contact me via email contact form.

Copyright Notice

This code is copyrighted under the Gnu General Public License. It is freely available for non-commercial use. Details:

Bill Bellon -- SSEC/UW-Madison