Adding a docked mode to your widgets

By Opera Software

24th April 2012: Please note

Starting with Opera 12, Opera Widgets will be turned off for new users and completely removed in a later release. If you're interested in building addons for Opera, we recommend going with our extensions platform — check out our extensions documentation to get started.

Table of contents:

Introduction

Opera Widgets are required to be run on various devices under differing UI constraints. In some cases, the UI needs to be interactive and in others only informative. To support this, Opera Widgets can be viewed in different modes, each mode giving the widget a slightly different environment to render in.

The default mode is the widget mode, which will display the widget as a separate window without chrome. There is also a docked mode, also known as micro mode, which is the minimized version of your widget. This version will typically be visible on the idle screen of a mobile phone, or in a panel in the desktop browser.

A docked widget takes the form of a non-interactive clipping of the widget from the top-left corner of the widget window. You can control how your widget looks when it gets docked by listening to JavaScript events dispatched by the device.

Note that widgets in docked mode are still actively running widgets. It is up to you to make sure the widget is not draining resources while in docked mode.

Various use cases apply to the docked mode, including:

Showing the number of unread items in a news feed
Showing weather information for your current location
Showing notifications or friend requests from social-networking sites

In this article we will create an example Hello World widget with a docked mode, to show you how it is done. The docked mode will display “Hello Docked World”. The HTML structure, CSS rules, and JavaScript for the widget are essentially the same as they would have been without the docked mode.

HTML markup

For our example, we choose to have two separate DOM elements representing the widget and docked modes. This is done only for keeping the code simple, and is in no way a definitive implementation.

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <div id="container">
      <div id="widget">
        Hello World!
      </div>
      <div id="docked">
        Hello Docked World!
      </div>
    </div>
  </body>
</html>

Config.xml alterations

Most widget implementations will simply display your widget’s icon and title in place of the docked mode, if your widget does not support it. This is why it is important for the implementation to know whether your widget supports docked mode. To let it know, we need to add an attribute of dockable to the widget element in the widget’s config.xml:

<?xml version='1.0' encoding='UTF-8'?>
<widget dockable="yes">
  <widgetname>New Feed reader</widgetname>
  <description>A news feed reader with a docked widget.</description>
  <width>240</width>
  <height>320</height>
</widget>

JavaScript

Now that the widget implementation is aware that your widget supports the docked mode, and the HTML markup has dummy content for your docked widget, it is time to bring in JavaScript event listeners to control everything.

To know whether you are changing the widget mode from widget to docked or vice versa, the application must listen to the widgetmodechange event on the widget object. The following event listener handles this:

widget.addEventListener( 'widgetmodechange', handleModeChange, false);

You can access the new mode through the widgetMode property of the event. In this case, we need to handle the transition to and from docked mode, so the handleModeChange() function is created as follows:

function handleModeChange(e)
{
    switch ( e.widgetMode )
    {
        case 'docked':
            handleDockedMode();
            break;
        case 'widget':
            handleWidgetMode();
            break;
    }
}

In the case of either mode, we want to get rid of the DOM which makes up one mode and replace it with markup for the other mode. The best way for managing DOM elements and populating the DOM Tree is explained in our article about cross-device development of widgets.

For our example, we can simply use display: none and display: block on the two elements:

function handleDockedMode()
{
    document.getElementById('widget').style.display = "none";
    document.getElementById('docked').style.display = "block";
}

Summary

In this article we have shown a simple example that demonstrates how to give a widget a docked mode. In some cases, you may not need to hide any data at all. In others a complete UI change might be necessary. It is recommended that you investigate the best mechanism to show and hide data when transitioning between modes.

Opera Widgets SDK table of contents

This article is licensed under a Creative Commons Attribution, Non Commercial - Share Alike 2.5 license.