• AnimateImage Old Version (v0.9 – v1.0.4)

    animated transparent PNGs

    * 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
    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

    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.

    Post Tagged with

Leave a Reply

Your email address will not be published.