The Web Widgets API

OpenBoard provides an API for interaction between web widgets and the OpenBoard application, using JavaScript.

API interaction patterns

The API allows four types of interactions:

• Properties are simple variables, which are mirrored to the JavaScript engine and can be read by widgets. Note that properties are read-only. Value changes cannot be forwarded from the widgets to the OpenBoard application.
• Signals are triggers sent by the OpenBoard application to the widgets. They can also carry parameters.
• Slots provide the other direction: They are sent from the widgets to the OpenBoard application. They can also carry parameters.
• Functions can be invoked from a widget and are processed by the OpenBoard application. In contrast to slots, functions can have a return value, which is provided asynchronously to the widget.

There are several API objects providing distinct sets of functions, which are described below. Each API is accessible as a global variable through the window object.

Properties

API properties can be accesses just as variables. Their value reflects the value of the property in the OpenBoard application.

Example:

var width = window.widget.width;

Signals

Signals are asynchronous events sent from the OpenBoard application to a widget. To handle a signal, the JavaScript application has to connect a callback, e.g. as follows:

window.widget.onenter.connect(() => { console.log("received onenter"); });

Slots

Slots are asynchronous events sent from a widget to the OpenBoard application. They can be triggered by a function invocation.

Example:

window.sankore.setPreference("key", "value");
window.widget.openURL("https://www.openboard.org");

Functions

Functions are similar to slots, but return a value. In contrast to the WebKit based widget API, the result is delivered asynchronously. It can be delivered in a callback or a Promise.

Examples:

// use callback
window.sankore.preference("key","default",function(value){
    // do something with value
});

// use Promise
window.sankore.async.preference("key","default").then(value => {
    // do something with value
});

// use async/await
async function myFunc() {
    var value = await window.sankore.async.preference("key","default");
    // do something with value
}

The widget API

Properties

The widget API provides access to basic properties of a widget. It contains the following properties:

• window.widget.uuid : Instance UUID, return a unique identifier for the widget. This value is guaranteed to be unique and constant for a widget.
• window.widget.id : The id of the widget as taken from the widget metadata.
• window.widget.name: The name of the widget as taken from the widget metadata.
• window.widget.description : The description of the widget as taken from the widget metadata.
• window.widget.author : The author of the widget as taken from the widget metadata.
• window.widget.authorEmail : The author e-mail address of the widget as taken from the widget metadata.
• window.widget.authorHref : The author web page address of the widget as taken from the widget metadata.
• window.widget.version : The version of the widget as taken from the widget metadata.
• window.widget.width : The actual width of the widget.
• window.widget.height : The actual height of the widget.

Signals

OpenBoard emits the following signals:

• window.widget.onenter : Emitted when the mouse cursor enters the area of the widget.
• window.widget.onleave : Emitted when the mouse cursor leaves the area of the widget.
• window.widget.onremove : Emitted immediately before the widget is removed from the board.

Slots

Additionally it provides the following slot:

• window.widget.openURL(string) : Open the given URL in the built-in browser.

Just for completeness, there is also an obsolete interface to a preference API available at window.widget.preferences. Please use instead the sankore.preferences API below.

The sankore API

The sankore API provides access to OpenBoard functions and allows interaction between widgets and the OpenBoard application. The sankore API is aware of the current scene. So many operations work with the current scene.

Properties

It contains the following properties:

• window.sankore.uuid : Deprecated, use window.widget.uuid instead.
• window.sankore.lang : Returns the language and eventually the country of this locale as a string of the form "language-country" or only "language" if the country is unknown, where language is a lowercase, two-letter ISO 639 language code, and country is an uppercase, two-letter ISO 3166 country code. Some potential values are en, en-UK, fr, fr-CH, fr-FR.
• window.sankore.dropData : Set to a short XML document containing details about the dropped file when enableDropOnWidget was called with processFileDrop set to true (see below). Shall be used in the drop handler instead or additionally to retrieving this data in the drop event.

Slots

The API provides the following slots for interacting with OpenBoard:

• window.sankore.setTool(tool) : set the tool. The parameter is a string indication the tool ("pen", "marker", "arrow", "play", "line").
• window.sankore.setPenColor(color) : set the color of the pen. The parameter is a string indicating an HTML color ("red", "blue", ...), an rgb value ("#FF0000") or a default Uniboard color ("1", "2", "3", "4", "5").
• window.sankore.setMarkerColor(color) : set the color of the marker. The parameter is a string indicating an HTML color ("red", "blue", ...), an rgb value ("#FF0000") or a default Uniboard color ("1", "2", "3", "4", "5").
• window.sankore.zoom(factor,x,y) : View based: Zoom the current viewport centered on scene position x/y.
• window.sankore.move(dx,dy) : View based: Move the current viewport for dx, dy pixels.
• window.sankore.moveTo(x,y) : Scene based: Move the control to position x/y in scene coordinates.
• window.sankore.drawLineTo(x,y,width) : Scene based: Draw a line from current pos to x/y in scene coordinates.
• window.sankore.eraseLineTo(x,y,width) : Scene based: Erase any line from current pos to x/y in scene coordinates.
• window.sankore.clear() : Scene based: Remove all drawings/objects from current scene.
• window.sankore.setBackground(isDark,isCrossed) : Scene based: Set the scene background to black/white with crossing or not.
• window.sankore.addObject(url,width,height,x,y,isBackground) : Scene based: Add any supported objects (pictures/video/widget) centered at scene position x/y. Width and height may be supplied, but are ignored for most object types. If background is true, the object is not selectable and sits in the lowest z position possible
• window.sankore.resize(width,height) : Scene based: Resize the container to width/height in scene (DOM) coordinates.
• window.sankore.setPreference(key,value) : Widget based: Save a preference for this widget instance. Both key and value are strings.
• window.sankore.showMessage(message) : Display a message on the bottom left corner of the board.
• window.sankore.centerOn(x,y) : Center the scene coordinates within the display port.
• window.sankore.addText(text,x,y,height,font,bold,italic) : Write some text on the board.
• window.sankore.sendFileMetadata(metadata) : TBD.
• window.sankore.enableDropOnWidget(enable,processFileDrop) : Inform OpenBoard that the widget supports a drop of an object. Setting processFileDrop to true enables the property dropData. See above. Default values are enableDropOnWidget(true,false)

Functions

The sankore API contains the following functions:

• window.sankore.pageCount() : The number of pages in the current document.
• window.sankore.currentPageNumber() : The page number of the current page.
• window.sankore.pageThumbnail(pageNumber) : Returns the URL of the thumbnail of a page.
• window.sankore.locale() : Deprecated. Use the lang property instead.
• window.sankore.preference(key,default) : Returns the value of the given preference or the default if the key does not exist.
• window.sankore.preferenceKeys() : Returns a list of all preference keys.

Widget upgrade

The widget API provided with QWebEngine is different from the one of QWebKit. This means that documents created with the original widget set will no longer work with the QWebEngine based version of OpenBoard unless they are upgraded.

OpenBoard provides an automatic upgrade mechanism for that. To make use of this mechanisms developers adapting the widgets to the new API have to follow some simple rule:

• use unique ids. Previously some interactivities had non-unique id's. When adapting these interactivities assign them a new and unique id. Proposals are available in resources/etc/widgets.md5sum which must match the actual id of the updated config.xml. The OpenBoard widget upgrade uses this table to identify these widgets and to map them to updated versions.

When a document is opened, OpenBoard checks the widget API usage by scanning for synchronous function invocation and signals not using the connect feature. If it detects such API usage for a widget which is also in the widget library, then the code of that widget is automatically upgraded to the new version.

Note that there is no downgrade mechanism. So documents containing widgets with the new widget API will most likely not properly work on older versions of OpenBoard.

If a widget cannot be upgraded, OpenBoard will show a grey rectangle with a hint indicating the incompatibility.

This page was written by @letsfindaway