This is a lower-level API. Lower-level APIs are not recommended for most projects, and may not be available on all plans. See our page on recommended deployment patterns for more information.

Methods

This page details the public methods available in Annotations API.



On this page:

Overview

The supported public methods of Annotations API can be accessed with the itemsApp.assessApp().annotationsApp() object. You will append to this the module name and the public method name, along with any required arguments.

Use the code structure shown below.

Example:

itemsApp.assessApp().annotationsApp().module('notepad').show();

Annotations App Instance Public Methods

These methods are for general interactions with the Annotations API.

Returns the specified module with facade object, or if no module is specified, returns an array of all the modules that have been enabled, for example ["notepad", "stickynote"].

Parameters
moduleName
string

Available moduleName values are: drawing, notepad, texthighlight, and stickynote.

 
itemsApp.assessApp().annotationsApp().module('drawing');

Binds an event handler (callback) that will be invoked whenever an event is triggered.

Implemented using the once method of the BackboneJS Event object.

See events binding outline for more information.

Parameters
eventName
string
The name of the event that the callback will be bound to.
callback
function()
The function that will be invoked whenever the specified event is triggered.
context
object
The context for which the callback should be invoked.
 
itemsApp.assessApp().annotationsApp().on('error', function () { // onError callback });

Just like on, but causes the bound callback to only fire once before being removed. Handy for saying "the next time that X happens, do this".

See events binding outline for more information.

Parameters
eventName
string
The name of the event that the callback will be bound to.
callback
function()
The function that will be invoked when the specified event is triggered.
context
object
The context for which the callback should be invoked.
 
itemsApp.assessApp().annotationsApp().once('texthighlight:add', function () { // onTextHighlight callback });

Removes the event handler for a bound callback.

See events binding outline for more information.

Parameters
eventName
string
The name of the event that the callback is bound to.
callback
function()
The function that will be invoked whenever the specified event is triggered.
context
object
The context for which the callback should be invoked.
 
itemsApp.assessApp().annotationsApp().off('texthighlight:remove', function () { // onTextHighlight callback });

Reset current annotationsApp instance. All modules’ components will be removed.

itemsApp.assessApp().annotationsApp().reset();

Check if there are any unsaved annotations. This method will return true if there are no unsaved annotations, or return false if there are unsaved annotations.

itemsApp.assessApp().annotationsApp().safeToUnload();

Save all annotations data into DB.

itemsApp.assessApp().annotationsApp().save();

Show all the enabled annotation tools, including highlights, drawings, sticky notes and the notepad.

Note This method is mainly used when assessment rendering_type is inline.

itemsApp.assessApp().annotationsApp().showAnnotations();

Hide all the enabled annotation tools, including highlights, drawings, sticky notes and the notepad.

Note This method is mainly used when assessment rendering_type is inline.

itemsApp.assessApp().annotationsApp().hideAnnotations();

Drawing Module Public Methods

These methods are for interacting with the drawing tool.

Adds one drawing area. A drawing area is a rectangular zone on the page that contains one part of the drawing. Takes two values, one for the drawing id and one for the HTML element name of the container.

Parameters
id
string
A unique string value up to 150 characters in length.
container
object
The DOM element upon which drawings can be made.
Returns: DrawingArea
itemsApp.assessApp().annotationsApp().module('drawing').addDrawingArea('12', document.body);

Enters the drawing mode. This is the same as clicking on the "Drawing mode" button in the user interface. In this mode, the drawing toolbar is displayed and users can draw on the drawing areas.

Note All drawing areas will enter drawing mode when this method is called.

itemsApp.assessApp().annotationsApp().module('drawing').enterDrawingMode();

Exits the drawing mode. The drawing toolbar will be hidden and users will no longer be able to draw on the page.

itemsApp.assessApp().annotationsApp().module('drawing').exitDrawingMode();

Get all of the Drawing Area instances in an array, so they can be manipulated.

Returns: Array[DrawingArea] 
itemsApp.assessApp().annotationsApp().module('drawing').getAllDrawingAreas();

Gets the current state of the drawing tool, regardless of whether drawing mode is active. Possible values are 'pencil' or 'eraser'.

Returns: string 
itemsApp.assessApp().annotationsApp().module('drawing').getDrawingTool();

Hides all the drawings.

itemsApp.assessApp().annotationsApp().module('drawing').hide();

Checks the state of the drawing mode. True = active. False = inactive.

Returns: boolean 
itemsApp.assessApp().annotationsApp().module('drawing').isDrawingModeActive();

Checks the visibility of the drawing(s). True = visible. False = invisible.

Returns: boolean 
itemsApp.assessApp().annotationsApp().module('drawing').isVisible();

Removes one drawing area.

Parameters
id
string
The id of the drawing area to be removed. The id can be any string value. The id can be collected by calling itemsApp.assessApp().annotationsApp().module().getAllDrawingAreas()[index].getId()
 
itemsApp.assessApp().annotationsApp().module('drawing').removeDrawingArea('12345');

Sets the drawing tool to 'pencil' or 'eraser'.

Parameters
mode
string
 
itemsApp.assessApp().annotationsApp().module('drawing').setDrawingTool('pencil');
itemsApp.assessApp().annotationsApp().module('drawing').setDrawingTool('eraser');

Shows all the drawings.

itemsApp.assessApp().annotationsApp().module('drawing').show();

Toggles the display of the background grid for the drawing tool.

Version added: v2021.2.LTS

itemsApp.assessApp().annotationsApp().module('drawing').toggleGrid()
object

An object describing a rectangular bounding box, which contains individual drawings.

Properties:
getContainerElement
function()

The DOM element that was used to initialize the drawing area.

Returns: HTML DOM Element
getContainerWidth
function()

Returns the container width in pixels, or returns undefined if not set.

Returns: number
getId
function()

The id that the DrawingArea was initialized with. Returns a string value.

Returns: string

Notepad Module Public Methods

These methods are for interacting with the notepad.

Shrinks the notepad window down to the collapsed state (just the menu bar).

itemsApp.assessApp().annotationsApp().module('notepad').collapse();

Sets the notepad to the expanded state (as opposed to collapsed).

itemsApp.assessApp().annotationsApp().module('notepad').expand();

Hide the notepad.

itemsApp.assessApp().annotationsApp().module('notepad').hide();

Show the notepad.

itemsApp.assessApp().annotationsApp().module('notepad').show();

Toggle the notepad's visibility status between shown and hidden.

itemsApp.assessApp().annotationsApp().module('notepad').toggle();

Returns the status of the notepad window's visibility, as True or False.

Returns: boolean 
itemsApp.assessApp().annotationsApp().module('notepad').isVisible();

Sets the notepad to the maximum size, filling the window.

itemsApp.assessApp().annotationsApp().module('notepad').maximize();

Sets the notepad to the minimum size (but not collapsed).

itemsApp.assessApp().annotationsApp().module('notepad').minimize();

Resizes the notepad window to the dimensions specified.

Parameters
width
number
height
number
 
itemsApp.assessApp().annotationsApp().module('notepad').resize(200, 200);

Set the content of the notepad text body.

Parameters
contentString
string
 
itemsApp.assessApp().annotationsApp().module('notepad').setContent('Hello World');

Sticky Note Module Public Methods

These are the sticky note methods that allow for interacting with all sticky notes simultaneously, and creating new sticky notes.

Add one new sticky note to the page.

Returns: sticky note instance 
itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

Render all stored stickynotes belonged to current Annotations instance's group_id.

This method should be called when all the DOM parents of the stickynotes

Returns: sticky note instance 
itemsApp.assessApp().annotationsApp().module('stickynote').render();

Returns a reference to an instance of one sticky note as an object for manipulation. It takes one argument, a string containing the sticky note id. The sticky note id format is a set of hyphen-delimited letters and numbers such as 61e2d437-6a34-4a14-b8f8-d07f1d5c7ef6. If the object does not exist, null will be returned.

Parameters
id
string
Returns: object 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').getNote('61e2d437-6a34-4a14-b8f8-d07f1d5c7ef6');

Returns a collection of sticky note instances.

Returns: array 
itemsApp.assessApp().annotationsApp().module('stickynote').getAllNotes();

Sets all sticky notes to the "expanded" state.

itemsApp.assessApp().annotationsApp().module('stickynote').expandAllNotes();

Sets all sticky notes to the "collapsed" state.

itemsApp.assessApp().annotationsApp().module('stickynote').collapseAllNotes();

Shows all sticky notes on the page.

itemsApp.assessApp().annotationsApp().module('stickynote').showAllNotes();

Shows all sticky notes on the page.

itemsApp.assessApp().annotationsApp().module('stickynote').show();

Hides all sticky notes on the page.

itemsApp.assessApp().annotationsApp().module('stickynote').hideAllNotes();

Hides all sticky notes on the page.

itemsApp.assessApp().annotationsApp().module('stickynote').hide();

Show only the relevant sticky notes (the "collection") for the current Item in context. A group of sticky notes is known as a collection. The collection id string will be populated from the name of the Item in context. This method is useful mainly when implementing your own assessment player and switching frequently between Items -- the Learnosity Assess player calls it automatically in the background when users move between Items. It is not needed for most implementations.

Parameters
collectionId
string
 
itemsApp.assessApp().annotationsApp().module('stickynote').showOnlyCollectionId('Demo3');

Sticky Note Instance Public Methods: Getters

These methods operate on an individual instance of a sticky note.

Get the id of the sticky note in context.

Returns: string 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.getId();
// -> "e69f3c88-69f1-419c-8c89-daaf6fde66ef"

Get the collection id of the collection that the sticky note in context belongs to. A group of sticky notes is known as a collection. The collection id string will be populated from the name of the Item in context.

Returns: string 
myNote.getCollectionId();
// -> "Demo3"

Get the body text from inside the sticky note in context.

Returns: string 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.getContent();
// -> "The quick, brown fox jumps over the lazy dog."

Get the pixel dimensions of the sticky note in context. Returns an object with two number properties, width and height.

Returns: object 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.getDimensions();
// -> {width: 250, height: 230}

Get the screen coordinates of the sticky note in context.

Returns: object 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.getPosition();
// -> {x: "33.723%", y: "47.468%"}

Get the visibility state of the sticky note in context. Returns a boolean value. True = visible. False = invisible.

Returns: boolean 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.isVisible();
// -> true

Get the expansion state of the sticky note in context. Returns a boolean value. True = expanded. False = collapsed.

Returns: boolean 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.isExpanded();
// -> true

Sticky Note Instance Public Methods: Setters

These methods operate on an individual instance of a sticky note.

Saves the content of the sticky note in context.

Parameters
contentString
string
 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.setContent('Hello World!');

Set the screen position of the sticky note in context. Can be a value in pixels or a percentage (append '%' or 'px' to the values, respectively).

Parameters
x
string
y
string
 
const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.setPosition('30%','30%');
myNote.setPosition('100px','100px');

Changes the window state of the sticky note in context to expanded.

const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.expand();

Change the window state of the sticky note in context to collapsed.

const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.collapse();

Show the sticky note in context.

const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.show();

Hide the sticky note in context.

const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.hide();

Resize the window of the sticky note in context. Takes two number values that will be used as pixel dimensions.

const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.resize(300,300);

Destroys the sticky note in context.

const myNote = itemsApp.assessApp().annotationsApp().module('stickynote').addNote();

myNote.remove();

Text Highlighting Module Public Methods

These methods are for interacting with the text highlighting tool.

Highlights certain text based on provided information. If the provided startContainerPath and endContainerPath start with an id prefix like “[id^=”passage_”]>p:nth-of-type(2);0”, then of all the elements that have ids matching [id^=”passage_”] such as id='passage_0' or id='passage_1' will be highlighted.

Parameters
id
string

A unique string value up to 150 characters in length.
startContainerPath
string

The beginning of the container path.
endContainerPath
string

The end of the container path.
startOffset
string

The beginning of the offset, a value in pixels.
endOffset
string

The end of the offset, a value in pixels.

 
app.module('texthighlight').applyHighlight({
    id: 'myNote',
    startContainerPath: 'div:nth-of-type(1)>p:nth-of-type(2);0',
    endContainerPath: 'div:nth-of-type(1)>p:nth-of-type(2);0',
    startOffset: 297,
    endOffset: 538
});

Renders stored highlights. This method should be called after the content of the page (containing the highlights) has been rendered completely.

itemsApp.assessApp().annotationsApp().module('texthighlight').render();

Each time a texthighlight is created, you can optimize the highlight information to suit your needs. This method is mostly used when you want to store highlights that will be persisted in multiple elements. For example, formatting the startContainerPath from “[id=”passage_0”]>p:nth-of-type(2);0” to “[id^=”passage_”]>p:nth-of-type(2);0”.

Parameters
callbackFunction
string

A callback function name.

 
itemsApp.assessApp().annotationsApp().module('texthighlight').setFormatRenderResult('callback');

Show all the highlighted text.

itemsApp.assessApp().annotationsApp().module('texthighlight').show();

Hides all the highlighted text.

itemsApp.assessApp().annotationsApp().module('texthighlight').hide();

You can define what sort of id prefix Annotations API should not store. This method is mostly used if your page contains dynamic content that can change each time it gets rendered. For example, the MathJax or MathQuill content of Learnosity.

Parameters
ids
string

The prefix that changes each time it gets rendered. For example, the MathJax or MathQuill content of Learnosity.
Note If you supply an ID like "foo" here, all IDs with 'foo' as a prefix (like 'football', 'foolish', etc.) become unhighlightable, too.

 
annotationsApp.module('texthighlight').utils.setBlackListIds(['MathJax-']);

Retrieves the path (similar to startContainerPath/endContainerPath) based on the provided DOM node element and context.

Parameters
element
object

The DOM node element.
Returns: string 
app.module('texthighlight').utils.getPath(['DOM-element-name','DOM-context-name']);

Retrieves the DOM node based on the provided path, textNodeOffset and context element.

Parameters
path
string

The path.
textNodeOffset
string

The text node number.

 
app.module('texthighlight').utils.deserializePath(['_navbar','31','DOM-context-name']);