Skip to content

Latest commit

 

History

History
146 lines (116 loc) · 7.54 KB

README.md

File metadata and controls

146 lines (116 loc) · 7.54 KB
Raw

Track Changes Plugin for CKEditor

  • Track changes plugin for CKEditor, based on ICE (NYTimes track changes for contentEditable documents).

Main Features

  • Enable / disable track changes mode
  • Show / hide tracked changes
  • Accept/Reject all/some changes
  • Accept/Reject a single change
  • Display customizable tooltips for each change

##Demo

Demo Page

##Site LoopIndex

##Getting Started

  • Add the lite plugin to ckeditor. The simplest way to do this is by adding the following line to ckeditor's config.js:
	config.extraPlugins = 'lite';
  • Optionally include lite-interface.js in your source, so you can use the various constants defined in it rather than string literals.
	<script type="text/javascript" src="ckeditor/plugins/lite/lite-interface.js"></script>

##Configuration The LITE plugin is automatically activated after you install it and edit config.js as described above. For the full details of tweaking the loading process, toolbar commands, users and more, see the documentation.

API

  • Get a reference to the lite plugin

    To interact with the lite plugin, either access it through the editor's plugins.lite property, or listen to the event LITE.Events.INIT fired by the editor instance. The data member of the event will contain a property called lite which references the lite plugin instance, initialized and ready for action.

  • toggleTracking(bTrack, bNotify)

    Toggles change tracking in the editor.

    Parameters

    • bTrack - boolean. If undefined, change tracking is toggled, otherwise it is set to this value
    • bNotify - boolean. If false, the LITE.Events.TRACKING event is not fired.

  • toggleShow(bShow, bNotify)

    Change the visibility of tracked changes. Visible changes are marked by a special style, otherwise insertions appear in their original format and deletions are hidden.

    Parameters

    • bShow - boolean. If undefined, change visibility is toggled, otherwise it is set to this value
    • bNotify - boolean. If false, the LITE.Events.SHOW_HIDE event is not fired.

  • acceptAll(options)

    Accept some or all the pending changes.

    Parameters

    • options - optional object filter the changes to which this operation applies with the following properties:
      • exclude
        an array of user ids to exclude from the the operation (takes precedence over include)
      • include
        an array of user ids to include from the the operation
      • filter
        a filter function that accepts an object of the form {userid, time, data} and returns a boolean. Only changes for which the filter returns true are included in the operation. The filter option can work with both exclude and include.
      All the fields you include in the options block, including custom ones, are preserved when it is sent back in the ACCEPT or REJECT events (see below).

    • rejectAll(options)

      Reject all the pending changes.

      Parameters

      • options - optional object to filter the changes to which this operation applies. See the acceptAll method for details.

    • countChanges(options)

      Returns a count of the tracked changes in the editor.

      Parameters

      • options - optional object to filter the counted changes. See the acceptAll method for details.

    • hasChanges()

      Sets the name and id of the current user. Each tracked change is associated with a user id.

      Parameters

      • none

    • setUserInfo(info)

      Sets the name and id of the current user. Each tracked change is associated with a user id.

      Parameters

      • info - An object with two members - id and name

    • setChangeData(data)

      Associates an arbitrary string with the changes made from now on. This string is passed to the optional filter function in options block passed to various methods that accept change filtering. For example, you may associate a revision number with the current change set and later on filter changes according to their revision.

      Parameters

      • data - Arbitrary data (converted to a string by the LITE plugin).

    Events

    The LITE plugin events are listed in lite-interface.js under LITE.Events. The following events are fired by the LITE plugin instance through its instance of ckeditor, with the parameter in the data member of the event info:

    • INIT (parameters: lite, the LITE instance)
      Fired each time LITE creates and initializes an instance of the ICE change tracker. This happens, e.g., when you switch back from Source mode to Wysiwyg.
    • ACCEPT(parameter : the options object passed to acceptAll, if relevant)
      Fired after some changes (possibly all) were accepted.
    • REJECT (parameter : the options object passed to acceptAll, if relevant)
      Fired after some changes (possibly all) were rejected.
    • SHOW_HIDE(parameter: show <boolean>)
      Fired after a change in the visibility of tracked changes.
    • TRACKING (parameter: tracking<boolean>)
      Fired after a change in the change tracking state.

    ##Known Issues

    • Adjacent changes from different collaborators may affect each other if you accept/reject a single change in the sequence. This is related to an issue in ICE which we hope to resolve with the developers.
    • See the ICE page for known issues related to ICE.
    • Note that the ICE engine adds markup to the editor content.
    • LITE tracks only text insertion and deletion. Other changes, such as style edits, are not tracked.

    ##Browser Compatibility LITE has been tested on Firefox 15+, Chrome 13+ and MSIE 9+. Support for MSIE 8 is not guaranteed, although the current version seems to work on it.

    ##License

    Copyright (c) LoopIndex.

    GPL 2.0

    This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along with this program as the file gpl.txt. If not, see http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

    Written by (David *)Frenkiel (https://github.com/imdfl)