The SpryEffects library is a stand-alone JavaScript effects library. It provides the following visual effects that can be applied to almost any HTML element on an page. SpryEffects.js has no other dependencies.
Be sure to check out the samples directory to see these effects in action.
The Spry Effects include:
Appear/Fade | Makes an element appear or fade away |
Highlight | Flashes a color as the background of an element |
BlindUp/BlindDown | Simulates a window blind, up or down, where the contents of the affected elements stay in place |
Slide | Simulates a window blind, where the contents of the affected element scroll accordingly (vertical or horizontal) |
Grow/Shrink | Increases/reduces the size of the element |
Shake | Moves the element slightly to the left, then to the right, repeatedly |
Squish | Reduces the element to its top-left corner and disappears |
For each effect, you must set the target element to which you want to apply the effect. The element parameter can be either a string containing the id of the element or a Java Script DOM element object.
Additionally, effects may have several optional parameters. (The number of optional parameters depends on the effect.) If you don't set optional parameters default values will be provided.
Example: Appear/Fade effect
new Spry.Effect.AppearFade('targetID',{duration: 1000,from: 0,to: 100, toggle: true});
You must enclose optional parameters in curly braces.
All effects (except the Shake-Effect) provide an optional toggle. This means that if you invoke an effect again, the effect reverses its behavior. For example, the first click will Fade the element. Click the same thing again will have the element Appear again. The toggle option is turned off by default.
For all effects you can pass a setupCallback and a finishCallback function. The setupCallback function is a function that is called before the effect starts; the finishCallback function is a function that is called after the effect finished.
The two parameters are:
Example:
new Spry.Effect.AppearFade('targetID',{duration: 1000,from: 0, to: 100,toggle: true, setup: setupFunc,finish: finishFunc}); function setupFunc(elmentObj , AppearFadeObj) { alert('The ' + AppearFadeObj.name +' effect now starts'); } function finishFunc(elmentObj , AppearFadeObj) { elmentObj.style.backgroundColor= "#ff0000"; // set the element background color to red }
Most effects provide the optional parameter 'transition'. This parameter describes the transition of the effect while the effect is performing from start to stop. Two values are allowed:
Default for all effects is Spry.sinusoidalTransition.
![]() |
![]() |
linear Transition | sinusoidial transition |
Spry.Effect.AppearFade(element, options)
elements not allowed | applet, body, iframe, object, tr, tbody, th |
duration | duration of the effect in milliseconds, default: 1000 |
from | from opacity in %, default: 0 |
to | to opacity in %, default: 100 |
toggle | toggle effect, default: false |
transition | kind of Transition ('Spry.sinusoidalTransition' or 'Spry.linearTransition'), default: 'Spry.sinusoidalTransition' |
setup | setup callback, default: null |
finish | finish callback, default: null |
Example:
new Spry.Effect.AppearFade('targetID',{duration: 1000,from: 0,to: 100,toggle: true});
Spry.Effect.Highlight(element, options)
elements not allowed | applet, body, frame, frameset, noframes |
duration | duration of the effect in milliseconds, default: 1000 |
from | start color (#rrggbb), default: background-color of the target element (if possible) |
to | end color (#rrggbb) |
restoreColor | restore color (ater effect finished), default: same like from-value; |
toggle | toggle effect, default: false |
transition | kind of Transition ('Spry.sinusoidalTransition' or 'Spry.linearTransition'), default: 'Spry.sinusoidalTransition' |
setup | setup callback, default: null |
finish | finish callback, default: null |
Note:
To get a reasonable appearance when toogling the effect, the restoreColor is not set at the end of the reverse effect. The restoreColor is only set in 'forward' direction.
Example:
new Spry.Effect.Highlight('targetID',{duration:1000,from:'#00ff00',to:'#0000ff',restoreColor:'#00ff00'});
Spry.Effect.Blind(element, options)
allowed elements | address, dd, div, dl, dt, form, h1, h2, h3, h4, h5, h6, p, ol, ul, li, applet, center, dir, menu, pre |
duration | duration of the effect in milliseconds, default: 1000 |
from | pixel or % of size to start, default: 100% |
to | pixel or % of size to end, default: 0% |
toggle | toggle effect, default: false |
transition | kind of Transition ('Spry.sinusoidalTransition' or 'Spry.linearTransition'), default: 'Spry.sinusoidalTransition' |
setup | setup callback, default: null |
finish | finish callback, default: null |
Example:
new Spry.Effect.Blind('targetID',{duration: 1000,from: '100%',to: '0%'});
Spry.Effect.Slide(element, options)
allowed elements | blockquote, dd, form, div, center |
duration | duration of the effect in milliseconds, default: 2000 |
from | pixel or % of size to start, default: 100% |
to | pixel or % of size to end, default: 0% |
horizontal | slide direction, default: false (vertical) |
toggle | toggle effect, default: false |
transition | kind of Transition ('Spry.sinusoidalTransition' or 'Spry.linearTransition'), default: 'Spry.sinusoidalTransition' |
setup | setup callback, default: null |
finish | finish callback, default: null |
Note:
The target element needs a second div element which wraps the content of the target element:
<div id='targetID'> <div>sample Text</div> </div>
Example:
new Spry.Effect.Slide('targetID',{duration: 1000,from: '100%',to: '0%'});
Spry.Effect.GrowShrink(element, options)
allowed elements | address, dd, div, dl, dt, form, img, p, ol, ul, applet, center, dir, menu, pre |
duration | duration of the effect in milliseconds, default: 500 |
from | pixel or % of size to start, default: 0% |
to | pixel or % of size to end, default: 100% |
referHeight | reference direction for the from/to parameters, if set in pixel (true: height, false: width), default: false |
growCenter | growing position of the element (true: grow from center, false: grow from top left corner), default: true |
toggle | toggle effect, default: false |
transition | kind of Transition ('Spry.sinusoidalTransition' or 'Spry.linearTransition'), default: 'Spry.sinusoidalTransition' |
setup | setup callback, default: null |
finish | finish callback, default: null |
Example:
new Spry.Effect.GrowShrink('targetID',{duration: 1000,from: '0%', to: '100%'});
Spry.Effect.Shake(element, options)
allowed elements | address, blockquote, dd, div, dl, dt, fieldset, form, h1, h2, h3, h4, h5, h6, iframe, img, object, p, ol, ul, li, applet, dir, hr, menu, pre, table |
the duration is fix: 500ms | |
setup | setup callback, default: null |
finish | finish callback, default: null |
Example:
new Spry.Effect.Shake('targetID')
Spry.Effect.Squish(element, options)
allowed elements | address, dd, div, dl, dt, form, img, p, ol, ul, applet, center, dir, menu, pre |
duration | duration of the effect in milliseconds, default: 500 |
toggle | toggle effect, default: false |
setup | setup callback, default: null |
finish | finish callback, default: null |
Example:
new Spry.Effect.Squish(targetID,{duration: 1000});
Spry Effects are set up by combining core effects. Core effects are: Move, MoveSlide, Size, Opacity, and Color. These core effects change small aspects of the style definition of HTML elements. For example, Move changes the top-left position of the HTML element so that it appears to move on the page.
Combined effects of the Spry framework are Highlight, GrowShrink, Shake, and Squish. The combined effects execute multiple core effects on the HTML element. GrowShrink changes the size of the element while at the same time changing the position. The position must be changed to let the element appear to stay centered in the same position while the size is modified. GrowShrink additionally applies the Opacity core effect to let the element appear or fade gradually while resizing it.
Combined effects are built by using the Cluster effect. The Cluster effect acts as a container for multiple core effects. Like a regular effect, the Cluster effect has a start() function. But unlike regular effects, Cluster provides the methods addNextEffect() and addParallelEffect(). Internally the Cluster effect includes an array of added effects over which it iterates when it's called to start.
With the Cluster effect it is possible to compose complex effects by packaging multiple core effects together. The effects are chained by calling addNextEffect() or addParallelEffect() with the core effect as parameter. The order in which the assembled effects begin is determined by the order in which they were added to the Cluster effect. When adding an effect with the addNextEffect() function, the function starts after the previous effect stops executing. But when adding an effect with the addParallelEffect() function, the effect begins as soon as possible. Although the effects of the Cluster are triggered in chained order, the execution of the effects can execute in parallel if they were added as parallel effects. Parallel effects execute simultaneously while effects added with the addNextEffect() function execute in sequence. Each core effect can be added as parallel or sequential.
In the SpryEffects.js file, you can find additional examples of combined core effects. Pulsate, Puff, DropOut and Fold demonstrate the construction and behaviour of advanced effect composition.
The model of constructing an advanced effect composition is a uniform procedure. Let's take a look at the Puff effect to get a further understanding of the workings of an advanced effect composition.
Calling the Puff effect on an HTML page looks as follows: "Spry.Effect.Puff(this)". Calling a Spry effect always takes the same syntax: "Spry.Effect" followed by the name of the effect. A Spry effect accepts two parameters: a reference to the HTML element on which the effect is performed, and additional options. We will look at the additional options parameter later on. The reference to the HTML element can be an actual reference (like "this" or "document.getElementById("myId")) or the id of an HTML element on the current page. The effect can be invoked by any event handler (like "onmouseup" or "onmouseover").
You assemble the Puff effect by adding the Size effect, then the Opacity effect, and finally the Move effect to the Cluster. After the cluster has been set up, you assign the cluster a unique name, and call "SpryRegistry.getRegisteredEffect()" with the element and the cluster as parameters. On the returned effect of this function, the start() call triggers the execution of the assembled effect. The last task of any assembled effect always is the returning of the registered Effect.
Spry.Effect.Puff = function (element, options) { [...] var puffEffectCluster = new Spry.Effect.Cluster; var doScaleContent = false; options = {duration:durationInMilliseconds, toggle:false, scaleContent:doScaleContent}; var sizeEffect = new Spry.Effect.Size(element, fromRect, toRect, options); puffEffectCluster.addParallelEffect(sizeEffect); options = {duration:durationInMilliseconds, toggle:false}; var fromOpacity = 1.0; var toOpacity = 0.0; var opacityEffect = new Spry.Effect.Opacity(element, fromOpacity, toOpacity, options); puffEffectCluster.addParallelEffect(opacityEffect); options = {duration:durationInMilliseconds, toggle:false}; var fromPos = new Spry.Effect.Utils.Position; fromPos.x = 0; fromPos.y = 0; var toPos = new Spry.Effect.Utils.Position; toPos.x = startWidth / 2.0 * -1.0; toPos.y = startHeight / 2.0 * -1.0; var moveEffect = new Spry.Effect.Move(element, fromPos, toPos, options); puffEffectCluster.addParallelEffect(moveEffect); puffEffectCluster.setup = setupCallback; puffEffectCluster.finish = finishCallback; puffEffectCluster.name = 'Puff'; var registeredEffect = SpryRegistry.getRegisteredEffect(element, puffEffectCluster); registeredEffect.start(); return registeredEffect; } |
One optional parameter of any effect is called "toggle". If toggle is set to true, the effect reverses on its next invocation. For example, you can run AppearFade() to let an element appear or fade. If an element should toggle between appear and fade with each invocation, the option toggle must be set to true. After the element appears, the element fades away with the next invocation of the effect. To make toggle work, you must call SpryRegistry.getRegisteredEffect() to make sure an element-effect combination is instantiated only once. Each element-effect combination has a private member variable called "direction" with which the current direction of the effect is set and known.
Other optional parameters of each core effect are "duration" and "transition". The duration sets the lifetime of the effect in milliseconds. The transition variable stores the kind of interpolation that is performed between the beginning and end of the effect's lifetime. Linear and sinusoidal transitions are provided.
Each core effect is derived from the Spry.Effect.Animator object. The Animator object provides the start() and stop() functions in which a JavaScript timer object is initialized and stopped. Stop() calls JavaScript's clearInterval() while start() sets drawEffect() as the designated function of the internal timer by calling JavaScript's setInterval(). DrawEffect() calculates the current position in the effect's lifetime (between 0.0 and 1.0) and passes that position to the animate() function.
Each core effect implements an animate() function. The animate() function is the main part of each core effect in which the style of the HTML element is dynamically changed. Assumptions of preconditions are as minimal as possible. Under some circumstances, however, some environmental preconditions are necessary. For example, to display an effect, the display and visibility style attributes must not hide the element. (If the element is hidden for some reason, it must be set to a visible state when the effect is invoked).
Highlight is a special effect in that it uses the setup and finish callbacks. Each core effect can have a setup or finish callback set. Before starting the timer the Animator object makes sure that the setup callback function is called if it is set, and after clearing the timer, the Animator calls the finish callback if there is one set.