How to Add Menu Items Using the BlackBerry Widget SDK

How-to

Using menu items effectively within your application is one of many ways to create a positive application experience, and helps to improve the overall engagement and usage of your application.

The BlackBerry® Widget API collection includes JavaScript® objects that can enhance the functionality of an application created using the BlackBerry Widget SDK. This collection includes the MenuItem object, which can be used to easily create contextual menus within your BlackBerry Widget application.

Creating MenuItem objects

As shown in the following example, adding a new menu item involves these two steps:

  1. Create an instance of the MenuItem JavaScript object;
  2. Use the Widget Menu API to add the object to the menu.

The keywords “Hello” and “World” are displayed as captions in the menu, and corresponding JavaScript functions named “callBackHello” and “callBackWorld” are called when the user selects the respective menu items.
This example also demonstrates how to create a menu item separator. Note the first parameter of the constructor is a Boolean value, indicating whether or not the MenuItem is a separator:

function createMenu(setDefault)
{
//Define Menu Item objects:
var mi_hello = new blackberry.ui.menu.MenuItem(false, 0, “Hello”, callBackHello);
var mi_separator = new blackberry.ui.menu.MenuItem(true, 1);
var mi_world = new blackberry.ui.menu.MenuItem(false, 2, “World”, callBackWorld);

//Clear existing menu items:
blackberry.ui.menu.clearMenuItems();

//Add a separator between two menu item objects:
blackberry.ui.menu.addMenuItem(mi_hello);
blackberry.ui.menu.addMenuItem(mi_separator);
blackberry.ui.menu.addMenuItem(mi_world);

//Optionally set default focus to a specified menu item:
if (setDefault)
{
blackberry.ui.menu.setDefaultMenuItem(mi_hello);
}
}

When to create the menu

The most straightforward way to add menu items in your Widget application is to call the “createMenu()” method from the “onload” event which occurs immediately after the browser rendering engine loads the page. This ensures that all required JavaScript has been loaded into memory, and that when the user is ready to interact with your application, the menu has been created:

<body onload=”createMenu()”>
You can also re-build the menu at any time by calling the createMenu function elsewhere on the page:
<button id=”btnMenu” onclick=”createMenu(1)”>
Re-build menu </button>
</body>

Menu and Super Apps

One of the key principles of the Super App concept is being able to provide a contextual user experience. This means allowing your application to make use of any conditional information in order to deliver content and services that are relevant within the current context.

The Widget Menu API provides an easy dynamic user interface you can adjust to the current context of the application. By displaying menu items that are relevant to what the user is currently doing, you can increase engagement and optimize the user experience by making it easier for your users to access the information they need within your application.

The best example of effective use of a contextual menu is one that most BlackBerry users are familiar with: the Messages application. The initial context of the Messages application provides a list of messages, and the menu on this screen includes items such as “Open” and “Search By.” When a message is opened, the context of the application changes – and so does the menu, becoming relevant to the user viewing a message. The “Open” menu item is removed, and the “More” and “Add to Contacts” menu items are added. This allows the user to easily access the application functionality that is most important to them at that point in time.

Another example of how you can contextualize the menu is having your application perform an automatic check for updates on startup. If a new version of your application is available, an “Update Now” item can be added to the menu. When selected, the menu item can redirect the user to either an over-the-air download page, or launch BlackBerry App World™ to your product download page.

Another final example of effective menu usage could be to use the Widget System API to detect whether the current BlackBerry smartphone has Wi-Fi® capability, and to provide an “Enable Wi-Fi” menu item in advance of your user accessing a high-bandwidth feature of your application.

Super App Developer Challenge

By making your apps context-aware, you can easily increase the usefulness and relevance of your services and deliver the Super App experience. Effective use of Menu items in your application is a great way to provide a highly contextualized user experience.

As a reminder, BlackBerry Widget applications can qualify for the BlackBerry Super Apps Developer Challenge. If you have or are building an application that you think meets the requirements for being a Super App, please don’t hesitate to submit it to the Developer Challenge before September 6, 2010.

About Adam S.

Adam is a Team Lead on the Developer Relations Team at BlackBerry. He manages technical relationships with ISVs as well as incubating the developing community ecosystem. Adam specializes in producing applications based on web and native technologies.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus