Inline Comments Plugin for TinyMCE

Integration guide

Why a guide?

Lance (Loopindex ANnotations for Content Editors) is a plugin for TinyMCE 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 TinyMCE 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 tinymce instance) needs to contain two types of elements which are not standard in TinyMCE plugins:

  1. The comments area an area on the page, usually adjacent to a TinyMCE 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 contain the script that defines the AnnotationsUI.
Assume the following folder strucutre:


	
hostpage.html
hostpage.css
hostpage.js
tinymce
|
tinymce.min.js
plugins
|
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="tinymce/tinymce.min.js"></script>
	<!-- the script that defines the comments user interface. -->
	<script type="text/javascript" src="tinymce/plugins/lance/js/annotationsui.min.js"></script>
	<!-- Your own javscript code that constructs and configures the comments UI -->
	<script type="text/javascript" src="hostpage.js"></script>

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.

When you receive lance plugin events, they already contain a reference to the instance associated with the editor:

	var editor = tinymce.init({
		selector: "editor1",
		plugins: 'lance',
		toolbar: "undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | table | fontsizeselect | lance",
		lance: {
			annotations: {
				permissions: {
					"delete": "owner"
				}
			}
		},
		mode: "exact",
		
		setup: onEditorSetup,
		init_instance_callback: onEditorLoaded
	});
	
	var onEditorSetup = function(editor) {
		editor.on("lance::init", function(event) {
			var lance = event.data.lance, // get a reference to the lance instance,
				annotations = lance.getAnnotations(); // get a reference to the annotations manager created by the plugin
			});


	var onEditorLoaded = function(editor) {
		// do something when the editor is loaded
	}

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 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,
    	blurAware: true
    };
    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:
    
    // editor is a variable obtained from a function call such as tinymce.init
    editor.on("lance::init", function(event) {
    	var lance = event.data.lance, // keep a reference to the lance instance,
    		annotations = lance.getAnnotations(); // get a reference to the annotations manager created by the plugin
    
    	// hook up the Annotations object to the UI we created in the previous step
    	ui.setOwner(annotations);
    
    	// 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);
    	});
    	// add some users to the annotations manager
    	annotations.addUsers([{
    		id : 1
    		name : "P Frink",
    		picture : "avatars/frink.png"
    	}, 
    	{
    		id : 2
    		name : "Bird Person",
    		picture : "avatars/bird.png"
    	}]);
    });
    
    			

Maximize (full screen) support

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

Handling multiple TinyMCE instances

When the host page contains several instances of TinyMCE, 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 TinyMCE 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 TinyMCE 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