Adding a docked mode to your widgets
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.
This article is licensed under a Creative Commons Attribution, Non Commercial - Share Alike 2.5 license.
Comments
The forum archive of this article is still available on My Opera.