Documentation

Everything you need to become a Mark.js expert.

Getting Started

To use Mark.js on your webpage, you must link to the library's stylesheet and script file in your HTML as follows:

<link rel="stylesheet" type="text/css" href="mark-styles.css">
<script type="text/javascript" src="js/mark.js">

Then, in your HTML's respective JS file, instantiate a default Mark.js pop-up.

const markInstance = new Mark();

This pop-up is fixed to the top-left of the viewport by default. Now, we can use the Mark.js API (which is fully-defined below) to edit the pop-up's state. Here is a code snippet of basic changes we can make to our Mark instances.

// Fix the pop-up to the top-right of a specified HTML element.
markInstance.setParentElement("elementID");
markInstance.setRight("0");
markInstance.applyAbsolutePositioning();

// Set its 4 available highlighter colours.
markInstance.setHighlighterColours("#FFFF00", "lime", "cyan", "#FF7777");

// Match the pop-ups theme to fit some webpage's dark theme.
markInstance.setPopUpBackgroundColour("#222222");
markInstance.setPopUpBorderColour("#gray");
markInstance.setPopUpTextColour("#CCCCCC");
markInstance.setOffButtonColour("#FF6666");
markInstance.setOnButtonColour("#AAFFAA");
markInstance.setSwitchTextColour("#222222");
markInstance.setNoteInputColour("white");

// Paste a note for the user to see on the second note layer. (Both devs and users can paste notes!)
markInstance.setNoteLayerNumber(2);
markInstance.addNote({
  left: 400,
  top: 120,
}, "Hey user!", "#elementID2");
markInstance.setNoteLayerNumber(1); // We want the user to start off on the first note layer.

API

Constructor

Mark(selector)

PARAMETERS
  • selector: an HTML selector
BEHAVIOUR
Instantiates a default Mark.js pop-up. If selector is provided, the pop-up is positioned absolutely at the top-left of the corresponding HTML element. Otherwise, the pop-up is fixed to the top-left of the viewport.

Methods: Pop-up Positioning

hidePopUp()

BEHAVIOUR
Hides the Mark.js pop-up associated with the Mark.js object the method is called on.

showPopUp()

BEHAVIOUR
Show the Mark.js pop-up associated with the Mark.js object the method is called on.

setTop(value)

PARAMETERS
  • value: a number of pixels (of type Number).
BEHAVIOUR
If the Mark.js pop-up is positioned absolutely, set the y-coordinate of the top of the Mark.js pop-up to the y-coordinate of the top edge of its "reference element" plus value. Otherwise, the Mark.js pop-up has fixed positioning; set its top property to value.

setBottom(value)

PARAMETERS
  • value: a number of pixels (of type Number).
BEHAVIOUR
If the Mark.js pop-up is positioned absolutely, set the y-coordinate of the bottom of the Mark.js pop-up to the y-coordinate of the bottom edge of its "reference element" minus value px. Otherwise, the Mark.js pop-up has fixed positioning; set its bottom property to value px.

setLeft(value)

PARAMETERS
  • value: a number of pixels (of type Number).
BEHAVIOUR
If the Mark.js pop-up is positioned absolutely, set the x-coordinate of the left of the Mark.js pop-up to the x-coordinate of the left edge of its "reference element" plus value px. Otherwise, the Mark.js pop-up has fixed positioning; set its left property to value px.

setRight(value)

PARAMETERS
  • value: a number of pixels (of type Number).
BEHAVIOUR
If the Mark.js pop-up is positioned absolutely, set the x-coordinate of the right of the Mark.js pop-up to the x-coordinate of the right edge of its "reference element" plus value px. Otherwise, the Mark.js pop-up has fixed positioning; set its right property to value px.

applyFixedPositioning()

BEHAVIOUR
Fix the position of the Mark.js pop-up. The pop-up is given one of top/bottom properties according to the following rules.
  • If setTop/setBottom has not been called on this Mark instance, give the pop-up a top property of 0.
  • Otherwise, if setTop was called on the Mark instance more recently than setBottom was called, give the pop-up a top property equal to the input of the argument used in the last call to setTop.
  • Otherwise, setBottom was called on the Mark instance more recently than setTop was called; give the pop-up a bottom property equal to the input of the argument used in the last call to setBottom.
The pop-up is given one of left/right properties according to the same idea with setLeft/setRight.

applyAbsolutePositioning()

BEHAVIOUR
Position the Mark.js pop-up absolutely relative to the last reference element set. The last reference element is determined according to the following rules.
  • If setParent has been called on this Mark instance, the pop-up's reference element is the one defined by the selector argument to the last call to setParent.
  • Otherwise, setParent has not been called on this Mark instance. The pop-up's reference element is the one defined by the selector argument given to the constructor. If there was no selector argument given to the constructor, the popup's reference element is the document's body.
The pop-up is given one of top/bottom properties according to the following rules.
  • If setTop/setBottom has not been called on this Mark instance, give the pop-up a top property of 0.
  • Otherwise, if setTop was called on the Mark instance more recently than setBottom was called, give the pop-up a top property equal to the input of the argument used in the last call to setTop.
  • Otherwise, setBottom was called on the Mark instance more recently than setTop was called; give the pop-up a bottom property equal to the input of the argument used in the last call to setBottom.
The pop-up is given one of left/right properties according to the same idea with setLeft/setRight.

setParentElement()

BEHAVIOUR
Set the parent element used when the Mark instance's pop-up is positioned absolutely.

Methods: Note-Pasting by the Developer

addNote(position, text, referenceSelector)

PARAMETERS
  • position: an object containing a top property OR a bottom property (not both), and containing a left propery OR a right property (not both).
  • text: text to place in the note.
  • referenceSelector: the selector of an HTML element that we want to use as a reference when attatching this note.
BEHAVIOUR
Paste a new note, with the message text, on the Note Layer that this Mark instance is currently set to (this can be set by both the developer using setNoteLayerNumber, and the user via the Mark instance's pop-up).

setNoteLayerNumber(layerNumber)

PARAMETERS
  • layerNumber: an integer from 1 to 3, inclusive.
BEHAVIOUR
Set this Mark instance's note layer to Note Layer <layerNumber>. After this method is run, the only notes written with this Mark instance visible to the user are those written when this Mark instance was on Note Layer <layerNumber>.

Methods: Pop-up Style

setCurrentHighlighterColour(i)

PARAMETERS
  • i: an integer from 0 to 3, inclusive.
BEHAVIOUR
Set the active highlighter colour (the one the user can currently highlight with) to be the (i + 1)-th that is displayed on this Mark instance' pop-up (viewing from left to right).

setHighlighterColours(colour0, colour1, colour2, colour3)

PARAMETERS
  • colour0: a CSS colour value (as a string).
  • colour1: a CSS colour value (as a string).
  • colour2: a CSS colour value (as a string).
  • colour3: a CSS colour value (as a string).
BEHAVIOUR
Set the colours provided to the user to be the ones provided. Display them in the same order that they are provided as arguments (left to right).

setPopUpBackgroundColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's background colour to the one specified by the colour string.

setPopUpTextColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's text colour to the one specified by the colour string.

setPopUpTextColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's text colour to the one specified by the colour string.

setPopUpBorderColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's border colours to the one specified by the colour string.

setOnButtonColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's on button colours to the one specified by the colour string.

setOffButtonColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's off button colours to the one specified by the colour string.

setNoteInputColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's note input text colour to the one specified by the colour string.

setSwitchTextColour(colour)

PARAMETERS
  • colour: a CSS colour value (string).
BEHAVIOUR
Set the pop-up's button text colours to the one specified by the colour string. This method does not apply to the pop-up's on/off switches.

useDarkTheme()

BEHAVIOUR
Apply the default dark theme to this Mark instance's pop-up.

useLightTheme()

BEHAVIOUR
Apply the default light theme to this Mark instance's pop-up.

Methods: Pop-up View

maximize()

BEHAVIOUR
Maximize the view of this Mark instance's pop-up.

minimize()

BEHAVIOUR
Minimize the view of this Mark instance's pop-up.

freeze()

BEHAVIOUR
Take away the minimize/maximize button from this Mark instance's pop-up.

unfreeze()

BEHAVIOUR
Give this Mark instance's pop-up a minimize/maximize button.