first commit

2026-06-17 06:11:37 +00:00 · 2017-04-15 01:34:36 +03:00
commit c715e2a604
5325 changed files with 329700 additions and 0 deletions
@@ -0,0 +1,128 @@
+# 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)