MochiKit Back to docs index

Name

MochiKit.Visual - visual effects

Synopsis

// round the corners of all h1 elements
roundClass("h1", null);

// round the top left corner of the element with the id "title"
roundElement("title", {corners: "tl"});

// Add an fade effect to an element
fade('myelement');

Description

MochiKit.Visual provides visual effects and animations for HTML elements.

Dependencies

Overview

MochiKit.Visual provides different visual effects: rounded corners and animations for your HTML elements. Rounded corners are created completely through CSS manipulations and require no external images or style sheets. This implementation was adapted from Rico. Dynamic effects are ported from Scriptaculous.

Animations & Effects

Dynamic or animated effects are managed by a basic looping service (see Base). The effect looping is controlled by timers that are invoked at regular and short intervals while the effect is executing. The base looping service takes the current system time into consideration, automatically skipping effect steps on execution delays.

The effect classes need only handle dynamic updates based on a floating-point number between 0.0 and 1.0 (the effect position). This effect position may also be manipulated by Transitions to provide non-linear updates, which may further enhance the visual effect.

The effect timer and transitions can be controlled through a set of DefaultOptions that are available for all effect classes.

The Effects Queue

When you create effects based on user input (mouse clicks for example), it can create conflicts between the effects if multiple effects are running at the same time. To manage this problem, the Queue mechanism has been introduced: it's responsible for running the effects as you desired.

By default, you have one Queue called 'global', and the effects run in 'parallel' (see DefaultOptions). Every effect has a queue option to customize this. Its value can be a string, thereby using the global scope:

  • front: the effect will be run before any other non-started effect;
  • end: the effect will be run when all other effects have finished;
  • break: every other effect is immediately finalized when the the effect start;
  • parallel: the effect runs in parallel with other effects.

But you have even more control if you use an object with the following property keys:

  • position takes one of the values listed above;
  • scope contains the queue name. If it's "global" the effect will use the default queue, otherwise you can define your own queue name. For example, if you add an effect on a specified element, you may use the element id as scope;
  • limit defines how many effects can be stored in the queue at a single time. If an effect is added when the limit has been reached, it will never be run (it's lost).

API Reference

Functions

roundClass(tagName[, className[, options]]):

Rounds all of the elements that match the tagName and className specifiers, using the options provided. tagName or className can be null to match all tags or classes. Regarding the options, see the roundElement function.

Availability:
Available in MochiKit 1.3.1+

roundElement(element[, options]):

Immediately round the corners of the specified element.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The options mapping has the following defaults:

corners "all"
color "fromElement"
bgColor "fromParent"
blend true
border false
compact false

The options parameters can have following values:

corners:

Specifies which corners of the element should be rounded. Choices are:

  • all
  • top
  • bottom
  • tl (top left)
  • bl (bottom left)
  • tr (top right)
  • br (bottom right)
Example:
"tl br": top-left and bottom-right corners are rounded
blend:
Specifies whether the color and background color should be blended together to produce the border color.
Availability:
Available in MochiKit 1.3.1+

toggle(element[, effect[, options]]):

Toggle an element between visible and invisible state using an effect.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
effect:

One of the visual pairs to use:

"appear" appear and fade
"blind" blindUp and blindDown
"size" grow and shrink
"slide" slideUp and slideDown
options:
The optional effect options (see the respective effect functions for details).
Availability:
Available in MochiKit 1.4+

tagifyText(element[, tagifyStyle]):

Transform the node text into SPAN nodes each containing a single letter. Only text nodes that are immediate children will be modified by this function.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
tagifyStyle:
Style to apply to each new SPAN node, defaults to 'position: relative'.
Availability:
Available in MochiKit 1.4+

multiple(elements, effect[, options]):

Launch the same effect on a list of elements.

elements:
A list of element ID strings or a DOM nodes (see MochiKit.DOM.getElement).
effect:
An effect class constructor function.
options:

The effect options (see the respective effect class). A special speed value will be added to the effect delay for each additional element in the list. This cause the effects to not run exactly in parallel by default.

speed 0.1
delay 0.0 (initial)
Availability:
Available in MochiKit 1.4+

Combination Effects

fade(element[, options]):

Fades an element using the Opacity effect. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element opacity will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
from element.opacity || 1.0
to 0.0
Availability:
Available in MochiKit 1.4+

appear(element [, options]):

Slowly shows an element using the Opacity effect. If the element has "display: none" style, it will be changed to "display: block" with MochiKit.Style.showElement.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
from element.opacity || 0.0
to 1.0
Availability:
Available in MochiKit 1.4+

puff(element [, options]):

Make an element double size while also fading it using the Scale and Opacity effects in parallel. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element size, position and opacity will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

blindUp(element [, options]):

Blind an element up, changing its vertical size to 0 using the Scale effect. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element size will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

blindDown(element [, options]):

Blind an element down, restoring its vertical size using the Scale effect. If the element has "display: none" style, it will be changed to "display: block" with MochiKit.Style.showElement.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

switchOff(element [, options]):

A switch-off like effect, making the element disappear, using the Opacity and Scale effects in sequence. The initial Opacity effect uses a flicker (partially random) transformation. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element opacity, size and position will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions. Note that the options will only affect the secondary Scale effect.
Availability:
Available in MochiKit 1.4+

dropOut(element [, options]):

Make the element fall and fade using the Move and Opacity effects in parallel. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element position and opacity will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The distance option controls the number of pixels that the element will move downwards. See also the DefaultOptions.

distance 100
Availability:
Available in MochiKit 1.4+

shake(element [, options]):

Shake an element from left to right using a sequence of six Move effects. Once the effect has completed, the original element position will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions. Note that the options will only affect the last Move effect.
Availability:
Available in MochiKit 1.4+

slideDown(element [, options]):

Slide an element down using the Scale effect. The element must have a fixed height and contain a single child. If the element has "display: none" style it will be changed to "display: block" with MochiKit.Style.showElement.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

slideUp(element [, options]):

Slide an element up using the Scale effect. The element must have a fixed height and contain a single child. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element size will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

squish(element [, options]):

Reduce the horizontal and vertical sizes at the same time using a single Scale effect. The result is similar to the shrink effect with a top-left value for the direction option. The element should have fixed width and height. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original element size will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

grow(element [, options]):

Grows an element size using Scale, Move and Opacity effects in parallel. The element should have fixed width, height and top-left position. Before the effect starts, the element will be shown with MochiKit.Style.showElement and the size and position values will be read.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The following options and default values control this effect. Note that the Opacity effect is turned off by default. See also the DefaultOptions.

direction "center"
moveTransition MochiKit.Visual.Transitions.sinoidal
scaleTransition MochiKit.Visual.Transitions.sinoidal
opacityTransition MochiKit.Visual.Transitions.full

The direction option controls the origin point of the effect. The following values are allowed:

"center" Grows from the center
"top-left" Grows from the top left corner
"top-right" Grows from the top right corner
"bottom-left" Grows from the bottom left corner
"bottom-right" Grows from the bottom right corner
Availability:
Available in MochiKit 1.4+

shrink(element [, options]):

Shrinks an element using Scale, Move and Opacity effects in parallel. The element should have fixed width, height and top-left position. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original size and position will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The following options and default values control this effect. Note that the Opacity effect is turned off by default. See also the DefaultOptions.

direction "center"
moveTransition MochiKit.Visual.Transitions.sinoidal
scaleTransition MochiKit.Visual.Transitions.sinoidal
opacityTransition MochiKit.Visual.Transitions.full

The direction option controls the destination point of the effect. The following values are allowed:

"center" Grows from the center
"top-left" Grows from the top left corner
"top-right" Grows from the top right corner
"bottom-left" Grows from the bottom left corner
"bottom-right" Grows from the bottom right corner
Availability:
Available in MochiKit 1.4+

pulsate(element [, options]):

Switches the element visibility using a pulsating Opacity effect. The effect both starts and ends with a 0 opacity value.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The pulses option controls the number of pulses made during the effect. See also the DefaultOptions.

pulses 5
Availability:
Available in MochiKit 1.4+

fold(element [, options]):

Reduce first the element vertical size, and then the horizontal size using two Scale effects in sequence. The element should have both fixed width and height. Once the effect has completed, the element will be hidden with MochiKit.Style.hideElement and the original size and position will be restored.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions. Note that the options will only affect the first Scale effect.
Availability:
Available in MochiKit 1.4+

Basic Effects Classes & Constants

Transitions:

Default transition functions available for all effects. A transition function adjusts the current position value between 0 and 1 in order to achieve a non-linear sequence of position values for the effect.

linear A straight linear transition.
sinoidal A smooth sine value transition.
reverse A reverse linear transition.
flicker A sine transition with random additions.
wobble A multi-period sine curve transition with 4.5 wobbles and ending with one (1).
pulse A multi-period triangle curve transition with 5 pulses (by default) and ending with zero (0).
parabolic A smooth parabolic transition.
none A fixed zero (0) value transition.
full A fixed one (1) value transition.
Availability:
Available in MochiKit 1.4+

DefaultOptions:

Default options for all effects. Note that all effects inherit the Base class and thereby also support a number of events that can be specified as callback functions among the effect options.

transition MochiKit.Visual.Transitions.sinoidal
duration 1.0 (seconds)
fps 25.0
sync false (only set for Parallel or Sequence effects)
from 0.0
to 1.0
delay 0.0
queue 'parallel'
Availability:
Available in MochiKit 1.4+

Base():

Base class to all effects. Define a basic looping service, use it for creating new effects.

You can override the methods setup, update and finish.

The class defines a number of events that will be called during effect life. The events are:

  • beforeStart
  • beforeSetup
  • beforeUpdate
  • afterUpdate
  • beforeFinish
  • afterFinish

If you want to define your own callbacks, define it in the options parameter of the effect. Example:

// I slide it up and then down again
slideUp('myelement', {afterFinish: function () {
    slideDown('myelement');
});

Specific internal events are also available: for each one listed above, the same exists with an 'Internal' postfix (e.g. 'beforeStartInternal'). Their purpose is mainly for creating your own effect and keep the user access to event callbacks (not overriding the library ones).

Availability:
Available in MochiKit 1.4+

Parallel(effects [, options]):

Launch a list of effects in parallel.

effects:
An array of instantiated effect objects. Note that they must all have sync set to true.
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

Sequence(effects [, options]):

Launch a list of effects in sequence, one after the other.

effects:
An array of instantiated effect objects. Note that they must all have sync set to true.
options:

See DefaultOptions. Note that the default value for some options is different and that some of the transition and timing options don't make sense to override.

transition MochiKit.Visual.Transitions.linear
duration Sum of the duration for all effects.
from Only 0.0 makes sense.
to Only 1.0 makes sense.
Availability:
Available in MochiKit 1.4+

Opacity(element [, options]):

Change the opacity of an element progressively.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The following options and default values control this effect. See also the DefaultOptions.

from 0.0
to 1.0
Availability:
Available in MochiKit 1.4+

Move(element [, options]):

Changes the (top left) position of an element in small steps, creating a moving effect.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The following options and default values control this effect. See also the DefaultOptions.

x 0
y 0
mode 'relative'

The mode option controls if the specified x and y coordinates are relative or absolute with respect to the current element position.

Availability:
Available in MochiKit 1.4+

Scale(element, percent [, options]):

Changes the size of an element.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
percent:
Final wanted size in percent of current size. The size will be reduced if the value is between 0 and 100, and raised if the value is above 100.
options:

The following options and default values control this effect. See also the DefaultOptions.

scaleX true
scaleY true
scaleContent true
scaleFromCenter false
scaleMode "box"
scaleFrom 100.0
scaleTo percent

The scaleContent option controls if the element font-size should also be scaled along with the size. The scaleFromCenter option allows continual adjustment of the element top left position to keep the element centered during the size change. The scaleMode option is used to determine the original element size. It can have one of the following values:

"box" Uses offsetHeight and offsetWidth
"contents" Uses scrollHeight and scrollWidth
{...} Uses originalHeight and originalWidth from the specified object
Availability:
Available in MochiKit 1.4+

Highlight(element [, options]):

Highlights an element by flashing the background color. The color is first set to the startcolor and is then slowly morphed into the endcolor, normally the original background color of the element.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:

The following options and default values control this effect. See also the DefaultOptions.

startcolor '#ffff99'
endcolor element.style.backgroundColor
Availability:
Available in MochiKit 1.4+

ScrollTo(element [, options]):

Scroll the window to the position of the given element. Note that this effect only scrolls the top window and not any parent elements with scrollbars due to "overflow: auto" style.

element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

Morph(element [, options]):

Make a transformation to the given element. It's called with the option style with an array holding the styles to change. It works with properties for size (font-size, border-width, ...) and properties for color (color, background-color, ...).

For size, it's better to have defined the original style. You must use the same unit in the call to Morph (no translation exists between two different units).

Parsed length are postfixed with: em, ex, px, in, cm, mm, pt, pc.

Example:

<div id="foo" style="font-size: 1em">MyDiv</div>
...
Morph("foo", {"style": {"font-size": "2em"}});
element:
An element ID string or a DOM node (see MochiKit.DOM.getElement).
options:
See DefaultOptions.
Availability:
Available in MochiKit 1.4+

Authors

Copyright

Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is dual-licensed free software; you can redistribute it and/or modify it under the terms of the MIT License or the Academic Free License v2.1.

Portions adapted from Rico are available under the terms of the Apache License, Version 2.0.

Portions adapted from Scriptaculous are available under the terms of the MIT License.