Skip to content

Guide for widget update

Jump to bottom
Martin Winter edited this page Nov 5, 2023 · 3 revisions

OpenBoard 1.7.0 introduces a new Chromium based Web rendering engine. This affects the widget API and requires updates to most Web widgets.

This guide will give you some tips for updating your widgets.

Background

First of all some background: The current 1.6.4 version of OpenBoard as all previous ones is based on QWebKit as browser engine, which also runs the widgets. QWebKit is however deprecated since years, and the change to the modern, Chrome based QWebEngine is required for several reasons:

  • QWebKit is obsolete, does not get any security fixes and currently just kept alive here and there to support applications like OpenBoard still relying on this.
  • Many modern web pages using HTML5 cannot be rendered correctly with QWebKit. Users are complaining about that.
  • At some time OpenBoard has to update from Qt 5.15 to Qt 6.2. There is no QWebKit available for Qt 6 any more.

QWebEngine has however a somewhat different concept for the API to interact between Javascript and the C++ Qt application. The main difference is that now all interactions are asynchronous. That means e.g. that the often used window.sankore.preference(key,default) function call will not directly return the result. Instead a callback must be provided which will be invoked when the result is available. Similar changes affect other API functions and signals.

I have written some documentation about the widget API with a small paragraph with examples how to use the asynchronous nature of function calls.

In the end this means however that widget applications are no longer compatible between OpenBoard versions, and that the upcoming 1.7.x, which is built on QWebEngine, needs updated widgets.

Updating a widget

Perform the following tasks to update your widget:

  • Make sure it has a unique id in the config.xml.
    In the past, many widget authors did not care about the widget id. This is however required to identify widgets in a document.
    • If your widget already has a unique id: keep it!
    • If your widget used the same id as other widgets: make it unique!
  • Adapt to the asynchronous nature of API functions and signals.
    See the documentation linked above.
  • As a special case you may use the property window.sankore.lang instead of the deprecated window.sankore.locale() function.

Please note that updated widgets will no longer run in OpenBoard versions before 1.7.0.

Automatic document update

OpenBoard 1.7.0 tries to automatically upgrade the widgets in a document created with previous versions of OpenBoard. However this only works if the widget already had a unique id, so that OpenBoard can identify the widget in the document.

Note: For the built-in widgets there is an additional widget identification mechanism so that those can be updated even if they did not have unique ids. This mechanism is however not available for custom widgets.

Simple Example

As an example for the necessary changes you might have a look at commit 7020919, where I updated Papier.wgt and Stopwatch.wgt.

Here the required changes were quite small: For Papier.wgt I had to fix a type mismatch in a parameter, as the new QWebEngine is more picky about this. For the Stopwatch.wgt and I had to introduce the async and await keywords to access the properties. In other cases there were more changes necessary, but this example pretty much shows what it is about.

Testing your widget

The QWebEngine comes with the full Chromium developer tools, which are very useful to debug your widget. Create a board page with your widget using OpenBoard 1.7.0. Right-click on the widget and select "Open Web inspector" from the context menu.

You now can set breakpoints and inspect variables. Also check the console for any error messages or warnings.

Installing custom widgets

Some web pages recommend to copy custom widgets into the OpenBoard installation directory tree. Please see Custom widgets for a better alternative!

Clone this wiki locally