Welcome to Lance for CKEditor

Full API documentation Demo Page LoopIndex site

Integrating with the sample user interface

Lance ships with a sample user interface which you can customize or replace.
For detailed information about the process of integrating the plugin and the user interface into your web application,
please read the integration guide.

Requirements

Lance has been tested on Firefox 15+, Chrome 13+, Safari 10.x and Edge. Support for MSIE 9+ is not guaranteed, although the current version seems to work on it.

Main Features

• Unobtrusive comment markers
• Name, Id and time stamp associated with each comment
• Full comment life cycle events
• Fully customizable

Getting Started

• Add the lance plugin to ckeditor. The simplest way to do this is by adding the following line to ckeditor's configuration:
  config.extraPlugins = 'lance'; /* or include lance in the comma separated value of this configuration option */
• For a typical installation which uses the comments UI from LoopIndex, inlcude the following file from the lance plugin folder:
  • js/annotationsui.min.js

Configuration

The Lance plugin is automatically activated after you install it and edit the editor's configuration as described above.

API

• Getting a reference to the lance plugin

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

  If you're using the jQuery CKEditor adapter, hooking to the lance::init event is done through the adapter's editor property, e.g.

  		/* configure the annotations object */ 
  		
  		var e = $( '#editor' ).ckeditor( { extraPlugins: "lance" });
  		e.editor.on("lance::init", function(event) {
  			var lance = event.data.lance,
  				annotations = lance.getAnnotations();
  			annotations.addUsers([{
  				id : "14",
  				name : "maor melixon",
  				picture : "http://images.com/my/image.png"
  			}]);
  		});
  		

  Lance creates an separate instance of itself in every editor that activates it. Therefore, in order to access a particular Lance instance, you need to use the findPlugin method, e.g.

  		var e = CKEDITOR.instances.editor1,
  			lance = e.plugins.lance.findPlugin(e);
  		

• Using the default User Interface

  The Comments User Interface provided with Lance takes care of presenting comments and interacting with them. This UI is based on a handful of simple templates. In oder to use this UI, you need to copy the relevant html into your own page, or provide templates that conform to the same DOM hierarchy and css scheme. See the index.html file in the distribution for details. If you choose to implement your own UI, please verify that you are using the same DOM hierarchy and the same class names.

  The relevant code in our demo page:

  	var uiOptions = {
  				owner : null,
  				generateUI: true // auto generate the comments user interface
  				container: ".annotations-container" // selector, node or jQuery of the DOM 
  				// element in which the comments UI will be generated.
  			};
  		ui = new App.AnnotationsUI();
  		ui.init(uiOptions);
  				

  Later, when you have a handle to a lance instance, you set it as the owner of the UI object, e.g.

  ui.setOwner(mylanceInstance);

• The app pseudo namespace

  Lance creates all its objects under the window object. Browsing the demo source, you will see several references to an object called app. Note that this object doesn't exist under this name. Rather, it is just an alias for window["LANCE"]. Examples can be found in the ckeditor-demo folder of the demo provided with the archive.

• Object model

  Most of the functionality of the annotation system is contained in the Annotations object, defined in the annotations.js file in the js folder of the plugin. This object maintains all the data relevant to inline comments - the threads, user details, avatars etc. See the API documentation for full details.

  Normally, the lance plugin instance will create its own instance of an Annotations Manager. You can retrieve this instance from the plugin by calling its getAnnotations method. The plugin can be configured not to create its own Annotations Manager, in which case you'll need to provide it with your own copy.

• Full documentation

  See the API documentation for full details.

Known Issues

• Under MSIE, comment selection may result in a strange selection box around the comment pin. This is due to the way that MSIE handles contentEditable elements.

Browser Compatibility

lance has been tested on Firefox 15+, Chrome 13+ and MSIE 8+. Future support for MSIE is not guaranteed.

License

See the License file