Cht transitions

Template rendering can be performed under control of an asynchronous process implemented by the user in order to animate the visible change in the HTML document.

The transition interface

Animated transitions are callback functions accepting up to three arguments and returning a promise:

function anAnimatedTransition( context, new_content, instance )
{
    var result = new dojo.Deferred();
    // 1. Set up the animation.
    // 2. Ensure that 'new_content' has replaced DOM nodes within 'context' by the time animation completes.
    // 3. Call result.resolve() when animation completes.
    return result;
}

First argument, context, is an object describing the location within DOM where the template expansion should be placed and the (potentially empty) sequence of DOM nodes it will be replacing. Second argument is a detached DOM node or fragment generated by template expansion. Third argument is the template instance object.

The transition is invoked as step 4 of the sequence of actions implemented by the place() method on template instances:

1. Render the template into HTML.
2. Parse resulting DOM to instantiate new widgets.
3. Clean up widgets associated with parts of DOM being replaced.
4. Replace old DOM with new.
5. Start up new widget instances.
   As a result, the place() method does not complete synchronously in presence of an animated transition and the latter is responsible for signaling its completion via the promise object it returns.

Note that in absence of asynchronous/incremental template rendering, the transition does not have to ensure that the new content has indeed replaced the old at the specified location. This requirement becomes more stringent with asynchronous templates because the incremental updates in this and other templates may interfere with the DOM changes asynchronously performed by transition (see the detailed discussion below).

The transition can complete its operation synchronously in which case it should return a non-promise value.

The context object

see The context objects in API: classes and functions