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
allowEmpty	Annotations created without bodies are normally discarded. Set to true to allow empty annotations	false
content	REQUIRED the DOM element to make annotate-able or, alternatively, the ID of the element	-
editorAutoPosition	Set to true if the editor should automatically re-position to remain in view, detaching from the annotation if necessary	false
readOnly	Set to true to display annotations read-only	false
formatter	For adding custom CSS classes to anntotations (see Formatters)	-
locale	Set the two-character language code for UI localization. Alternatively, 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

clearAnnotations()

Removes all text and relationship annotations.

clearAuthInfo()

Clears the user auth information (see below). RecogitoJS will no longer insert creator data when creating or updating annotations.

destroy()

Destroys the RecogitoJS instance, removing all text and relationship annotations and restoring DOM state from before initialization.

getAnnotations()

Returns all annotations, according to the current rendered state.

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

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

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

removeAnnotation(annotation)

Removes an annotation programmatically.

Argument	Value
annotation	the annotation object in WebAnnotation format

setAnnotations(annotations)

Renders the list of annotations, removing any previously existing annotations. The annotations 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
annotations	array of annotations in WebAnnotation format

setAuthInfo(arg)

Specifies user authentication information. RecogitoJS will make use of this information when annotations are created or updated. arg is an object with the following properties:

Property	Value
id	REQUIRED the user ID, which should be an IRI
displayName	REQUIRED the user name, for display in the UI

The data will go into annotation bodies via the creator field:

{ 
  type: "Annotation",
  
  // ...  

  body:[{
    type: "TextualBody",
    value:"My comment",
    purpose: "commenting",
    created: "2020-05-18T09:39:47.582Z",
    creator: {
      id: "http://recogito.example.com/rainer",
      name: "rainer"
    }
  }]
}

setMode(mode)

Changes the annotation mode to either ANNOTATION or RELATIONS.

Argument	Value
mode	string, either ANNOTATION or RELATIONS

setServerTime(timestamp)

Set a "server time" timestamp. This method helps to synchronize the creation timestamps generated locally by RecogitoJS with the server environment, avoiding problems when the clock isn't properly set in the user's browser.

After setting server time, the creation timestamps will be adjusted by the difference between server time and local clock.

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

deleteAnnotation

Fired when an existing annotation was deleted.

r.on('deleteAnnotation', function(annotation) {
  // 
});

Argument	Type	Value
annotation	Object	the deleted annotation

selectAnnotation

Fired when the user selects an annotation.

r.on('selectAnnotation', function(annotation, element) {
  // 
});

Argument	Type	Value
annotation	Object	the annotation in W3C WebAnnotation format
element	Element	the annotation SPAN element

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" : "";
}