Widgets

Widgets are iframe-based HTML objects that can be embedded on any website. This allows third parties to easily integrate Drillster's functionality in third party systems.

Available widget types

Currently the following widget types are available:

Widget loader

The widget loader is a small Javascript library that will take care of loading the appropriate widgets on the page, and facilitates passing through the various event messages from the widgets to the hosting page.

The widget loader must be present on the page in order to display any Drillster widgets. It is a very lightweight (currently 4KB) script that needs to be included once somewhere on the page, irrespective of the number of widgets the page contains. As it will be cached by the browser, repeated requests will not carry a peformance penalty.

To include any widgets on your page, please include this line of HTML code anywhere on your page. To aid quick rendering of your page, it is best to place this code at the very end of the page, just above the closing </body> tag.

<script src="https://www.drillster.com/widgets/loader.js" type="text/javascript"></script>

With the loader added to the page, widgets may be embedded by adding the appropriate <div> tags (where {widget_type} refers to the particular widget type):

<div class="drl-widget {widget_type}"></div>

Please see the documentation for each widget type for exact embedding instructions.

Client-side events

During their operation, widgets may emit various types of events, such as when a widget is initialized, a question is answered or if some condition was met.

These messages originate in the widgets themselves, and are picked up by the widget loader and made available to the hosting page. It is up to the embedder to decide to listen to these messages and initiate particular actions based upon those messages. Acting on event messages requires Javascript programming.

Listening for widget events

The general format for listening to widget events and taking action is:

drillster.widgets().on('EVENT_TYPE', function(event) {
  // take action for any widget on the page
});

The above example will receive all events named EVENT_TYPE for any widget on the page. If the page contains just a single widget, this is the easiest way to subscribe to an event. However, if the page contains multiple widgets, it may be desirable to listen for events coming from a specific widget or a subset of widgets on the page. This may be accomplished as follows:

drillster.widgets('tile42').on('EVENT_TYPE', function(event) {
  // take action for widget 'tile42'
});

This code listens for events of type EVENT_TYPE coming specifically from a widget with ID tile42. Filtering by widget ID may also be done using regular expression patterns:

drillster.widgets('tile*').on('EVENT_TYPE', function(event) {
  // take action for any widget with an ID starting with 'tile'
});

Or to respond only to widgets tile1 and tile3 in a single statement:

drillster.widgets('tile(1|3)').on('EVENT_TYPE', function(event) {
  // take action for widgets 'tile1' or 'tile3'
});

It is also possible to listen for multiple event types in a single statement, again by using a regex pattern:

drillster.widgets().on('(EVENT_TYPE_1|EVENT_TYPE_2)', function(event) {
  // take action on EVENT_TYPE_1 or EVENT_TYPE_2 for any widget
});

Obviously the filters on event type and widget ID may be combined.

Processing the event message

When subscribing to widget events as described above, your custom code will receive the raw event if the filters by widget ID and event type match. An event is a Javascript object with a specific structure, and depending on the event type they may or may not contain payload data.

The general format of an incoming event is:

{
  "type": "EVENT_TYPE",
  "origin": "two",
  "data": {
    // optional payload
  }
}

The type represents the event type. It is included so that your custom code may distinguish between different events in case your code listens for multiple event types. For the same reason, the origin is included so that your code may distinguish between multiple widgets on the page. The origin value is always available. For widgets without an ID, the value for origin is set to UNKNOWN.

The data attribute contains the message payload and is optional. Whether or not a payload is inluded with the event, and what its data format is, depends on the widget and event type. Please see the documentation for each individual widget for details.

Delegated logins

If the containing page is able to obtain a valid authentication token for the end user, it is possible to display pre-authenticated widgets. This way it is possible to create a more seamless user experience. Please refer to the access section in the documentation of the Drillster REST API on how to obtain these tokens.

Most client-side widgets will accept a drl-token attribute. Please see the documentation for each widget for details.