Backbone.Undo.js/README.md

Backbone.Undo.js
================

An extremely simple undo manager for Backbone.js

#### Advantages of Backbone.Undo.js

* 	**The Drop-In Manager**

	In comparison to undo managers that implement the memento pattern you don't have to modify your models and collections to use Backbone.Undo.js. Just drop in Backbone.Undo.js and register the objects whose actions you want to undo. That way it's not only easy to include Backbone.Undo.js, but also to exclude it in case you don't want to use it any longer at some point.

*	**Ready To Go: Based on Backbone-Events**

	You don't have to manually call methods to `store()` or `restore()` certain states. To detect an undoable action, Backbone.Undo.js listens to the events Backbone triggeres automatically. You don't have to do anything.

* 	**Magic Condensation**

	In a more complex web application the click of a button might trigger several changes which dispatch several events which in Backbone.Undo.js are turned into several undoable actions. If the user wants to undo what he caused with his click he wants to undo all of those actions. Backbone.Undo.js has an internal feature called *Magic Condensation* that detects actions that were created in one flow and undoes or redoes all of them.

#### Who should use Backbone.Undo.js

Backbone.Undo.js is a simple undo manager that should be used by rather simple web applications. It has mechanisms that makes it extensible and suitable for more complex applications. However, it might not be adequate for very large-scale applications with tens of thousands of lines of code.

## Getting started

Backbone.Undo.js depends on Backbone.js which depends on Underscore.js (or Lo-Dash.js). Make sure to include these two files before you include Backbone.Undo.js:

    <script src="underscore.js"></script>
    <script src="backbone.js"></script>
    <!-- Backbone.Undo.js is included *after* Backbone and Underscore -->
    <script src="Backbone.Undo.js"></script>


#### Backbone Version

Backbone.Undo.js was developed for Backbone 1.0.0 or higher.

#### Underscore Version

Backbone.Undo.js was developed for Underscore 1.4.4 or higher.

## Setting up your UndoManager

In order to set up your UndoManager you have to do the following steps:

1. __Instantiate__ your UndoManager

        var myUndoManager = new Backbone.UndoManager();

2. __Register__ the models and collections you want to observe

        var model = new Backbone.Model,
        collection = new Backbone.Collection;
        myUndoManager.register(model, collection); // You can pass several objects as arguments
        // You can prepare your objects here. Changes won't be tracked yet.
        model.set("foo", "bar");
        collection.add([{"something": "blue"}]);
        // These changes can't be undone.

3. __Start tracking__ the changes

        myUndoManager.startTracking(); // Every change that happens to the model and the collection can now be undone

__Shorthand__: If you already have the objects you want to observe at hand when you instantiate the undo manager or if you don't need to prepare them you can pass them on instantiation:

    // Shorthand
    var myUndoManager = new Backbone.UndoManager({
    	track: true, // changes will be tracked right away
    	register: [model, collection] // pass an object or an array of objects
    })


## Backbone.Undo.js methods

Methods you can call on an instance of `Backbone.UndoManager`:

#### Constructor 	`new Backbone.UndoManager([object])`

The constructor can be called with an object of attributes as an optional argument. Each attribute is optional and has a default value.

    var undoManager = new Backbone.UndoManager; // possible, because the argument is optional
    var undoManager = new Backbone.UndoManager({
        maximumStackLength: 30, // default: Infinity; Maximum number of undoable actions
        track: true, // default: false; If true, changes will be tracked right away
        register: myObj // default: undefined; Pass the object or an array of objects that you want to observe
    });

#### register		`undoManager.register(obj, [obj, ...])`

Your undo manager must know the objects whose actions should be undoable/redoable. Therefore you have to register these
objects:

    var model = new Backbone.Model;
    var collection = new Backbone.Collection;
    undoManager.register(model, collection);

The register-method doesn't check whether the object is an instance of Backbone.Model or Backbone.Collection. That makes
it possible to bind other objects as well. However, make sure they have an `on()` and an `off()` method and trigger an `"all"` event in the fashion of Backbone's `"all"` event.

#### unregister		`undoManager.unregister(obj, [obj, …])`

Previously registered objects can be unregistered using the `unregister()` method. Changes to those objects can't be
undone after they have been unregistered.

    var myModel = new Backbone.Model;
    undoManager.register(myModel);
    undoManager.startTracking();
    myModel.set("foo", "bar"); // Can be undone
    undoManager.unregister(myModel);
    myModel.set("foo", "baz"); // Can't be undone

#### unregisterAll      `undoManager.unregisterAll()`

Unregister all objects that have been registered at this undoManager so far.

#### startTracking 	`undoManager.startTracking()`

Changes must be tracked in order to create UndoActions. You can either set `{track: true}` on instantiation or call `startTracking()` later.

    var myModel = new Backbone.Model;
    undoManager.register(myModel);
    myModel.set("foo", "bar"); // Can't be undone because tracking didn't start yet
    undoManager.startTracking();
    myModel.set("foo", "baz"); // Can be undone

#### stopTracking	`undoManager.stopTracking();`
    
If you want to stop tracking changes for whatever reason, you can do that by calling `stopTracking()`.

    myModel.set("foo", 1);
    undoManager.startTracking();
    myModel.set("foo", 2);
    undoManager.stopTracking();
    myModel.set("foo", 3);
    undoManager.undo(); // "foo" is 1 instead of 2, because the last change wasn't tracked

#### undo		`undoManager.undo([magic]);`
    
The method to undo the last action is `undo()`.

        myModel.get("foo"); // => 1
        
        myModel.set("foo", 2);
        undoManager.undo();
        
        myModel.get("foo"); // => 1

Pass `true` to activate *Magic Condensation*. That way you undo the complete last set of actions that happened at once.

#### redo		`undoManager.redo([magic])`
    
The method to redo the latest undone action is `redo()`.

        myModel.set("foo", 2);
        
        undoManager.undo();
        myModel.get("foo"); // => 1
        
        undoManager.redo();
        myModel.get("foo"); // => 2

Like with `undo()` you can pass `true` to activate *Magic Condensation* and to redo the complete last set of actions that were undone.

#### isAvailable        `undoManager.isAvailable(type)`

This method checks if there's an UndoAction in the stack that can be undone / redone. Pass `"undo"` or `"redo"` as the argument.

        undoManager.isAvailable("undo") // => true; You can undo actions

If you use undo- and redo-buttons in your gui this method is helpful for determining whether to display them in an enabled or disabled state.

#### merge              `undoManager.merge(otherManager1, [otherManager2, …])`

This is a feature for the advanced use of Backbone.Undo.js. Using the UndoTypes-API (see below) for specific instances of `Backbone.UndoManager` you can create undo managers with special behavior for special cases. But as having several undo managers side by side doesn't make any sense you need a way to combine them. That's what `merge` is for.

The method `merge` sets the stack-reference of other undo managers to its stack.

        var mainUndoManager = new Backbone.UndoManager,
        specialUndoManager = new Backbone.UndoManager;
        
        // Implementing special behavior
        specialUndoManager.addUndoType(…)
        
        // Making both write on one stack
        mainUndoManager.merge(specialUndoManager);
        
        mainUndoManager.stack === specialUndoManager.stack // => true

You can pass one or more undo managers or an array with one or more undo managers when calling this function.

#### addUndoType        `undoManager.addUndoType(type, fns)`

This adds an UndoType that only works for this specific undo manager and won't affect other instances of Backbone.UndoManager. See the UndoTypes-API for a more thorough documentation on this function.

#### changeUndoType     `undoManager.changeUndoType(type, fns)`

This changes an UndoType only on this specific undo manager and won't affect other instances of Backbone.UndoManager. See the UndoTypes-API for a more thorough documentation on this function.

#### removeUndoType     `undoManager.removeUndoType(type)`

This removes an UndoType only from from this specific undo manager. See the UndoTypes-API for a more thorough documentation on this function.

***

Methods you can call on the object `Backbone.UndoManager`:

#### defaults 		`Backbone.UndoManager.defaults(obj)`

Extend or overwrite the default values of an undo manager.

	Backbone.UndoManager.defaults({
		track: true
	});
	
	var undoManager = new Backbone.UndoManager; // tracking has now already started
	
#### addUndoType        `Backbone.UndoManager.addUndoType(type, fns)`

This adds an UndoType that works for all undo managers whether they've already been instantiated or not. See the UndoTypes-API for a more thorough documentation on this function.

#### changeUndoType     `Backbone.UndoManager.changeUndoType(type, fns)`

This changes an UndoType for all undo managers whether they've already been instantiated or not. See the UndoTypes-API for a more thorough documentation on this function.

#### removeUndoType     `Backbone.UndoManager.removeUndoType(type)`

This removes an UndoType from all undo managers whether they've already been instantiated or not. See the UndoTypes-API for a more thorough documentation on this function.


## Supported Events

Backbone.Undo.js uses Backbone's events to generate UndoActions. It has built-in support for the following events

*   `add` When a model is added to a collection
*   `remove` When a model is removed from a collection
*   `reset` When a collection is reset and all models are replaced by new models (or no models) at once
*   `change` When a model's attribute is changed or set

### Supporting other events and modifying built-in behavior

Backbone.Undo.js has an API to extend and modify the generation of UndoActions. In order to use the API it's important to understand the concept of creating UndoActions:

#### UndoTypes

Backbone.Undo.js retrieves the data of the undoable states from the events Backbone triggers and their arguments. However, different events have different arguments and thus need different approaches in retrieving the necessary data. Additionally, different types of actions require different behavior to undo and redo them.
That's what the *UndoTypes* are for. An *UndoType* is an object of functions for a specific type of event. The functions retrieve the data necessary to create an UndoAction and are able to undo an action of this type and redo it.

An *UndoType* needs to have the following functions:

*   **on**	`([…])`
    This function is called when the event this UndoType is made for was triggered on an observed object. It gets all the arguments that were triggered with the event. The `"on"`-function must return an object with the properties `object`, `before`, `after` and optionally `options`.

		return {
		    "object": … // The object the event was triggered on
		    "before": … // The object's state before the concerning action occured
		    "after": … // The object's current state, after the concerning action occured
		    "options": … // Optionally: Some 'options'-object
		}

*   **undo**	`(obj, before, after, options)`
    The `undo` function is called when the action this UndoType is made for should be undone. The data returned by the `"on"` function is passed to `"undo"` as arguments:
	*  `obj` is the model, collection or other kind of object that should be acted on
	*  `before` is the the data before the action occured and defines the state that should be created within this function
	*  `after` is the data after the action had occured and represents obj's current state
	*  `options` are the options the `on` function returned
*   **redo**	`(obj, before, after, options)`
    The `redo` function is called when the action this UndoType is made for should be redone. As with `"undo"` the data returned by the `"on"` function is passed to `"redo"` as arguments
	*  `obj` is the model, collection or other kind of object that should be acted on
	*  `before` is the the data before the action occured and represents the current state as the action was previously undone
	*  `after` is the data after the action had occured and is the state wich should be recreated
	*  `options` are the options the `"on"` function returned

It can have an optional property:

*   **condition**	`([…])`
    `"condition"` can be a function or a boolean value that defines whether an UndoAction should be created or not. If it's false or if it returns false `"on"` won't be called and no UndoAction is created. If it's not set, condition is always `true`.

##### UndoType example

This is an example of an UndoType for the `"reset"` event.

	{
	    "reset": {
	    	"condition": true, // This isn't necessary as condition is true by default
	    	"on": function (collection, options) {
	    		// The 'on'-method gets the same arguments a listener for the
	    		// Backbone 'reset'-event would get: collection.on("reset", listener)
	    		
	    		// The 'on'-method has to return an object with the properties
	    		// 'object', 'before', 'after' and optionally 'options'
	    		return {
	    		    object: collection,
	    		    before: options.previousModels,
	    		    after: _.clone(collection.models)
	    		}
	    	},
	    	"undo": function (collection, before, after) {
	    		// To restore the previous state we just reset the collection
	    		// with the previous models
	    		collection.reset(before);
	    	}
	    	"redo": function (collection, before, after) {
	    		// To restore the subsequent state we reset the collection to
	    		// the 'after'-array of models
	    		collection.reset(after);
	    	}
	    }
	}

#### UndoTypes API

To create your own UndoTypes for custom events or for extending the support of Backbone-events or if you just want to modify the built-in behavior, you can either do that on a global level to affect all current and future instances of Backbone.UndoManager or do that per instance to change only a specific undo manager.

Either way you have three methods to extend or change the UndoTypes. Below the functions for global changes are presented:

#### addUndoType

	Backbone.Undo.addUndoType(type, callbacks);
	// or
	Backbone.Undo.addUndoType(types);

With the `addUndoType()` method you can add or overwrite one or more UndoTypes. You can call it with the two arguments `type` and `callbacks` or with an object in which all keys are `type`s and their values `callbacks` to perform a bulk action.

* `type` The name of the event this UndoType is made for. In terms of Backbone events: `"add"`, `"remove"`, `"reset"`, `"change"`, etc.
* `callbacks` An object with the funcitions `"on"`, `"undo"`, `"redo"` and optionally `"condition"`
    
*Example*: If we want to overwrite the UndoType `"reset"` with the functions defined in the example above we can do the following:

    Backbone.Undo.addUndoType("reset", {
        "on": function (collection, options) {
            …
        },
        "undo": function (collection, before, after) {
            …
        },
        "redo": function (collection, before, after) {
            …
         }
    });
    
You can also define several UndoTypes at once by passing an object to `addUndoType`

	Backbone.Undo.addUndoType({
		"reset": {
		   "on": …
		   "undo": …
		   "redo": …
		},
		"add": {
		   "on": …
		   "undo": …
		   "redo": …
		},
		"customevent": {
		   "on": …
		   "undo": …
		   "redo": …
		}
	});

#### changeUndoType

	Backbone.Undo.changeUndoType(type, callbacks);
	// or
	Backbone.Undo.changeUndoType(types);

If you want to change just one or more functions of an already added or built-in UndoType `changeUndoType` is the way to go. It works just like `addUndoType` with the difference that there must already be an UndoType for the specified `type` and you don't have to pass all `callbacks` functions.

	Backbone.Undo.changeUndoType("reset", {
	    "condition": …
	})

Pass an object to perform a bulk action:

	Backbone.Undo.changeUndoType({
	    "reset": {
	        "condition": …
	    },
	    "add": {
	        "on": …
	        "undo": …
	    },
	    "customevent": {
	        "redo": …
	    }
	})

#### removeUndoType

	Backbone.Undo.removeUndoType(type);
	// or
	Backbone.Undo.removeUndoType(types);

Call `removeUndoType` to remove an existing UndoType. Pass the type of the UndoType you want to remove as the argument or pass an array of types if you want to remove several at once.

	Backbone.Undo.removeUndoType("reset");
	
Pass an array to perform a bulk action:

	Backbone.Undo.removeUndoType(["reset", "add", "customevent"]);
	
If you just want to suspend an UndoType for a limited amount of time, making use of the `"condition"` property might be more adequate:

	Backbone.Undo.changeUndoType("reset", {"condition": false});

#### Using the UndoTypes API per instance

As stated above you can also add, change and remove UndoTypes for a specific instance of Backbone.Undo without affecting other instances. The methods and arguments are exactly the same.

	var undoManager = new Backbone.UndoManager;
	
	undoManager.addUndoType("reset", {
	    "on": …
	    "undo": …
	    "redo": …
	})
	
	undoManager.changeUndoType("reset", {
	    "undo": …
	})
	
	undoManager.removeUndoType("reset");
	
Please note that removing an UndoType on a per instance level just causes a fallback to the global UndoTypes and won't take away the support for this type. You have to overwrite the type with an UndoType of empty functions to accomplish that.

## License (MIT License)

Copyright (c) 2013 Oliver Sartun

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.