API Reference

Initializing RecogitoJS

Initialize a RecogitoJS instance on a page element with

var r = Recogito.init(config);

The configuration must be an object with the following properties:

Property	Value	Default
content	REQUIRED the DOM element to make annotate-able or, alternatively, the ID of the element	-
readOnly	Set to true to display annotations read-only	false
formatter	For adding custom CSS classes to anntotations (see Formatters)	-
locale	Set the language code for UI localization. Use auto to select the language based on the browser setting. See here for a list of currently supported languages	-
mode	Set this to pre if the content is preformatted text (<pre> tag or white-space: pre CSS style). In pre mode, TextPositionSelectors stored in the annotations will precisely match the text formatting in the markup, whereas positions in html mode will correspond more closely to the character offsets rendered in the browser.	html

Instance Methods

addAnnotation(annotation)

Adds an annotation programmatically. The annotation format is that of the W3C WebAnnotation model. RecogitoJS requires a TextPositionSelector in the annotation, and will display each TextualBody as a field the popup.

Argument	Value
annotation	the annotation object in WebAnnotation format

removeAnnotation(annotation)

Removes an annotation programmatically.

Argument	Value
annotation	the annotation object in WebAnnotation format

loadAnnotations(url)

Loads annotations from a JSON-LD source. The method returns a promise, in case you want to do something after the annotations have loaded.

r.loadAnnotations(url).then(function(annotations) {
  // Do something
});

Argument	Value
url	the URL to HTTP GET the annotations from

getAnnotations()

Returns all annotations, according to the current rendered state.

on(event, callback)

Subscribe to an event. (See Events for the list.)

Argument	Value
event	the name of the event
callback	the function to call when the event is emitted

off(event[, callback])

Unsubscribe from an event. If no callback is provided, all event handlers for this event will be unsubscribed.

Argument	Value
event	the name of the event
callback	the function used when binding to the event

Events

createAnnotation(annotation, overrideId)

Fired when a new annotation is created from a user selection. When an annotation is created, RecogitoJS automatically assigns it a globally unique ID. It is possible to override this ID with your own (e.g. server-generated) ID via the overrideId callback function.

r.on('createAnnotation', async (annotation, overrideId) => {
  // POST to the server and receive a new ID
  const newId = await server.createAnnotation(annotation);

  // Inject that ID into RecogitoJS
  overrideId(newId);
});

Warning: keep in mind that users may have continued annotating if the async operation takes a long time. This creates a potential concurrency situation when the user:

• creates a new annotation
• and then draws a relationship just before the ID is updated

RecogitoJS takes care of keeping the IDs in sync internally between annotation and relation, after overrideId was called. But you may need to take extra precautions to avoid IDs getting out of sync on the server. Be sure you understand the possible consequences of opting out of auto-generated IDs when using relationship annotation.

Argument	Value
annotation	the annotation in W3C WebAnnotation format
overrideId	a callback function for assigning a custom annotation ID

updateAnnotation(annotation, previous)

Fired when an existing annotation was updated.

Argument	Value
annotation	the updated annotation
previous	the annotation state before the update

Formatters

Per default, RecogitoJS renders annotation highlights as SPAN elements with an annotation CSS class.

Tell me of <span class="annotation">that ingenious hero</span> who travelled...

By adding a formatter, you can customize the CSS classes that will be attached to the annotation highlights, and use these classes to create your own style rules. The formatter is simply a function which gets the annotation as an argument, and must return a string.

// E.g. to give a different background color to annotations with multiple bodies
var formatter = function(annotation) {
  return (annotation.bodies.length > 1) ? "has-multiple-bodies" : "";
}