Opera logo


Adding a docked mode to your widget

  1. Introduction
  2. HTML markup
  3. Config.xml alterations
  4. JavaScript
  5. Summary

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. You can use the Widget Emulator to see how your widget will look like in docked mode on different devices.

Note: 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:

In this article we will create an example Hello World widget with a docked mode, to show you how it’s 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, its time to bring in JavaScript event listeners to control everything.

In order to know if 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 the 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.