Welcome to Lance for Froala

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 11 is not guaranteed, although the current version seems to work on it.

Main Features

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

Getting Started

1. Include the Lance scripts. These would be plugin.js and typically also js/annotationsui.min.js, which codes Lance's Comments UI.

   				
   					<script src="path/to/lance/plugin.js"></script>
   					<script src="path/to/lance/js/annotationsui.min.js"></script>
   				
   			

2. Initialize Lance before you create your first editor. This is done through the function initFroalaLancePlugin, available on the global object window.LANCE. This function accepts one parameter - the FroalaEditor module (if you've imported Froala) or window.FroalaEditor.

   					
   						var App = window.LANCE;
   						App.initFroalaLancePlugin(FroalaEditor);
   					
   				

3. Including the Lance plugin.js script and calling the initFroalaLancePlugin function, ensure that the Lance plugin will be available to every instance of the Froala Editor.
   

   	new FroalaEditor("someId", {
   // ... various options
   		toolbarButtons: [['undo', 'redo', 'bold'], ["annotate"]],
   		 lance: {
   			 // Various Lance options, see the demo code for details
   		},
   		events: {
   			// Various Editor events
   			"lance::init": function (event) {
   				var lance = event.lance;
   				var ann = lance.getAnnotations();
   				ann.addUsers([{
   					id: "1",
   					name: "Mary",
   					picture: "path/to/mary's/picture"
   				}]);
   				ann.setUserId("1");
   			}
   		}
   	}

Configuration

The Lance plugin is automatically activated after you install it and edit config.js as described above.

API

• Getting a reference to the lance plugin

  To interact with the lance plugin, either access it using the Lance utility function: var lance = FroalaEditor.PLUGINS.lance.findPlugin(someEditor), or listen to the event "lance::init" fired by the editor instance and save the reference your receive in the event data. See the above code for an example.

• 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.getAnnotations());

• 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 froala-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

Browser Compatibility

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

License

See the License file