Inline Comments Plugin for Froala

Integration guide

Why a guide?

Lance (Loopindex ANnotations for Content Editors) is a plugin for Froala that allows you to insert, modify and delete comment threads. While the comments markers are embedded in the editor text, the display area for the annotations is not contained in the editor. This makes the process of integrating Lance into Froala somewhat more complicated than simply adding the plugin to the editor's configuration.

Integration basics

In order to display the comment threads, the host page (a web page that contains the froala instance) needs to contain two types of elements which are not standard in Froala plugins:

  1. The comments area an area on the page, usually adjacent to a Froala instance, in which the comment threads are displayed
  2. If you're not using the automatically generated user interfce - Comment templates: HTML elements which are duplicated and populated for every comment added. As you can see in the demo provided with the Lance distribution, these elements are marked by the class lance-tmpl which has its display style set to none. The AnnotationsUI object duplicates these templates for each new comment thread and each new comment, removing the lance-tmpl class.
If these elements are not present, or are not conveyed to the AnnotationsUI controller, then your user interface will lack the part that displays comment text and controls.

Resource Setup

At the minimum, the host page needs to include the Lance plugin code and annotationsui.min.js - the script that defines the Annotations UI.

Assume the following folder strucutre:


	
hostpage.html
hostpage.css
hostpage.js
froala
lance
|
js
css

Under this structure, the includes for properly constructing and styling the comments UI are:

	<!-- page style,can appear anywhere -->
	<link rel="stylesheet" href="hostpage.css" />
	<!-- Must be included before any of the lance scripts -->
	<script type="text/javascript" src="froala/froala.pkgd.min.js"></script>
	<!-- the Lance plugin code. -->
	<script type="text/javascript" src="lance/plugin.min.js"></script>
	<!-- the script that defines the comments user interface. -->
	<script type="text/javascript" src="lance/js/annotationsui.min.js"></script>
	<!-- Your own javscript code that configures Lance and constructs the comments UI -->
	<script type="text/javascript" src="hostpage.js"></script>

Getting a reference to the lance plugin

(Work in progress)

The App namespace

All the Lance objects live in a namespace (just a fancy name for a variable) under the window variable. Technically, this namespace is located at window["LANCE"], but all the Lance code, including our demo pages, runs in a closure that refers to this namespace as App. This object is defined in annotationsui.min.js, so once you've included this file, you can use a common javascript closure to access the lance namespace as a variable, e.g.:

(function(App) {
	// code code code
	var ui = new App.AnnotationsUI();
	// more code
}(window["LANCE"]));

If your browser complains that App is not defined, then annotationsui.min.js has not been included, or is included after your script has started running.

Setting up the comments user interface

Once you've set up your html and includes, there are two steps in settings up the comments UI.

  1. Create the comments UI object, which manages the display of comments in the area that you've designated for this purpose. You initialize this object with information about the DOM nodes that display the comments.
    	
    var uiOptions = {
    	container: ".annotations" // the selector of the DOM node in which the annotations ui will construct its elements
    	// see the api documentation for options to use your own comments HTML templates
    	autoGrow: true, // default
    	blurAware: true // default
    };
    var ui = new App.AnnotationsUI();
    ui.init(uiOptions);
    	
    	
  2. Wait for the Lance plugin lance::init event and hook up your UI to the Annotations object associated with the plugin. Once the comments UI is connected to the Annotations object, it will listen to the various annotation events and display the comments accordingly. For example:
    
    	new FroalaEditor("#editor1", {
    		inlineMode: false,
    		//width: 600,
    		height: 400,
    		toolbarButtons: [['undo', 'redo', 'bold'],	["annotate"]],
    		lance: {
    			// various lance options
    		},
    		events: {
    			// various event handlers, then
    			// handle Lance init event
    			"lance::init": function (arg: any) {
    				var lance = arg.lance,
    					ann: any = lance.getAnnotations();
    				// add some users to the annotations manager
    				ann.addUsers([
    					{
    						id: "1",
    						name: " Amr",
    						picture: "avatars/amr.png"
    					},
    					{
    						id: "2"
    						name: "Bird Person",
    						picture: "avatars/bird.png"
    					}
    				]);
    				// hook up the Annotations object to the UI we created in the previous step
    				ui.setOwner(ann);
    				// register to some event from the annotations manager, just to show it can be done
    				annotations.on(App.Annotations.Events.ANNOTATION_CREATED, function(createdEvent) {
    					console.log(createdEvent);
    				});
    			}
    		}
    	}
    	
    
    			

Maximize (full screen) support

Currently not supported in Froala. When the editor is maximized, the comments UI is hidden.

Handling multiple Froala instances

When the host page contains several instances of Froala, each of them is served by a separate Annotations manager. If each editor is served by its own comments UI, then no action is required if you switch focus between editors. However, it is very common to use a single comments user interface and simply change its content when a certain Froala instance receives focus. This is easily accomplished by running the following code when an editor receives focus:
// assume the variable editor2 is a reference to a Froala instance
// assume the variable ui is a reference to an AnnotationsUI object
var lance = editor2.plugins.lance;
ui.setOwner(lance.getAnnotations()); // will unlink the UI from the current owner, if any

Full documentation

See our comprehensive API documentation

Known Issues

Browser Compatibility

Lance has been tested on Firefox 15+, Chrome 13+, Edge 3+/Edge Chromium and MSIE 9+. Future support for MSIE is not guaranteed.

License

See the License file