Creating Blackberry Apps with WebWorks and BSP – P...

former_member186695 · ‎06-07-2011

Introduction

We recently had a workshop with a RIM Solution Architect to evaluate the feasibility of using Blackberry’s WebWorks Platform which can speed up mobile app deployment on Blackberries and Playbook. The platform promises that you can create web applications that run on Blackberries using traditional HTML, CSS, Java Script and images. You can read more about the product here (http://us.blackberry.com/developers/browserdev/). What we ended up doing was creating a BB app (we like to call it Asset Tag App) with two screens/pages, which would use a custom function module wrapped around standard FMs which imports an asset/equipment number and returns related details (assigned owner, location, equipment description etc). The first page would be our landing page, where the user can enter an asset number and the second page would display the details pulled out of the system. I’m going to break this up in three parts. ** [Part 2 | Creating Blackberry Apps with WebWorks and BSP – Part 2] – will cover how to create the BSP application, basically embedding the pages we created in Part 1 ** [Part 3 | Creating Blackberry Apps with WebWorks and BSP – Part 3] – will cover registering your keys, signing the application and deploying on the mobile device h3. Code Signing Keys Before we start with the installation and app creation, I recommend that you apply for your code signing keys now! It takes RIM 1-2 days to process your request, so while you create and play around with your first app on the simulator you’ll receive couple of emails from RIM. Currently RIM doesn’t charge anything for the keys but the process does require a valid credit card. You can apply for the keys here (https://www.blackberry.com/SignedKeys/). By the way, and this is very important, note down the PIN you enter while applying for the keys, you’ll need this to enable the keys (you’ll receive three of them). There is no PIN recovery mechanism available, so if you forget, you’ll have to apply for the keys again which is a bit frustrating. I’ll let you in on the next steps later on.

Blackberry WebWorks

You can get ‘getting started’ details here (http://us.blackberry.com/developers/browserdev/eclipseplugin.jsp) at the blackberry.com website. In our case, we went with the Eclipse route (Microsoft Visual Studio route is also available), the first step is to install the latest JDK and then the Eclipse with WebWorks plug-in which is also available at the before mentioned link. It might be a good idea to change the default location to a simple one, as you’d be referencing the locations within pretty often. Once the installation is complete it’s a good idea to check the environment variables to make sure the JAVA_HOME is pointing to the one you recently installed (in case you have older version installed). This should look something like C:Program Files (x86)Javajdk1.6.0_22. Plus add the following directories in the PATH variable, if they don’t already exist. The first two are required for successful execution of the simulator. The third one is for javaloader.exe program; we’ll talk about this more later on. h3. Create project Run your Eclipse.exe and start a new project by going in to the file menu or choose the (New) button right under the File menu, following screen will appear

If you choose ‘Project’, the following wizard will start prompting for type of project you want to start. Select BlackBerry WebWorks Project and click next. Or you can directly choose the ‘Blackberry WebWorks Project’ (if available – the first time you run Eclipse the WebWorks Perspective is not active, so most probably you won’t see this option but I do recommend that you activate the perspective).

The next screen will prompt you for the project name and the starting page (index.html by default). For our project, I entered AssetTag for the project name and changed the start page to MainView.htm.

Click on finish and the project will be created with some basic folders and files.

As a side note, the WebWorks getting started window opens everytime you create a new project. The ‘APIs’ tab above gives you insight to all the APIs you can make use. Once you close it, you can access this help again through the ‘i’ button also highlighted above. Double click on the ‘config.xml’, this is called the configuration document for the application. You can get more details on each of the section by clicking on the help button on any of the sections like overview, permissions etc. I’ll just let fill in/update the important ones. For our app I updated the name in the overview section to Asset Tag; I have an icon for our app which I’d like to display instead of the default icon which needless to say doesn’t look cool. In order to do this, we need to create a sub folder ‘img’ under AssetTag project. The best way of doing that is to go to the project folder of your AssetTag app from your windows explorer. You can find the location of the project folder by right clicking on the AssetTag node and at the bottom of the context menu click on properties or press Alt+Enter.

Once you create the sub folder, we actually need to put three images there

First one for the application icon:

(SAPIcon.png),

Second one for the home page banner

(HomePageHeader.png)

And the third one for the asset details page

(AssetDetailsHeader.png)

Once you put the images in, go back to Eclipse, select AssetTag project and hit refresh (F5). The ‘img’ folder will/should appear with all three images, which can now be referenced within our application.

Now back to associating an icon with our application. In the right side, within the ‘Configuration’ section, click on the ‘Browse…’ against the ‘Icon’ field and point to the ‘SAPIcon.png’ image. Custom Header field is required to be filled with value “RIM-Widget:rim/widget” to enable any use of RIM provided APIs (we will be adding a custom menu item). Select the check box against ‘Use focus-based navigation on trackpad/trackball smartphones’. Entries would look something like:

Permissions

There are two ways of accessing ‘Permissions’ one is from the tab at the bottom of the frame

And the second one is from the ‘Permission’ section which is right next to the ‘Information Section’

Both will lead you to same screen

Here we need to set the permissions for the app. We are just going to add what we need to get the job done, I’m going to add one feature to the existing node ‘Local’ which is blackberry.ui.menu (You’ll see the usage below). If you rather not deal with what permissions to add, feel free to add all of them. We also need to add a new domain ‘*’, to enable our application to access all web pages without restriction. Needless to say, you can limit that as well to the specific domain you’ll be accessing. The permission tab should look like:

Start creating your page(s)

As much as I would’ve loved to have a UI designer delivered with WebWorks, I was greatly disappointed to hear that all development would have to be carried out the ‘old’ way. Bad news for some and good news for all the HTML gurus out there who can leverage this and make the apps look cool! As I mentioned earlier, we will be developing two simple screens/pages. The first page would have a banner at the top, an input field and a button to submit request. The second page would have a banner on top and couple of fields listed in a two column table. Here is the HTML for the first page (MainView.htm):

So your final package would look like the following:

<!DOCTYPE
html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Asset Tag</title>

function loadMenuItems()

{

var mi_search = new blackberry.ui.menu.MenuItem(false, 1, "Search Inventory", goToDetails);

blackberry.ui.menu.clearMenuItems();

blackberry.ui.menu.addMenuItem(mi_search);

}

function goToDetails(){

window.location = "AssetList.htm";

}

</script>

</head>

<tr>

</tr>

</table>

<tr>

<td align="center"><p>Inventory Asset Tag</p></td>

</tr>

<tr>

</tr>

<tr>

</tr>

<tr>

</tr>

</table>

</body>

And for the second page (AssetList.htm)

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

function loadMenuItems()

{

if (blackberry.ui.menu.getMenuItems().length > 0)

blackberry.ui.menu.clearMenuItems();

var item = new blackberry.ui.menu.MenuItem(false, 1, "Back", backToSearch);

blackberry.ui.menu.addMenuItem(item);

}

function backToSearch()

{

window.location ="MainView.htm";

}

</script>

</head>

<tr>

</tr>

</table>

<br>

<tr>

<td width="30%" id="itemDesc">Description:</td>

<td id="itemValue">T-510 Lenovo laptop</td>

</tr>

<tr>

<td width="30%" id="itemDesc">Owner:</td>

</tr>

<tr>

<td width="30%" id="itemDesc">Location:</td>

</tr>

<tr>

<td width="30%" id="itemDesc">Location Description:</td>

<td id="itemValue">US - Head office</td>

</tr>

</table>

</body>

</html>

And finally a simple CSS file named 'Inventory.css' (I've created this one in a separate folder 'css', just like 'img' folder)

@CHARSET "ISO-8859-1";

p.sansserif{

font-family:Arial,Helvetica,sans-serif;

color:white;

font-size:150%;

font-weight:600;

}

#itemDesc{

font-family:Arial,Helvetica,sans-serif;

color:#63759C;

font-size:25;

font-weight:100;

}

#itemValue{

font-family:Arial,Helvetica,sans-serif;

color:Black;

font-size:25;

font-weight:100;

}

So your final package would look like the following:

Simple! Only thing worth noticing here is the java script mentioned in the two pages. In both cases, we are adding one item to the blackberry menu and we are doing so in the body onload. On the first page it will call function goToDetails which in turns opens the second page. On the second page it will return the user back to the search page. It is important to note that the RIM menu/menu item API won’t work without specifying “RIM-Widget:rim/widget” as the custom header in the configuration. h3. Test it out Okay, even before we test it out in a BB simulator or in an actual Blackberry, let’s give it a go in a HTML5 compatible browser. This is of course a simple app, but for complex scenarios it is always easier to debug and trouble shoot in the local browser. To that, you simply need to drag n’ drop the htm file into the browser and see if how it works. This should give you a goodlook and feel for the app. Resize the browser window you’ll see something similar to what you’d actually see on the BB.

The menu buttons are of course not available here, so for that you’d have to test this out in the BB simulator. To do this simply click on the ‘Run’ button from the application bar. If you’re running this for the first time you’ll be prompted with the following popup:

Select ‘Blackberry WebWorks’ and click ok. After successful compilation a command window running the MDS should pop open along with the BB simulator. It takes a little bit of time for the simulator to start depending on the performance of the machine you’re running it on. But it should load successfully (if you’ve made sure everything is configured as mentioned earlier) and eventually opening up the application as well. In case the application does not run automatically, you’ll have to do it manually by going to the download folder or opening the tray to see all applications available. In case your MDS does not start automatically upon execution, you can run it manually from the service manager tab located at the bottom frame. If it’s not visible use the ‘Window’ menu to display it.

Once the simulator loads, it should automatically kick off the application. When you back out of the application you’ll notice the icon we associated with the app (in the download folder), click on it to launch the app to execute. If we wouldn’t have associated the icon, the app would’ve came up looking something like a generic exe icon you see below right next to our Asset Tag app.

I hope you’ve enjoyed and learnt something new out of this. In the next blog, I’ll show how to embed these pages in BSP, so we’ll have live data from an SAP system. Meanwhile if you have any questions please let me know. At the end, I’d like to thank to Martin Lang (SAP), Rana Puri (RIM) and Subrah Kappagantula (SAP) for their contribution.