YUI3 Undo Framework, ver. 1.01

The current version is using YUI 3.1.1. If you are looking for an older version, cilck here.

Introduction

YUI3 Undo Framework allows adding undo/redo functionality to an application.
It consists of two classes:

UndoManager manages a list of UndoableAction-s. In addition to standard undo/redo functionality, YUI3 Undo Framework supports asynchronous actions too. An asynchronous action must fire undoFinished event in order to notify that its undo/redo process has been completed.

Using the module

1. Instantiating UndoManager

In order to implement undo/redo functionality to your application, the first thing you have to do is to include the module in your YUI3 instance.
Next, you must instantiate UndoManager. You may limit the number of actions, which can be added to the list with actions, by setting limit property. By default, the number of actions is 0 (unlimited).

                YUI().use( 'gallery-undo', function( Y ){
                    var undoManager = new Y.UndoManager();
                });

2. Adding UndoableAction

Once you have instantiated UndoManager, you have to add one or more UndoableAction-s. The UndoableAction represents an action in your application. What kind of action is it, is up to the developer. That could be typing a character in a text document, drag&drop action, moving map, etc. Once you instantiate an UndoableAction, you must add it to UndoManager.

There are a few functions the developer may want to override:

undo - undoes the action
redo - redoes the action
merge - merges the action with another one
cancel - cancels the action

The implementation of these functions is up to the developer and the application.

Usually, the developer will extend Y.UndoableAction, implement undo, redo, merge and cancel methods and add it to UndoManager:

                function MyAction(config){
                    MyAction.superclass.constructor.apply( this, arguments );
                }

                MyAction.NAME = "MyAction";

                MyAction.ATTRS = {
                    ...
                };

                Y.extend( MyAction, Y.UndoableAction, {

                    initializer : function( config ){
                        ...
                    },

                    undo : function(){
                        ...
                    },

                    redo : function() {
                        ...
                    },

                    merge : function( newAction ) {
                        ...
                    },

                    cancel : function() {
                        ...
                    }
                } );

                Y.MyAction = MyAction;

                var myAction = new Y.MyAction({
                    label: "My undoable action"
                });

                undoManager.add( myAction );

3. Asynchronous actions

Sometimes it is not known when an action finishes its job. For example, it may send XMLHttpRequest (XHR) to the server, or doing its job after some timeout by using setTimeout method. In this case, the developer should flag it as an asynchronous action - by setting asyncProcessing property to true.

In the process of undoing/redoing actions, UndoManager will check if the current action is asynchronous. If yes, it will invoke its undo/redo methods and wait until action fires undoFinished or redoFinished events.

                Y.extend( MyAction, Y.UndoableAction, {
                    undo : function(){
                        // doing something asynchronous
                        this.fire( "undoFinished" );
                    },

                    redo : function() {
                        // doing something asynchronous
                        this.fire( "redoFinished" );
                    }
                });

                var myAction = new Y.MyAction({
                    label: "My asynchronous undoable action",
                    asyncProcessing: true
                });

4. Working with UndoManager

UndoManager provides three functions in order to undo/redo actions:

undo - undoes the action before current index by calling its undo method.
redo - redoes the action at current index by calling its redo method.
processTo - undoes or redoes actions while reaching the action index, passed as parameter.

           undoManager.undo();
           ...
           undoManager.redo();
           ...
           undoManager.processTo(3);

UndoManager provides convenient functions in order to check is undo or redo possible in some moment. These are:

5. Events

Both UndoManager and UndoableAction provide a few events. UndoableAction provides these events:

In case of asynchronous action, UndoManager will listen to both of these events - undoFinished and redoFinished events.

UndoManager fires the same events (and more) but with slightly different meaning. Undo/Redo process may include more than one action - this depends on actions implementation or the developer may have invoked processTo method. UndoManager fires the following events:

actionAdded - fires when an action has been added to UndoManager.
beforeCanceling - canceling may happen if we have undone some actions and we add another one to the list. UndoManager will purge all actions after the current one until the end of the list. Also, if there is a limited number of actions, on each add UndoManager will discard as many actions, as needed in order to free place for the new one.
actionCanceled - fires when UndoManager cancels an action.
cancelingFinished - fires when canceling process finishes.
beforeUndo - fires before the start of undo process. More than one action may be undone during this process.
actionUndone - fires when an action finishes its undo regardless is it asynchronous or not.
undoFinished - fires when undo process completes.
beforeRedo - fires before the start of redo process. More than one action may be redone during this process.
redoFinished - fires when redo process completes.