Installation
If your ckeditor build does not already contain LITE, drop the
lite
folder into ckeditor's plugins
folderGetting Started
- Include the lite plugin's interface in your html, e.g.
<script type="text/javascript" src="ckeditor/plugins/lite/lite-interface.js"></script>
You don't have to include this file, but doing so will allow you to use the constants defined in it, e.g.LITE.Commands.TOGGLE_TRACKING, LITE.Events.ACCEPT
- If
LITE
is not included in ckedito's plugins list, add it to the editor's configuration. The simplest way to do this is by adding the following line to ckeditor'sconfig.js
:config.extraPlugins = 'lite';
If your configuration already contains some plugin tweaking, just make sure thatLITE
is included in the editor's plugins list. - If you wish to make any other configuration changes via
config.js
, verify that the editor's configuation contains alite
section by adding the following lines to ckeditor'sconfig.js
:var lite = config.lite|| {}; config.lite = lite;
- If your page doesn't include jQuery, the
LITE
plugin will load it during its initialization. By default the code is loaded from thelits/js
folder. If you want to provide a different path, you can do so by configuring the value oflite.jQueryPath
in ckeditor'sconfig.js
. The path you specify should be relative to thelite
folder.config.lite.jQueryPath = "../common/jquery.min.js";
Configuration
- By default, LITE loads a minifed version of
ice
, located in itsjs
folder. To loadice
from a different location, or load other versions (e.g. full sources for debugging), edit yourconfig.js
and set a value toconfig.lite.includes
, e.g.config.lite.includes = ["js/my-includes.min.js", "js/some-plugins.min.js"];
Paths are relative to the LITE plugin folder - Select the
LITE
commands you want to include in ckeditor's toolbar. By default all the commands inlite-interace.js
are available in the toolbar except for toggle tooltips. To configure this, editconfig.js
and set a value to theconfig.lite.commands
, e.g.// display only the show/hide, accept all and reject all commands. config.lite.commands = [LITE.Commands.TOGGLE_SHOW, LITE.Commands.ACCEPT_ALL, LITE.Commands.REJECT_ALL];
- Some more LITE options may be set through the
config.lite
object:userName
- the initial username used by theICE
change trackeruserId
- the initial user ID used by theICE
change trackertitleTemplate
- the template of the text shown as a title (tooltip) when the cursor hovers over a tracked change region. The default value isChanged by %u %t
,%u
representing the user name and%t
representing a time stamp relative to the current time (e.g. now, 2 minutes ago, May 31). The titles are refreshed periodically. If you provide an empty template, no title will be displayed.userStyles
- a map of id=>style number which allows you to consistenly display styles per user id. By default LITE creates a new style per user as it is introduced.tooltips
- set totrue
(or omit altogether) to get the default implementation of LITE tooltips, based on Opentip. You can also settooltips
to an object with various configuration options.isTracking
- set tofalse
to start the plugin's life with change tracking turned off.
- You may also tweak the configuration in your code by listening to the CKEditor
configLoaded
event and then modifying the editor'sconfig.lite
object.
Methods
Get a reference to the lite plugin
To interact with thelite
plugin, you need to obtain a reference to the actual plugin object which is unique for each instance of CKEditor. The safest way to do this is by listening to the eventLITE.Events.INIT
fired by the editor instance. Thedata
member of the event will contain a property calledlite
which references the lite plugin instance, initialized and ready for action.You can also obtain a reference directly from a fully initialized CKEditor by calling
myEditor.plugins.lite.findPlugin(myEditor)
.toggleTracking(bTrack, bNotify)
Toggles change tracking in the editor.Parameters
bTrack
- boolean. Ifundefined
, change tracking is toggled, otherwise it is set to this valuebNotify
- boolean. If false, theLITE.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. Ifundefined
, change visibility is toggled, otherwise it is set to this valuebNotify
- boolean. If false, theLITE.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 overinclude
)include
an array of user ids to include from the the operationfilter
a filter function that accepts an object of the form{userid, time, data}
and returns aboolean
. Only changes for which the filter returnstrue
are included in the operation. Thefilter
option can work with bothexclude
andinclude
.
options
block, including custom ones, are preserved when it is sent back in theACCEPT
orREJECT
events (see below).rejectAll(options)
Reject all the pending changes.Parameters
options
- optional object to filter the changes to which this operation applies. See theacceptAll
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 theacceptAll
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
andname
setChangeData(data)
Associates an arbitrary string with the changes made from now on. This string is passed to the optionalfilter
function inoptions
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 theLITE
plugin).
Events
The LITE plugin events are listen inlite-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 theICE
change tracker. This happens, e.g., when you switch back fromSource
mode toWysiwyg
. - 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. - REJECT (parameter : the