Spry Effects Migration from 1.4 to 1.5

About the Spry Effects changes in 1.5

For Spry 1.5 we decided that we had to make some changes to SpryEffects.js so that not only did they work better, but they were better integrated into the rest of the toolkit. We wanted to offer users the ability to add observers in the same way you do it now for the data sets and regions. Another important change is the ability to run multiple effects like Slide, Squish, Highlight in clusters, just like we did for Move, Size, Opacity or Color.

The new implementation allowed us to redesign the current Effect Classes. We transformed the static animation functions into classes that will inherit the notification mechanism and the existing Cluster interface. As an added benefit, we fixed some known bugs like reverting the order of running subeffects inside a cluster when toggling.

We don't easily invoke the 'pre-release' clause to make big changes to the framework, especially when it will impact existing pages. In the process of this transformation we we worked to keep backward compatibility and provide a way for users to migrate their pages that already use Spry Effects. This document will describe those changes and give examples of the new code.

If you want to upgrade your Spry Effects to 1.5, you will have to make some code changes.

Structure changes

The most important change we did to the Spry Effects was to change from static functions to classes.

This means that you will have to change the way you call the effects. This will look familiar if you have used Spry widgets before.

In the Spry 1.4 or earlier, you would attach an Effect to an element's onclick event. The code it would look like this:

<a href="#" onclick="Spry.Effect.Slide('element', {toggle:true});">Click to animate</a>

<div id="element">I'm the animated div</div>

If you just drop in SpryEffect.js 1.5 onto your site, your page animation will stop working when you click the element.

In the first example you'll receive a JavaScript alert error with the following text:

"Spry.Effect ERR: The Slide class can't be accessed as a static function anymore. Please read Spry documentation.

If your page looks like the second example, you will not receive any error message but the animation fail to work.

There are two possible ways to migrate your code so they work with Spry 1.5:

Method 1: Transform your functions into classes

This is the method we advise users to follow. You will have a better control over the effects on the page and you will be ready to use all the new functions included in Spry 1.5.

Part 1: Move code

The first step will be to extract the code from the HTML and move it inside a <script> tag below the element that will be animated. We recommend putting it just above the closing body tag.

<a href="#" onclick="">Click to animate</a>
<div id="element">I'm the animated div</div>
<script type="text/javascript">
    Spry.Effect.Slide('element', {toggle:true});

The next step will be to add the keyword 'new' in front of the JavaScript line (if it is not there already) and assign the resulting object to a global variable:

<a href="#" onclick="">Click to animate</a>
<div id="element">I'm the animated div</div>
<script type="text/javascript">
    var slide_effect = new Spry.Effect.Slide('element', {toggle:true});

The variable name can be whatever you wish. This name will be used to control the effects, as noted below.

We have created the Effect object and saved it into a variable. The effect will no longer auto-start, as in the previous versions. We will now integrate the effect back into the element to react to the users clicks. For this we will have to call the 'start()' method. The start() method will automatically take care of running the effect and also the toggle when called subsequent times (if the toggle option is set).

<a href="#" onclick="fade_effect.start();">Click to animate</a>
<div id="element">I'm the animated div</div>
<script type="text/javascript">
    var slide_effect = new Spry.Effect.Slide('element', {toggle:true});

Part 2: Effects renamed/removed

When we started the new Effect structure migration, we renamed couple of the effects. The goal was to make the API names more clear. Here is a list of the former names of the effects and the new ones. The MoveSlide animator was removed. The code it contain was moved into the Slide cluster.

So, in the code scenario above, if your code used one of the 3 Effects that had a name change, you will have to make one more small change: old name to new name. Change:

<div id="element" onclick="fade_effect.start();">I'm the animated div</div>
<script type="text/javascript">
    var fade_effect = new Spry.Effect.AppearFade{toggle:true});

That's it! The effect should be working normally.

Method 2: Use the backward compatible wrappers functions

For backward compatibility and for easy migration for users, we included a list of wrapper functions that takes the existing function and forwards it to the new version.

To enable these wrapper functions, we added "Do" to the function name. The name changes are as follows:

Because we renamed some of the effects during the migration process, the wrappers are based on the new effects names.

So, in your code, simply change:

<a href="#" onclick="Spry.Effect.AppearFade('element', {toggle:true});">Click to animate</a>
<div id="element">I'm the animated div</div>


<a href="#" onclick="Spry.Effect.DoFade('element', {toggle:true});">Click to animate</a>
<div id="element">I'm the animated div</div>

And your effects will work as before.

Copyright © 2007. Adobe Systems Incorporated.
All rights reserved.