# ice.js

Ice is a track changes implementation, built in javascript, for anything that is `contenteditable` on the web. Conceived by the CMS Group at The New York Times, ice has been piloting successfully for articles written in the newsroom.

## Demo

[Check it out!](http://NYTimes.github.com/ice/demo/)

## Download

[v0.4.2](http://nytimes.github.com/ice/downloads/ice_0.4.2.zip)

## Features

- Track multi-user inserts and deletes with the option to turn on and off tracking or highlighting.
- A robust API to accept and reject changes, get clean content, and add a lot of configuration.
- Plugins for tinymce and wordpress.
- Optional plugins to track copy-cut-pasting, convert smart quotes, and create em-dashes.

## Get Started

***

**_Contenteditable initialization_** - If you are comfortable with maintaining your own text editing utilities, then you can initialize ice on any block element:
```javascript
     var tracker = new ice.InlineChangeEditor({
       // element to track - ice will make it contenteditable
       element: document.getElementById('mytextelement'),
       // tell ice to setup/handle events on the `element`
       handleEvents: true,
       // set a user object to associate with each change
       currentUser: { id: 1, name: 'Miss T' }
     });
     // setup and start event handling for track changes
     tracker.startTracking();
```
Additional options:
```javascript
     var tracker = new ice.InlineChangeEditor({
       element: document.getElementById('mytextelement'),
       handleEvents: true,
       currentUser: { id: 1, name: 'Miss T' },
       // optional plugins
       plugins: [
         // Add title attributes to changes for hover info
         'IceAddTitlePlugin',
         // Two successively typed dashes get converted into an em-dash
         'IceEmdashPlugin',
         // Track content that is cut and pasted
         {
           name: 'IceCopyPastePlugin',
           settings: {
             // List of tags and attributes to preserve when cleaning a paste
             preserve: 'p,a[href],span[id,class]em,strong'
           }
         }
       ]
     }).startTracking();
```
***

**_Useful utilities in the API:_**

**acceptChange, rejectChange**
```javascript
     // Accept/Reject the change at the current range/cursor position or at the given `optionalNode`
     tracker.acceptChange(optionalNode);
     tracker.rejectChange(optionalNode);
```
**acceptAll, rejectAll**
```javascript
     // Accept/Reject all of the changes in the editable region.
     tracker.acceptAll();
     tracker.rejectAll();
```
**getCleanContent**
```javascript
     // Returns a clean version, without tracking tags, of the content in the editable element or
     // out of the optional `body` param. After cleaning, the `optionalCallback` param is called
     // which should further modify and return the body.
     tracker.getCleanContent(optionalBody, optionalCallback);
```
**setCurrentUser**
```javascript
     // Set the desired user to track. A user object has the following properties: { `id`, `name` }.
     tracker.setCurrentUser({id: 2, name: 'Miss T'});
```
**getChanges**
```javascript
     // Get the internal list of change objects which are modeled from all of the change tracking
     // nodes in the DOM. This might be useful to add a more sophisticated change tracking UI/UX.
     // The list is key'ed with the unique change ids (`cid attribute`) and points to an object
     // with metadata for a change: [changeid] => {`type`, `time`, `userid`, `username`}
     var changes = tracker.getChanges();
```
***

**_Tinymce initialization_** - Add the ice plugin to your tinymce plugins directory and include the following in your tinymce init:
```javascript
      tinymce.init({
        plugins: 'ice',
        theme_advanced_buttons1: 'ice_togglechanges,ice_toggleshowchanges,iceacceptall,icerejectall,iceaccept,icereject',
        ice: {
          user: { name: 'Miss T', id: 1},
          preserveOnPaste: 'p,a[href],i,em,strong',
          // Optional param - defaults to the css found in the plugin directory
          css: 'http://example.com/custom.css'
        },
        ...
      });
```
***

**_Wordpress initialization_**

     In testing - more to come soon.

***

## Limitations/Dependencies

- ice needs to be initialized after the DOM ready event fires.
- ice was originally created for the simple markup behind nytimes.com articles (`p`, `a`, `em`, `strong`). As such, it requires that all text editing takes place in a common root block element, and that there are no other blocks found in the editor. Any type of inline elements are ok, inside of the common root blocks.
- Unfortunately, we haven't been able to test this across all browsers and versions. We know that it tests well in modern Firefox (5+) and Webkit browsers, and "seems to work" in IE7+. We intend to do more testing and get a better idea about what ice can support across browsers.

## License

[GPL 2.0](https://github.com/NYTimes/ice/blob/master/LICENSE)