Development

dgDojoPlugin/DojoEffects

You must first sign up to be able to contribute.

Dojo Effects

Dojo offers various effect interfaces and capabilities that make the library unique. This part of the plugin is aimed at giving a PHP interface to these great effects. The interesting part about Dojo effects is their ability to have callbacks and to be combined and chained with each other. Because of this, the effects have been split into various objects that represent their effect. This chapter outlines these different effect objects and their capabilities.

Dojo Base Effect

The DojoBaseEffect class is the base class for any effects for Dojo that are created. The point is to allow for limiting objects added to the DojoEffectsContainers. This class also houses the various callback functions available for Dojo effects. The available callbacks are:

  • beforeBegin - Called before an animation begins
  • animate - Called on each interval of the animation
  • begin - Called when the animation begins
  • end - Called when the animation ends
  • pause - Called when the animation is paused
  • play - Called when the animation is played
  • stop - Called when the animation is stopped

This class is also responsible for maintaining the array of options. It's only functions are for setting options, so there is no validation at this level. There is also a 'play' function that returns the Javascript to do a Dojo effect but also adds a call to play() to make the effect happen. The play function takes two arguments:

  • Time in seconds to delay starting the animation
  • Boolean to control rewinding animation or going from where left off
<?php
// This won't work because DojoBaseEffect is abstract
$effect = new DojoBaseEffect();
echo $effect->play(2);
?>

Dojo Effect

The DojoEffect class extends DojoBaseEffect and is responsible for maintaining the node for an effect and also houses the default options for any effect. It uses the class method 'additionalOptions' to add additional options that some of the subclasses have. Those extra options are included in the description for their classes. The base options for effects are included below:

  • delay - The time in seconds to wait before starting an animation after it has been played
  • duration - The time in seconds the animation will take to run
  • rate - The time in milliseconds to wait before advancing to the next frame of the animation
  • repeat - How many times to repeat the animation
  • jnode - To interpret the node as Javascript instead of an ID, set this to true
  • easing - A Javascript function that takes a single decimal argument and returns a decimal. There are many functions available and are listed in the DojoEasing class.

The whole point of this class is to just remove some of the burden from the real effects files. This also houses the default constructor for the effect classes. The constructor takes a node ID as the first argument and a set of optional options. The node ID can also be Javascript if you set the option 'jnode' to true.

Examples

<?php
// This doesn't work because DojoEffect is an abstract class, but demonstrates the syntax.
$effect = new DojoEffect('effect_id');
$effec2 = new DojoEffect("dojo.byId('effect_id').parentNode", array('jnode' => true))
?>

Dojo Effects Container

The DojoEffectsContainer extends DojoBaseEffect and is responsible for maintaining the list of effects for the purpose of combination or chaining applications. Because of this, this class only has effect addition and setting capabilities.

Dojo Fade Effect

DojoFadeEffect extends DojoEffect. The only additional method is the 'buildEffect' method that puts together the Javascript to create a Dojo effect. One of the options for this effect is the 'dir' option. This tells the fade effect which way to go, either 'in', the default, or 'out'. Anything else will cause Javascript errors.

Examples

<?php
// Make a fade in effect
$fadeIn = new DojoFadeEffect('effect', array('delay'    => 0.8,
                                             'duration' => 2,
                                             'rate'     => 20,
                                             'repeat'   => 1));
echo dojo_link_to_function('Click Me!', $fadeIn.play());

// Make a fade out effect
$fadeOut = new DojoFadeEffect('effect', array('dir'      => 'out',
                                              'duration' => 2))
echo dojo_link_to_function('Click ME!', $fadeOut.play());
?>

Dojo Cross Fade Effect

The DojoCrossFadeEffect extends DojoEffect and essentially does a fade in and a fade out at the same time but for two different elements. It's constructor is different than the others because it needs two nodes to cross fade. Besides that, it has the same set of options as any other effect.

Examples

<?php
// Let's cross fade my config and locale divs!
$cross = new DojoCrossFadeEffect('config', 'locale', array('duration' => 2));
echo dojo_link_to_function('Cross Me!', $cross->play());
?>

Dojo Wipe Effect

DojoWipeEffect is similar to the DojoFadeEffect in that you control the direction with the 'dir' option. All of the other options are the same.

Examples

<?php
// Make a wipe in effect
$wipeIn = new DojoWipeEffect('effect', array('duration' => 2));
echo dojo_link_to_function('Click Me!', $wipeIn.play());

// Make a wipe out effect
$wipeOut = new DojoWipeEffect('effect', array('dir' => 'out'));
echo dojo_link_to_function('Click Me!', $fadeOut.play());
?>

Dojo Highlight Effect

DojoHighlightEffect is a class for highlighting elements of your page for some amount of time. It has the following options in addition to those for the DojoEffect:

  • color - The color you wish the highlight to be

Examples

<?php
// Make a highlight red effect
$highlight = new DojoHighlightEffect('effect', array('color'    => '#FF0000',
                                                     'duration' => 2));
echo dojo_link_to_function('Click Me to Highlight!', $highlight->play(2));
?>

Dojo Slide To Effect

This effect enables you to slide a div to a particular location based on top and left references. It extends the DojoEffect giving you the following options:

  • left - How far from the left of the screen should the element be placed
  • top - How far from the top should the element be placed

Examples

<?php
$slideTo = new DojoSlideToEffect('effect', array('top'  => 1000, 
                                                 'left' => 30));
echo dojo_link_to_function('Slide Me!', $slideTo->play());
?>

Dojo Slide By Effect

This effect enables you to slide an element by some amount based on top and left references. It extends the DojoEffect giving you the following options:

  • left - How far to move in reference to the current left position
  • top - How far to move in reference to the current top position

Both of those options support negative values, so you can move up, down, left, or right in reference to the top or left. This effect does not currently support being chained or combined on the same element. This means that if you want to move 50 pixels from the top and 50 pixels from the left in the same element, you have to specify both 'left' and 'top' in the same effect instance.

Examples

<?php
$slideBy = new DojoSlideByEffect('effect', array('top'  => 100, 
                                                 'left' => -30));
echo dojo_link_to_function('Slide Me!', $slideBy->play());
?>

Dojo Size To Effect

This effect lets you adjust the height and width of an element either one right after the other or at the same time. To do this, it uses the options from DojoEffect and adds these options:

  • width - Final width of the element after animation
  • height - Final height of the element after animation
  • method - One of chain, one right after the other, or combine, do them together

Examples

<?php
$sizeTo = new DojoSizeToEffect('effect', array('width'  => 500, 
                                               'height' => 500, 
                                               'method' => 'combine'));
echo dojo_link_to_function('Size Me!', $sizeTo->play());
?>

Dojo Smooth Scroll Effect

This effect allows you to scroll an element or a window to show a particular element in the item. It does a nice job of making it look smooth. It extends DojoEffect, so those options are available along with the following ones:

  • win - What element or window to scroll. This defaults to the current window
  • offset - How far to offset from the target node when scrolling
    • x - How far in the 'x' direction to be off
    • y - How far in the 'y' direction to be off

Examples

<?php
// Let's add a scroll to the 'config' element that is FAR down the page
$scroll = new DojoSmoothScrollEffect('config');
echo dojo_link_to_function('Scroll to Config', $scroll->play());
?>

Dojo Wipe To Effect

This effect gives you the ability to have the width or height wiped to a specific amount. You can specify both parameters, but only the width will change because Dojo defaults to using width if both are set. If you need to change both, use DojoSizeToEffect. This class extends DojoEffect and adds the following options:

  • height - The end height for the element
  • width - The end width for the element

Examples

<?php
// Let's make an effect to wipe the width to 500
$wipeToWidth = new DojoWipeToEffect('config', array('width' => 500));
// Let's make another that wipes to a height of 500
$wipeToHeight = new DojoWipeToEffect('config', array('height' => 500));
echo dojo_link_to_function('Wipe Width of Config', $wipeToWidth->play());
echo dojo_link_to_function('Wipe Height of Config', $wipeToHeight->play());
?>

Dojo Animate Effect

This effect is interesting. It gives you the ability to animate any CSS property of an HTML element. Because of this, it handles these additional options:

  • properties - Set of properties to be animated (can be more than one). Each property can either key to a single value representing the end value for the property, or an array of options. These are the available options:
    • start - Start value for the property in the animation
    • end - End value for the property in the animation
    • unit - What the units of the start and end values are

Examples are in order.

Examples

<?php
// Create an animate effect and make it go!
$animate = new DojoAnimateEffect('effect', array('duration'   => 2,
                                                 'properties' => array('width'  => 1,
                                                                       'height' => array('start' => 100,
                                                                                         'end'   => 1,
                                                                                         'unit'  => 'px'))));
echo dojo_link_to_function('Click Me to Animate!', $animate->play());
?>

Dojo Add Class Effect

The DojoAddClassEffect extends DojoEffect and adds the 'class' option for setting what class needs to be added. This class will create Javascript that will attempt to animate the element chosen to add the desired class. It's a little iffy in a chain or combination, but works well enough outside of that.

Examples

Classes are declared in the head.

<style type="text/css">
.fun {
    line-height: 22pt;
    margin-left: 50px;
    font-size: 16pt;
}
</style>
<?php
// Let's add fun to the effect element
$addFun = new DojoAddClassEffect('effect', array('class' => 'fun'));
echo dojo_button_to_function('Add Fun', $addFun->play());
?>

Dojo Remove Class Effect

The DojoRemoveClassEffect extends DojoEffect and adds the 'class' option for setting what class needs to be removed. This class will create Javascript that will attempt to animate the element chosen to remove the desired class. It's a little iffy in a chain or combination, but works well enough outside of that.

Examples

Classes are declared in the head.

<style type="text/css">
.fun {
    line-height: 22pt;
    margin-left: 50px;
    font-size: 16pt;
}
</style>
<?php
// Let's remove fun to the effect element
$removeFun = new DojoRemoveClassEffect('effect', array('class' => 'fun'));
echo dojo_button_to_function('Stop Having Fun', $removeFun->play());
?>

Dojo Toggle Class Effect

This class is kind of neat because it toggles a certain class on an element. Even though this extends DojoEffect it is unable to use all of the available options. Dojo has not yet released a toolkit that enables this animation to have the full set of arguments like 'duration' or 'delay'.

Examples

Assuming the fun class is declared in CSS.

<?php
// Let's toggle the fun on and off
$toggleFun = new DojoToggleClassEffect('changeClass', array('class' => 'fun'));
echo dojo_button_to_function('Toggle Fun', $toggleFun->play());
?>

Dojo Combine Effect

The DojoCombineEffect extends the DojoEffectsContainer and allows you to combine any effect that inherits from the DojoBaseEffect. This allows you to create custom types of animations or to mix existing ones. The constructor for this effect is of variable length so you can just list all of the effects to combine.

Examples

<?php
// Let's combine a fade out and wipe out
$fadeOut = new DojoFadeEffect('effect', array('dir' => 'out'));
$wipeOut = new DojoWipeEffect('effect', array('dir' => 'out'));
$combine = new DojoCombineEffect($fadeOut, $wipeOut);
echo dojo_link_to_function('Watch Me Fade and Wipe Out!', $combine->play());
?>

<?php
// Let's make the div 1 x 1 px and fade at the same time
$animate = new DojoAnimateEffect('effect', array('duration'   => 2,
                                                 'properties' => array('width'  => 1,
                                                                       'height' => array('start' => 100,
                                                                                         'end'   => 1,
                                                                                         'unit'  => 'px'))));
$fadeOut = new DojoFadeEffect('effect', array('dir'      => 'out',
                                              'duration' => 1));
$combine = new DojoCombineEffect($animate, $fadeOut);
echo dojo_link_to_function('Watch Me Shrink and Fade Out!', $combine->play());
>?

Dojo Chain Effect

The DojoChainEffect is another class that extends DojoEffectsContainer. It enables you to chain effects together. As soon as the first effect is done, the next is triggered in succession until all effects have been run. This also allows the user to use a variable number of arguments to describe the effects in the chain.

Examples

<?php
// Let's fade out then fade the div back in and highlight it when done
$fadeIn = new DojoFadeEffect('effect', array('duration' => 2));
$fadeOut = new DojoFadeEffect('effect', array('dir'      => 'out',
                                              'duration' => 1));
$highlight = new DojoHighlightEffect('effect');
$chain = new DojoChainEffect($fadeOut, $fadeIn, $highlight);
echo dojo_link_to_function('Watch Me Chain!', $chain->play());
?>

Combining Chains and Chaining Combines

Yes, you can indeed do this. Currently, there is a known bug in Dojo 1.1.1 where chaining combines causes many Javascript exceptions to be thrown, but the effect still works. If you can switch the logic around and do combinations of chains, the exceptions will go away and you should be able to get the same effect.

The Future

There are some very exciting effects in the works for the Dojo framework. As these new effects become available, they will be added to this plugin as more classes.

Dojo Explode and Converge

This is an interesting effect where the div can be 'blown apart' in some number of rows and columns. The individual blocks fade out as they disperse. The converge effect is just the opposite. Many blocks fade in and come together to form the div.

Dojo Disintegrate and Build

This is where the different blocks 'disintegrate' by falling down, out of the div and fading away. The opposite of this is 'build' which has the pieces come down and fade into place.

Dojo Shear and Unshear

This effect essentially can slide out rows, columns, or both out of the div. The unshear effect does the opposite and brings the pieces in.

Dojo Pinwheel and Unpinwheel

This offers an interesting pinwheel out or pinwheel in effect. Different portions of the div just spin in or out of view.

Dojo Block Fade Out or In

This is where a line moving across the div 'wipes' away the div or brings it back. Very nice looking.