Download source code - 11.5 KB

Introduction

Quite a few readers have requested more information about the development for BlackBerry devices. In this series of articles, I will walk you through the creation of an end-to-end application that will be a BlackBerry version of the web application I talk about in these blog posts: End-to-end ExtJS application (Part 1) and End-to-end ExtJS application (Part 2).

In case you haven’t read the articles, the web application I built is a very simple Knowledge Base System. These are the basic usage scenarios I had established for it:

Browsing a collection of articles stored in a knowledge base repository.
Creation, edition, or deletion of articles (any user can view, create, edit, and delete any article).
View an article. The article’s visible attributes are:
- Title
- Body
- Tags, as a way to connect the article to specific topics
- Author’s name
- Date published

Requirements

For the BlackBerry application, I will skip the creation, edition, and deletion of articles, and focus on browsing and viewing existing articles. So, my first take at the usage scenarios produces this list:

Searching a collection of articles stored in a knowledge base repository:
- By title
- By tags
View an article. The article’s visible attributes are:
- Title
- Body
- Tags, as a way to connect the article to specific topics
- Author’s name
- Date published

Building Blocks

Besides the BlackBerry application, I will use a .NET HTTP handler on the server side, to channel all communications between the device and the article's database.

User Interface

I’ve found that when I enter the construction phase on a project of this kind, it always helps me if I have an idea of how the user interface is going to look. Keeping my “product owner” hat on, I am going to help my coder alter ego by putting together a few rough UI prototypes.

First comes the Home Screen. This will be the main screen of the application, and I expect it to be a door into the different search features that will be available as well as the application settings.

Now, to the Search Screen. This screen will allow our users to initiate an article's search by typing one or more words belonging to the article’s title.

The Browse Tags Screen will display a list of the existing tags in the database. Beside each tag, there will be a count of the articles the tag applies to.

The Results Screen will show a list of articles that satisfies the criteria entered on the Search Screen. It will also allow our users to click on any listed article in order to view it.

The Article Screen will show the viewable attributes of the article that was selected on the Results Screen. This is where the user gets to read the article.

The Options Screen will allow the user to change the application settings. In terms of settings, so far, I can only think of the URL our application will connect to in order to talk to its server counterpart, and the number of references to recently viewed articles to keep cached on the device.

Implementation

It looks like I can switch to “coder” mode and get started on writing our device-side code. I will first take care of creating a stripped-down version of the application that does nothing but display the main user interface elements. This will allow me to validate my UI prototypes and serve as a foundation I can build upon later when I have to add the networking routines and the code that will take care of loading and saving the application settings. In this article, I will create the Application class and the Home Screen. I will tackle the rest of the screens in my next article.

The Development Environment

The IDE I will be using is the BlackBerry JDE version 4.3.0. You can download the IDE as well as its documentation here.

The Application Class

Let’s begin with the Application class. This class will be the entry point into our application, and will be in charge of creating the Home Screen.

package KnowledgeBase;
import net.rim.device.api.ui.*;
class KbAppplication extends UiApplication {
    
    KbAppplication() {
        HomeScreen homeScreen = new HomeScreen();
        this.pushScreen(homeScreen);
    }
    
     public static void main(String[] args){       
       KbAppplication myApp = new KbAppplication();
       myApp.enterEventDispatcher();
    }
}

Worth highlighting is the constructor of the class, which is where I create an instance of the Home Screen and push it to the display stack.

Home Screen

The Home Screen displays a list of search options.

One interesting detail here is that I'm extending the ObjectListField class in order to be able to add a small icon to each of the search options.

private class MyObjectListField extends ObjectListField {
        
    private Bitmap icon = Bitmap.getBitmapResource("img/star_green.png");
    
    // We are going to take care of drawing the item.
    public void drawListRow(ListField listField, Graphics graphics, 
            int index, int y, int width) {
        if (null != icon) {
            int offsetY = (this.getRowHeight() - icon.getHeight())/2;
            graphics.drawBitmap(1,y + offsetY, icon.getWidth(),
                    icon.getHeight(),icon,0,0);
            graphics.drawText(mainMenuItems[index], 
                icon.getWidth() + 2, y, DrawStyle.ELLIPSIS, width);
        } else {
            graphics.drawText("- " + mainMenuItems[index], 0,
                y, DrawStyle.ELLIPSIS, width);
        }
    }
};

The navigationClick method is where I’m going to determine what search option will be displayed.

protected boolean navigationClick(int status, int time) {
    // Determine which menu item was clicked.
    int selected = menu.getSelectedIndex();
    switch (selected) {
        case 0:
            // TODO: Show the Search Screen.
        break;
        case 1:
            // TODO: Show the Browse Tags Screen.
        break;
        case 2:
            // TODO: Show the Results Screen and load the 
            // recently viewed items.
        break;
    }
    
    return true;
}

What’s Next

This is it for now. In my next article of this series, I will build the rest of the screens and lay the foundation for adding the networking code as well as the code to save and retrieve the application settings. Once I cover the device-side code, I will move to the server side and take care of the pieces that will handle the communications with the device.

End-to-End Real World BlackBerry Application, Part 1