animateText.js

Copyright (c) 2012 Justin Lucas

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Overview

					<ul id="example">
						<li>Coming from the left</li>
						<li>Coming in from the right</li>
						<li>Coming in from the top</li>
					</ul>
					<script type="text/javascript">
						var textObjects = [
							{
								offset: 0,
								duration: 2000,
								animation: 'leftToRight'
							},
							{
								offset: 1000,
								duration: 2000,
								animation: 'rightToLeft'
							},
							{
								offset: 2000,
								duration: 2000,
								animation: 'topToBottom'
							}
						],
						options = {
							repeat: 5
						},
						animations = {
							topToBottom: {
								positions: {
									start: {
										bottom: '100%',
										left: '50%',
									},
									1:  {
										bottom: '0%'
									}
								}
							}
						};
						$("#example").animateText(textObjects, options, animations);
					</script>
				

animatedText() accepts 3 parameters: textObjects, options and animations. Only textObjects is required.

Here's a brief overview of the parts that make up textAnimate.js:

textObjects - A textObject represents a single block of text, contained within an <li>, that animates as a whole. Each textObject has 3 main parameters (animation, offset, duration) that determine which animation to use, when to start and how long it should last. A collection of textObjects make up a textGroup.

animations - An animation contains instructions on how to move and transform a textObject. These instructions are made up of 1 or more 'positions' which describe a state the textObject will animate into.

positions - A position describes a state the textObject will animate into. Each animation contains 1 or more positions. The first position is the starting point for the textObject which will immediately begin animating into the state described in the next position. If more positions exist the textObject will continue animating to each of them, one at a time.

textObjects (array)

textObjects is an array of objects, each one representing a single list item. The order of an object in the array determines which <li> it represents. Every <li> must have a corresponding textObject.

Each textObject has several properties describing how it should be animated (none are required):

									$("#example").animateText([
										{
											animation: 'rightToLeft',
											positions: {
												start: {
													top:'35px',
													'font-size': '37px',
													'font-weight': 700,
													color: '#CCC'
												},
												0: {
													duration: 4000
												}
											}
										}
									]);
								

options (Object)

					$("#example").animateText(
						[{}],
						{
							repeat: 5,
							textObject: {
								offset: 1000,
								animation: 'implode'
							},
							position: {
								duration: 3000,
								easing: 'linear'
							}
						}
					);
				

The options object allows you to change any of the several default values. Properties set in an animation or textObject will override these options. To the right is an example of how to override the default values:

Here's a complete list of the options you can set:

Animations (Object)

The animations parameter allows you to customize existing animations or add your own. The object can contain any number of animations using each animations name as the key. Each animation is itself an object containing a single property named 'positions'.

The positions property contains 1 or more objects each describing a state the textObject will animate into. The first position is always labeled 'start' and is used as the starting point for the textObject. The 'start' position object can contain any style property accepted by jQuery's .css() function. All subsequent positions represent animations and must be labeled from 0 - n. These positions can contain any property accepted by jQuery's .animate() function. They also accept the 'duration' and 'easing' properties:

Preloaded animations - fadeIn, fadeOut, rightToLeft, leftToRight, explode, implode.

				$("#example").animateText(
					[{}],
					{},
					{
						"explode": {
							positions: {
								0: {
									duration: 2000
								}
							}
						}						
					}
				);
				

Customize any of the preset animations by extending them. Simply create an animation object with the same key and include only the properties you would like to change. These changes will be merged into the existing animation. For example, here's how you would change the duration of the '0' position in the 'explode' animation to 2 seconds:

				$("#example").animateText(
					[{
						animation: 'bottomLeftToTopRight'
					}],
					{},
					{
						bottomLeftToTopRight: {
							positions: {
								start: {
									bottom: '0%',
									left: '0%'
								}
								0: {
									bottom: '100%',
									left: '100%',
									easing: 'linear',
									duration: 2000
								}
							}
						}
					}
				);
				

Or, create your own animation from scratch:

Requirements

• jQuery 1.4 or above
• jQuery UI 1.8 and above - only if using an easing function other than 'linear'