Docked Mode for Widgets

Comments

You may have noticed that some widgets, while being minimized, display some piece of information on the Vodafone Apps Manager home screen. For example the pre-installed Weather Bug widget displays the current temperature of the set location, and the pre-installed Clock widget displays the current time. This is possible because the Vodafone Apps Manager runtime supports different modes in which a widget may run. For example, besides showing one widget at a time in application mode, it supports displaying widgets in a docked mode.

Screenshot 2: WeatherBug Widget in Docked Mode

Screenshot 1: WeatherBug Widget in Application Mode

Adding a docked mode to your widgets is quite easy and you only have to change your widgets following these two steps:

First, you have to tell the widget runtime that your widget is capable of being executed in docked mode
Second, you may want to change the appearance of the widget for the different modes (i.e. application and docked)

Make your widget “dockable”

The first step is very easy. To tell the widget runtime that your widget is capable of being executed in docked mode, add a dockable attribute to the <widget>-tag of your widget’s config.xml file and set its value to true.

<?xml version="1.0" encoding="utf-8"?>
<widget id="http://host/myWidget" dockable="yes">
  .
  .
  .
</widget>

Change the appearance of the widget

Most of the time, you probably want to change the appearance of a widget when it is executed in docked mode. To determine in which mode the widget is currently running - and to change the appearance of the widget corresponding to that mode -, you have two options: You may use CSS media queries or JavaScript event handling. Let us illustrate with one example.

First, we need a simple HTML page:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>My Docked Widget</title>

  <!-- Include stylesheets -->
  <link rel="stylesheet" href="css/style.css" type="text/css">
</head>
<body>
  <div id="main">This text will be displayed when the widget is NOT in docked mode</div>
  <div id="docked">This widget is docked</div>
</body>
</html>

CSS Media Queries

For CSS media queries, we need a CSS file that controls how the widget appears in the different modes. What we want to achieve is that in all modes except the docked mode, the content of the <div> with id=”main” is displayed, while the content of the <div> with id=”docked” is not. When the widget runs in docked mode, we want it the other way round: The content of the <div> with id=”main” should not be displayed and the content of the <div> with id=”docked” should be displayed.

So what we are going to do is to query whether the widget is currently running in docked mode or not. This is our (very basic) CSS file:

@media all and (-o-widget-mode:docked) {
  #main { display: none; }
  #docked { display: block; }
}

#docked { display: none; }

What happens here is that all styles between @media all and (-o-widget-mode:docked) { … } are applied when the widget is executed in docked mode. When the widget is executed in another mode, all other styles are applied.

JavaScript Event Handling

Your second option to control how the widget looks and behaves in the several modes is using JavaScript. Every time the mode of the widget changes, the runtime fires an widgetmodechange-event. Therefore, we need an event listener and a function that handles the changes we want to make.

First, we add the following code to the <head>-section of our index.html:

<!-- Include JavaScript -->
<script type="text/javascript" src="js/javascript.js"></script>

Then, within javascript.js, we register an event listener and we create a function that handles the changes we want to make:

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

function handleModeChange() {
  var main = document.getElementById('main');
  var docked = document.getElementById('docked');

  switch (widget.widgetMode) {
    case 'application':
      main.setAttribute('class', '');
      docked.setAttribute('class', 'hide');
      break;
    case 'docked':
      main.setAttribute('class', 'hide');
      docked.setAttribute('class', '');
  }
}

Of course we need to change our CSS file from above. First, we remove the media query part. Second, we add CSS definitions for .hide. After that, our CSS file looks like this:

.hide { display: none; }

Additionally, we need to add class=”hide” to the <div> with id=”docked” in the index.html file:

<div id="docked" class="hide">This widget is docked</div>

Note

Within the Vodafone Apps Manager, it is possible to start a widget in docked mode instead of starting it in application mode. Unfortunately,when starting a widget in docked mode, the widgetmodechange-event is not triggered. What we need to do is to call handleModeChange() ourselves when the widget is started, for example:

<body onload="handleModeChange()">

Summary

Which way you choose to add a docked mode to your widgets is completely up to you. If you are more comfortable with CSS, use CSS media queries; if you are more comfortable with JavaScript, add an event handler to your widget to provide a docked version of your widget.

Just keep in mind, that you need to tell the runtime, that your widget is “dockable” and then handle the different appearences of your widget corresponding to the different modes.

And that is it. Now you know what you need to do to add a docked mode to your widgets.

betavine

Mobile Web Widgets