AnimateImage Old Version (v0.9 – v1.0.4)
* This post is for information about older AnimateImage (version 0.8.x).
Index
Introduction
AnimateImage is a JavaScript code which displays multiple images continuously like animated GIF.
* See AnimateImage Official Site for latest information.
Usage
Write the following code in “head” or “body” element to load AnimateImage script.
<script type="text/javascript" src="animateImage.min.js"></script>
Write the following code if you animate 1.png, 2.png, … 10.png in ‘images’ directory.
<img src="images/1.png" data-files="[1-10].png" />
Or write the following code if you use AnimateImage from inside JavaScript.
<script type="text/javascript"> animateImage('Image[1-10].png'); </script>
Image files that can be animated are the following 4 types.
- Sequential number (0, 1, 2, 3, …)
- Sequential zero-padded number (01, 02, …, 001, 002, …)
- Sequential alphabet (a, b, c, …, A, B, C, …)
- Arbitrary files (foo.png, bar.jpg, baz.gif, …)
Options to customize animation are more than 15.
- Image title, alternative text of image
- ID string and class name of image element
- Animation interval, delay between animation cycles
- Repeat count of animation
- Whether to rewind to the first image at the end of animation
- Whether to pause at the first/last image in animation
- Whether to display blank image between animation cycles
Furthermore you can do below by writing JavaScript codes.
- Contolling animation (play/stop/replay)
- Getting animation img element, then modify/insert it
- Changing common options for all animations
* See API Specification and Code Samples for more information.
* you can play/stop/replay animatione. you can change common options of all animations.
Download
This is the source code of old version (v1.0.4).
- animateImage-1.0.4.min.js
-
- v1.0.4, 2012-08-27, 5.5 KB
- Free license (for personal & non-commercial, donate to support)
- Optimized and compressed code
- animateImage-1.0.4.js
-
- v1.0.4, 2012-08-27, 18.8 KB
- Commercial license ($5.00)
- Uncompressed code with comments
- Paid support (technical questions, customization, etc.)
API Specification
Auto Apply img Elements
AnimateImage is applied automatically to ‘img’ elements that have ‘data-files’ attribute.
<img src="" data-files="" title="" alt="" id="" class="" style="" data-delay="" data-repeat="" data-rewind="" data-pauseAtFirst="" data-pauseAtLast="" data-showBlank="" data-cycleDelay="" data-blankClassName="" />
You need to specify undefined attributes with custom data-* attributes in ‘img’ element. ‘src’ and ‘data-files’ attributes are required in AnimateImage. ‘data-files’ attribute is specified with file name including format string, or specified with relative path to directory when specifying directory name with format string. See Code Sample 3 for details.
animateImage() Function
Animates multiple images.
Syntax
animator = animateImage(files, options)
* The following old syntax also works.
animator = animateImage(files, title, id, delay, repeat, rewind)
Arguments
- files (required)
- Image files specified with file name including the format string or array of file name
-
- Sequential Number
- In “[d-d]” format. Specify as “[0d-dd]” or “[00d-ddd]” if zero-padding.
- Sequential Alphabet
- In “[a-z]” format. Specify as “[A-Z]” if uppercase.
- Comma Separated Values
- In “[foo, bar, baz]” format. Specify as “[foo.png, bar.jpg, baz.gif]” if different extensions.
- options
- Animation settings specified with object literal (
{ properyName: value }
)- title
- Image title that is set to img@title attribute
- alt
- Alternative text that is set to img@alt attribute (options.title in default)
- id
- ID string of img element. It is unique value for each animation.
- delay
- Animation delay in milliseconds (Animations.delay in default)
- repeat
- Repeat count of animation (Animations.repeat in default)
- rewind
- Whether to rewind to the first image at the end of animation (Animations.rewind in default)
- pauseAtFirst
- Whether to pause at the first image in animation (Animations.pauseAtFirst in default)
- pauseAtLast
- Whether to pause at the last image in animation (Animations.pauseAtLast in default)
- showBlank
- Whether to display blank image between animation cycles (Animations.showBlank in default)
- cycleDelay
- Delay between animation cycles in milliseconds (Animations.cycleDelay in default)
- className
- Class name of img element, separated by spaces (Animations.className in default)
- blankClassName
- Class name of img element, added to blank image (Animations.blankClassName in default)
- attr
- Arbitrary attributes specified with object literal (
{ attributeName: value }
) - css
- Arbitrary CSS properties that are set to img@style, specified with object literal (
{ propertyName: value }
). - You can use property names in DOM formatting (ex. borderLeft) or CSS formatting (ex. border-left). You need to enclose hyphenated names in quotation marks as
{ 'property-name': value }
. - imgElem
- img element specified with Image object. Use it to specify created img element. (img element will be created if omitted)
- output
- Whether to output img element
Return Value
- animator
- ImageAnimator object. you can stop/replay animation using this object.
Animations Object
Common options in AnimateImage.
* A value that is set before calling animateImage() is used. If you change a value, you should set before the start of animation.
Properties
- delay
- Animation delay in milliseconds. Default is 500 ms.
- repeat
- Repeat count of animation. -1 means infinite iteration, and 0 means no animation (i.e. only displays first image). Default is -1.
- rewind
- Whether to rewind to the first image at the end of animation. Default is false.
- pauseAtFirst
- Whether to pause at the first image in animation. Default is false.
- pauseAtLast
- Whether to pause at the last image in animation. Default is false.
- showBlank
- Whether to display blank image between animation cycles. Default is false.
- Blank image is displayed in the size of the first image. This is not availabe in IE7 or earlier because it uses transparent GIF with data:url.
- cycleDelay
- Delay between animation cycles in milliseconds. Default is 0.
- className
- Class name of img element, separated by spaces. class attribute is not added if empty. Default is “animation”.
- blankClassName
- Class name of img element, added to blank image. class attribute is not added if empty. Default is “blank”.
- output
- Whether to output img element. Default is true.
ImageAnimator Object
An object to control animation of images.
Properties
- imgElem
- ‘img’ element that is created by AnimateImage, or specified with options.imgElem
Constructor Function
ImageAnimator(files, options)
* See animateImage() function about arguments specification. The following old syntax also works.
ImageAnimator(files, title, id, delay, repeat, rewind)
animate(replay) Method
Plays (Replays) animation.
When argument “replay” is true or you call it after animation, the animation is replayed from the beggining.
stopAnimate() Method
Stops (Pauses) running animation.
Code Samples
- Code Sample 1: Sequential File Names
- Code Sample 2: Arbitrary File Names
- Code Sample 3:Specifying Directory Name with Format String
- Code Sample 4: title/alt Attributes
- Code Sample 5: id/class Attributes
- Code Sample 6: delay/cycleDelay Options
- Code Sample 7: repeat/rewind Options
- Code Sample 8: pauseAtFirst/Last Options
- Code Sample 9: Arbitrary Attributes
- Code Sample 10: Arbitrary CSS Properties
- Code Sample 11: Common Options (Animations Object)
- Code Sample 12: Animation Control (Start/Stop/Replay)
- Code Sample 13: Using Created img Elements
- Code Sample 14: Getting/Modifying/Inserting img Elements
Code Sample 1: Sequential File Names
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" /> <img src="images/01.png" data-files="[01-99].png" /> <img src="images/001.png" data-files="[001-999].png" /> <img src="images/a.png" data-files="[a-z].png" /> <img src="images/A.png" data-files="[A-Z].png" /> <img src="dir/pre-1_post.jpg" data-files="pre-[1-10]_post.jpg" />
JavaScript
animateImage('images/[0-9].png'); animateImage('images/[01-99].png'); animateImage('images/[001-999].png'); animateImage('images/[a-z].png'); animateImage('images/[A-Z].png'); animateImage('dir/pre-[1-10]_post.jpg'); // prefix/suffix
Code Sample 2: Arbitrary File Names
img Elements (HTML)
<img src="images/foo.png" data-files="[foo, bar, baz].png" /> <img src="images/foo.png" data-files="[foo.png, bar.jpg, baz.gif]" /> <img src="dir/pre-foo_post.jpg" data-files="pre-[foo, bar, baz]_post.jpg" />
JavaScript
animateImage('images/[foo, bar, baz].png'); animateImage('images/[foo.png, bar.jpg, baz.gif]'); animateImage('dir/pre-[foo, bar, baz]_post.jpg'); // prefix/suffix
* You can also specify array of file name instead of file name including format string.
var files = ['images/foo.png', 'images/bar.png', 'images/baz.png']; animateImage(files); animateImage(['images/foo.png', 'images/bar.jpg', 'images/baz.gif']);
Code Sample 3:Specifying Directory Name with Format String
img Elements (HTML)
<img src="parent/child/image0.png" data-files="image[0-9].png" /> <img src="parent/child0/image.png" data-files="child[0-9]/image.png" /> <img src="parent0/child/image.png" data-files="parent[0-9]/child/image.png" />
* ‘data-files’ attribute is specified with file name including format string, or specified with relative path to directory when specifying directory name with format string.
JavaScript
animateImage('parent/child/image[0-9].png'); animateImage('parent/child[0-9]/image.png'); animateImage('parent[0-9]/child/image.png');
* Specify path to directory to data-files attribute if directory name is sequential.
Code Sample 4: title/alt Attributes
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" title="foo" alt="foo" /> <img src="images/0.png" data-files="[0-9].png" title="foo" alt="bar" /> <img src="images/0.png" data-files="[0-9].png" alt="bar" /> <img src="images/0.png" data-files="[0-9].png" alt="" />
JavaScript
animateImage('images/[0-9].png', { title: 'foo' }); // title="foo" alt="foo" animateImage('images/[0-9].png', { title: 'foo', alt: 'bar' }); // title="foo" alt="bar" animateImage('images/[0-9].png', { alt: 'bar' }); // alt="bar" animateImage('images/[0-9].png', { alt: '' }); // alt=""
* Add alt attribute with empty string to img element (img@alt=””) if alternative text for images is unnecessary.
Code Sample 5: id/class Attributes
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" /> <img src="images/0.png" data-files="[0-9].png" id="foo" /> <img src="images/0.png" data-files="[0-9].png" class="bar" /> <img src="images/0.png" data-files="[0-9].png" class="bar baz" /> <img src="images/0.png" data-files="[0-9].png" class="" />
JavaScript
animateImage('images/[0-9].png'); // class="animation" animateImage('images/[0-9].png', { id: 'foo' }); // id="foo" class="animation" animateImage('images/[0-9].png', { className: 'bar' }); // class="bar" animateImage('images/[0-9].png', { className: 'bar baz' }); // class="bar baz" animateImage('images/[0-9].png', { className: '' }); // no class
* Define style rules with class/id selectors in CSS files or style elements.
img.animation { background: white; } img#foo { background: silver; } img.bar { background: gray; } img.baz { background: black; }
Code Sample 6: delay/cycleDelay Options
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" /> <img src="images/0.png" data-files="[0-9].png" data-delay="1000" /> <img src="images/0.png" data-files="[0-9].png" data-cycleDelay="2000" />
JavaScript
animateImage('images/[0-9].png'); // delay=500, cycleDelay=0 animateImage('images/[0-9].png', { delay: 1000 }); animateImage('images/[0-9].png', { cycleDelay: 2000 });
Code Sample 7: repeat/rewind Options
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" /> <img src="images/0.png" data-files="[0-9].png" data-repeat="1" /> <img src="images/0.png" data-files="[0-9].png" data-repeat="2" data-rewind="true" />
JavaScript
animateImage('images/[0-9].png'); // repeat=-1, rewind=false animateImage('images/[0-9].png', { repeat: 1 }); animateImage('images/[0-9].png', { repeat: 2, rewind: true });
Code Sample 8: pauseAtFirst/Last Options
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" /> <img src="images/0.png" data-files="[0-9].png" data-pauseAtFirst="true" data-pauseAtLast="true" />
JavaScript
animateImage('images/[0-9].png'); // pauseAtFirst=false, pauseAtLast=false animateImage('images/[0-9].png', { pauseAtFirst: true, pauseAtLast: true });
Code Sample 9: Arbitrary Attributes
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" width="100" height="100" longdesc="long description" />
JavaScript
animateImage('images/[0-9].png', { attr: { width: 100, height: 100, longdesc: 'long description' } });
Code Sample 10: Arbitrary CSS Properties
img Elements (HTML)
<img src="images/0.png" data-files="[0-9].png" style="border: solid; border-top: dotted; border-bottom: dashed" />
JavaScript
animateImage('images/[0-9].png', { css: { border: 'solid', borderTop: 'dotted', 'border-bottom': 'dashed' } });
Code Sample 11: Common Options (Animations Object)
JavaScript
animateImage('images/[0-9].png'); // delay=500, repeat=-1 Animations.delay = 1000; Animations.repeat = 1; animateImage('images/[0-9].png'); // delay=1000, repeat=1 animateImage('images/[0-9].png'); // delay=1000, repeat=1 animateImage('images/[0-9].png', { delay: 2000, repeat: -1 });
Code Sample 12: Animation Control (Start/Stop/Replay)
JavaScript
var animator = new ImageAnimator('images/[0-9].png'); animator.animate(); var animator2 = animateImage('images/[0-9].png');
* Write the following input elements when you control animation behavior.
<input type="button" value="Start" onclick="animator.animate()" /> <input type="button" value="Stop" onclick="animator.stopAnimate()" /> <input type="button" value="Replay" onclick="animator.animate(true)" />
Code Sample 13: Using Created img Elements
JavaScript
var imgElem = new Image(); imgElem.src = 'images/0.png'; imgElem.width = 100; imgElem.height = 100; imgElem.setAttribute('longdesc', 'long description'); animateImage('images/[0-9].png', { imgElem: imgElem });
Code Sample 14: Getting/Modifying/Inserting img Elements
JavaScript
var animator = animateImage('images/[0-9].png', { output: false }); animator.imgElem.width = 100; animator.imgElem.height = 100; animator.imgElem.setAttribute('longdesc', 'long description'); document.getElementById('foo').appendChild(animator.imgElem);
FAQ
- Which to Use Auto Apply ‘img’ Elements or JavaScript Codes
- Differences between ImageAnimator object and animateImage() function
- How to describe valid HTML as complying with Web standards
Which to Use Auto Apply ‘img’ Elements or JavaScript Codes
- Auto Apply ‘img’ Elements
-
- Improved readability by not writing ‘script’ elements and JavaScript codes
- No need for JavaScript codes. It is also available in where JavaScript is limited.
- ‘img’ elements are always displayed even if JavaScript is disabled or JavaScript errors occur (equivalent of ‘noscript’ elements)
- JavaScript Codes
-
- Animation behavior (start/stop/replay) is controllable
- Handling ‘img’ elements in JavaScript (to get, create, modify, insert, etc.)
- Common options can be changed
* FYI: The two sample codes below are almost equivalent.
<p><img src="images/0.png" data-files="[0-9].png" /></p>
<p><script type="text/javascript">animateImage('images/[0-9].png');</script></p> <noscript><p><img src="images/0.png" /></p></noscript>
Differences between ImageAnimator object and animateImage() function
- ImageAnimator Object
- Use when you want to control the start timing of animation.
-
- In creating object, first image is displayed.
- Animation does not start until calling animate() method.
- animateImage() Function
- Use when you do not care about starting animation automatically.
-
- In calling the function, first image is displayed and animation starts.
How to describe valid HTML as complying with Web standards
There are three points below.
- ‘alt’ attribute is mandatory in ‘img’ element
- ‘script’ element is inline in body, and ‘noscript’ element is block
- ‘noscript’ element contains only block elements
Then valid HTML as complying with Web standards is as follows.
<div> <script type="text/javascript"> animateImage('image[0-9].png', 'text'); </script> </div> <noscript> <div><img src="image0.png" alt="text" /></div> </noscript>
“keyboard keys” by chromatix is licensed under Creative Commons License.