Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Message List Information


The Message List API will allow you to add items to the main message list much like BBM, Facebook and Twitter do. When clicking on the item it will then invoke your application.

Authors: Tim Neil, John Mutter

Known Issues

  • Uniqueness of IDs is not enforced. Adding duplicate items with duplicate IDs will cause problems.

Tested On

  • BlackBerry Torch 9800 v6.0.0.227
  • BlackBerry Storm 9550 v5.0.0.469
  • BlackBerry Bold 9700 v5.0.0.469

Requires BlackBerry WebWorks SDK for Smartphones v2.0 or higher

Have a problem with this extension? Log an Issue or contact the Authors

How To Configure The Extension For Use

  1. Locate your BlackBerry WebWorks SDK for Smartphone extensions directory using your File Explorer. Default path is C:\Program Files\Research In Motion\BlackBerry WebWorks Packager\ext

  2. Create a new webworks.message.list directory in the ext directory

  3. Download the source from this repository and unzip it to a location on your computer

  4. Using File Explorer browse to this extension's downloaded source code Smartphone\MessageList

  5. Copy the library.xml file from the downloaded Smartphone\MessageList directory to your new ext\webworks.message.list directory

  6. Copy the downloaded Smartphone\MessageList\src directory to your new ext\webworks.message.list directory

Your Directory should look like this:

  • C:\Program Files\Research In Motion\BlackBerry WebWorks Packager\ext\webworks.message.list\

    ** src

    ** library.xml

NOTE: Be sure to back-up this ext\webworks.message.list directory in your WebWorks SDK extensions directory before performing a WebWorks SDK upgrade. Simply copy it back into the ext directory after you have completed your SDK upgrade.

Required Feature ID

Whenever you use the below feature id in any of your WebWorks applications this extension will be loaded for use.

<feature id="webworks.message.list" />


static function onItemOpened;       // function(item : Item)
static function onItemMarkedRead;   // function(item : Item)
static function onItemMarkedUnread; // function(item : Item)
static function onItemDeleted;      // function(item : Item)

static void init(options : InitOptions); 
static void addItem(item : Item); 
static Item getItem(id : string);
static void removeItem(id : string);
static void markItemRead(id : string);
static void markAllRead(); //There will NOT be any "onItemMarkedRead" notifications fired
static Item[] getItems();  

/* TODO:        
static void updateItem(item : Item);

Options Summary

readwrite String guid;                  // Unique Identifier for your message store
readwrite String folderName;            // Name for the custom folder
readwrite String defaultNewImage;       // Default image to use for new items.  Must be local relative path
readwrite String defaultReadImage;      // Default image to use for read items.  Must be local relative path

Item Summary

readwrite String id;                    // Unique ID given to the item
readwrite String title;                 // Title of item
readwrite String description;           // Description of the item
optional readwrite String imageNew;     // Image to be displayed when the item is new.  Uses the default if not specified
optional readwrite String imageRead;    // Image to be displayed when the item is read.  Uses the default if not specified

Initialization Example

function init() {

    // Setup our listeners
    webworks.message.list.onItemOpened = onItemOpened;
    webworks.message.list.onItemMarkedRead = onItemMarkedRead;
    webworks.message.list.onItemMarkedUnread = onItemMarkedUnread;
    webworks.message.list.onItemDeleted = onItemDeleted;

    // Configure our options
    var options = { 'guid' : '',
                'folderName' : 'My Cool App',
                'defaultNewImage' : '/images/new.png',
                'defaultReadImage' : '/images/read.png',
                'defaulDeletedImage' : '/images/deleted.png'

    // Initialize the message list integration

function onItemOpened(item) {;
    addStatusMessage('Item Opened: ' +;

function onItemMarkedRead(item) {
    addStatusMessage('Item Marked Read: ' +;

function onItemMarkedUnread(item) {
    addStatusMessage('Item Marked Unread: ' +;

function onItemDeleted(item) {
    addStatusMessage('Item Deleted: ' +;

function addStatusMessage(message) {
    var list = document.getElementById('messageList');
    var item = document.createElement('div');
    item.innerHTML = message;
    item = document.createElement('br');

Add Item Example

function postItemToList() {
    var item = { 'id' : blackberry.utils.generateUniqueId().toString(),
            'title' : 'my title',
            'description' : 'my description'

Delete Item Example

function removeItem(id) {