MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Integrating event feed into applications

The Events view in MeeGo 1.2 Harmattan devices contains an event feed feature that displays a stream of updates from different applications such as e-mail clients, RSS readers and turn-based games. This allows the device user to keep up to date with latest messages or important information within one device screen, instead of scrolling through all the related applications.

The event feed can be a very useful feature for any application that needs to notify the user about ongoing events even when the application is not visible.

Application architecture

Although you can create an application that pushes its events into the Events view only when triggered by the user from the application UI, the most convenient way to integrate Events view with your application activity is to use Buteo Synchronization Framework (SyncFW). SyncFW allows the event feed updates to be processed independently of the application state. This means that it is not necessary for the application to be visible - or in some cases even running - to push updates to Events view. The rest of this section describes how to create applications that use event feed with SyncFW.

Events Feed API overview

When designing applications that use event feed, you can think of the whole setup setup as consisting of the following components:

  • UI application - normal Harmattan UI application, with event feed functionality.
  • Buteo Synchronization Framework Plugin - makes scheduled updates to the event feed.
  • Settings applet - allows the user to enable or disable the feed.

To work with the above components, you need to use the following technologies:

  • Events Feed API - for creating the application's event feed and feed items for it.
  • SyncFW plugin - loaded and run automatically by the Synchronization Framework according to the schedule that has been set up.
  • Settings API - for creating a feed settings applet in the device control panel.

These technologies are described in more detail below.

Events Feed API

Events Feed API - formerly known as MeeGo Touch Events API - creates an interface that allows applications to push feed items to Events view. The contents of a new feed item are defined as parameters in the addItem function.

A feed item consists of the following mandatory elements:

  • Icon - icon that is displayed with every feed item from this application.
  • Title text - title or header of the feed item.
  • Timestamp - timestamp for the feed item.
  • Source feed identifier - identifier for the feed from this application. This must be both unique and persistent. Typically the name of the application is sufficient.
  • Source feed identifier text - identifier text for the feed from this application. This is displayed in several situations on the device screen.

In addition, the following optional elements can be used:

  • Body text - main text of the feed item.
  • Footer text - end text in the feed item.
  • Images - list of a maximum of 3 images from the device file system or as image IDs from the current theme.
  • URL - defines the executed URL when the feed item is clicked in the event feed.
  • Video toggle - boolean trigger for video content in the feed item. When set as true, renders a video play button overlay on top of the first image in the images list.

The visible part of a feed item consists of icon, title, body text, footer, and timestamp. The images and the full body text are displayed when the user expands the feed item by clicking it. Feed items can be deleted with the removeItem function.

Synchronization Framework plugin

The Synchronization Framework (SyncFW) is a service that allows applications running on a Harmattan device to perform scheduled tasks. Applications using Events Feed API can use SyncFW to set up an update interval to push feed items to the Events view. When the set timer has eclipsed, SyncFW loads and runs the plugin. Then the plugin polls the application for new events and publishes them.

Synchronization Framework is used with a SyncFW plugin, which is a shared library (.so) file that is loaded automatically by the SyncFW daemon when it has been included and installed with the packaged application. The plugin must be named as lib<client_name>-client.so and placed into the /usr/lib/sync directory on the device during installation. The <client_name> functions as the plugin's identifier within the SyncFW, and therefore it must be similar to the client name that is defined in the XML files described below.

The SyncFW plugin loads the requested information from a set of XML files, which must similarly be included with the packaged application. The files must have the name <name_of_your_application>.xml and be placed into the following directories during installation, with the described content:

  • /etc/sync/profiles/client/ - for telling SyncFW the name of the SyncFW plugin (the shared library file) to associate with this application.
  • /etc/sync/profiles/service/ - for enabling SyncFW in online mode for this application.
  • /etc/sync/profiles/sync/ - for additional options, such as Accounts Framework interaction and setting up different update intervals for required times.
    Note: The profile name must be unique. It is recommended to use the package name, for example.

Settings API

It is recommended that you create a Control Panel applet to allow the user to control the behaviour of the event feed, or at least enable and disable the feed more easily. The most convenient way to do this is to use the declarative applet structure within the MeeGo Touch framework.

A declarative applet reads its information from two files during the installation process:

Developing for Harmattan
File Location on device Description
.desktop file /usr/share/duicontrolpanel/desktops for basic information such as the name and type of the applet, and its location in the device Control Panel
XML file /usr/share/duicontrolpanel/uidescriptions for describing the setup options and layout of the applet in MeeGo Touch declarative language

A declarative applet reads its information from two files when run by the Control Panel application. The declarative language allows you to create elements such as boolean toggles and sliders with integer values for this purpose. The values of the settings are automatically stored in GConf using the keys given in the XML file. You can then fetch the settings values using libgq-gconf.

For more information on Control Panel Applets, see Storing and managing application settings.

For more information on MeeGo Touch declarative syntax, see the libduicontrolpanel library in the Platform API reference.

Examples

To use Events Feed API in your application, add the following line into your application's project file:

CONFIG += meegotouchevents 

Then include the meventfeed.h header in your source:

#include <meventfeed.h>

To publish an event feed item, you need to create an instance of MEventFeed interface as the feed and add the ten-part item in it with the addItem function:

qlonglong  = MEventFeed::instance()->addItem(QString("icon name"),
                       QString("title text"),
                       QString("body text"),
                       QStringList(ImageList),
                       QDateTime::currentDateTime(),
                       QString("footer text"),
                       false,
                       QUrl("http://www.myurl.com/"),
                       QString("ApplicationID"),
                       QString("ApplicationID_Name"));

For a more complete example, see the following sections:

Things to consider when updating the events

The event feed feature is used by many different and simultaneously running applications. Keep this in mind when designing the way your application uses Events Feed API since too frequent and verbose updates can clutter the Events view display. Keep the updates brief and within a reasonable updating frequency. 30 minutes is a recommended starting point.

Erroneous behaviour from an application using Events Feed API hinders the usability of the Events view, which is a highly visible part of the device UI. Test cases where a lot of events occur within a small time frame carefully, and take tips from the way built-in applications work with Events Feed API.

Known issues and limitations

Events view contains a Refresh button. Currently, this button only refreshes feeds from built-in applications.

Currently, the installed SyncFW plugins are only run after the device has been re-booted. For further information on SyncFW behaviour during installation, see Example of updating Events feed from an application.

When testing your application, note that SyncFW only runs plugins when the device is connected to a WLAN or 3G network.