# Adding a docked mode to your widget

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

- 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 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.