Welcome to the project. Your team will develop a mobile app for the BlackBerry 9000 smartphone for an “always-on” phonebook app.

The app enables a mobile user to interact with a phone book stored on an online database server, and shadowed locally on the BlackBerry smartphone.

1. Familiarize yourself with the overall project.

2. Pick your team.

   • One team member email to godfrey@cse.yorku.ca with the subject “CSE2041 Project Team”.

     • CC your the other team members.

     • Say in the email the team members by name, student number, and CSE-account.

     • State a team name. Rah, rah! Go team, go!

3. Build a browser-based (e.g., Firefox) version of your Phonebook app. (Lab #4 was the start of this.)

   • Have the HTML of the app stay put. Use AJAX to update the DOM.

   • Add the functionality that the project asks for.

     Of course, you will not have a local storage of the contact list as you will in the full app.

   • Use this as a testbed for your design, both for functionality and for look and feel (UX).

   • Ultimately, your phonebook app should work both from your BB app and from this webapp.

4. Read over the BB Widget Trial.

5. Start working out your design.

   • How do you want the interface to look? What should the user experience (UX) be?

I will try getting the BB phones set up for check out during this lab...but may not make it. In any case, there is much to do beforehand.

Work on the project in between project lab #1 and this lab — project lab #2 — of course. Also, you have another week after this lab — project lab #2 — to finish.

6. Do the BB Widget Trial.

   • Check out your BB phone and load the trial app.

7. Do the PIM Widget exercise.

8. Work out a reasonable solution to synchronizing the local BB database and the server-side database.

9. Finish your design.

Ideally in the week after this lab before the project is due, all you will have left is to polish things and the Project Report.

• Each team will have an assigned phone.

• You will be able to check your team's phone out from the lab monitor in #1006.

  • You will need to sign out the phone, and leave a valid ID with the monitor — a driver's licence, a York student card, ... — which you will get back when you return the phone.

  • Do not leave the building with the phone.

  • Tech staff will lock your CSE account if the phone goes missing! And that would not be very convenient...

The app must support of the following use cases.

1. User to look up the phone number of a given name prefix.

2. User to edit or delete an entry returned by the look-up use case.

3. User to insert a new entry.

The app must use the online server whenever available, and fall back on the local database when there is no connectivity.

What information should your phonebook entries keep? As in Lab #4.

You should deliver three things by the due date of this project.

1. working BB app. The BlackBerry that was assigned to your team, with the app loaded on it.

   • Just leave your functioning app on the phone when you return it to the lab monitor that last time.

2. project report. Submit the project report.

   The report file — in pdf format — can be submitted using the command:

   submit 2041 proj report_file

   The report is meant to describe your execution of the project to someone who is familiar with the project; e.g., a fellow student who is also executing the same project, and writing a similar report. Hence, the report should focus on your own experience and efforts; i.e., what you actually did, rather than on general description. It is expected to be very brief, to the point, and made up of at most two pages (excluding source listings).

   The report should include three sections.

   1. overview. Describes the overall architecture, design, and implementation issues, and a self-assessment of any limitation or deficiencies,

   2. team. The cse# and name of each team member, an explanation of how the work was divided, and how was communication and consistency maintained, and the main lessons that were learned from this project,

   3. source files. Listings of all HTML, CSS, JS, Java, and CGI files that make up the project. Make sure the code is properly formatted.

3. project files. Submit your project files.

   These include the following.

   1. widget source files. HTML, CSS, JS, XML. In one archive.

   2. widget cod file. Must be signed.

   3. server-side files. CGI, Java. In one archive.

   Use

   submit 2041 proj files...

The project will be evaluated based primarily (80%) on meeting the specs — these include system functionality and report contents and on its internal quality — design, style, code, etc.

The remaining (20%) is based on how your project compares with those of other teams.

It is recommended that you approach this project in an iterative manner.

1. Create a browser-based — e.g., Firefox on the PC — “widget”.

   • Get your database connectivity working.

   • Program in your functionality for your phonebook app.

   • Work out your design and the look and feel of your app.

2. Get things working in the Eclipse emulator.

3. Then get things working on the BB phone.

For the widget, do things in steps.

1. Create a remote widget, one that works with the remote database. This widget uses form submission and AJAX to enable the user to add, edit, delete, or search.

2. Create a local widget, one that works with the device's PIM. This widget has the same interface and functionality as remote, but it uses the PIM API to access the local database.

3. Merge the two widgets into one. After all, they have the same user interface, and differ only in their database connection. The user can click a radio button on the HTML page to indicate whether the remote or the local database is to be used.

4. Automate the database selection, by figuring out how to synchronize the two databases.

Test the procedure for developing, testing, and installing an app.

Elect one person to be the team's “packager”. He or she should get and authenticate a signing key. An app must be signed to be loaded onto the BB Bold 9000 (or into the simulator).

Go to BlackBerry Code Signing Keys and follow the instructions.

Note: You do not need privileges for the secure element.

Once you receive the three CSI files from RIM, use the SignatureTool in the SDK's bin/, as per instructions, to make a sigtool.csk and sigtool.db.

Make a copy of your sigtool.csk and sigtool.db somewhere safe and permanent. (Say in your home directory.) You will need to copy them into the SDK bin/ of whatever machine you are working on to have that signing key. Do not only leave them on the Windows machine in the lab; they will vanish.

Remember (and/or store safely somewhere) the PIN you used to create the key and the password you set for it.

We will be using Ripple to load and package our web-app as a mobile app for the BB. Ripple is an extension for the Google Chrome browser.

1. Start up Google Chrome.

2. Go to URL Download for HTML5/WebWorks — BlackBerry HTML5/WebWorks.

   1. Select the tab BlackBerry OS 7 and earlier.

   2. Click Ripple Emulator 0.9.10 beta.

3. Chrome will download it and then refuse to install it.

   1. Accept Chrome's refusal.

   2. Open a tab for Tools > Extensions

   3. Find the ripple_ui.crx that was just downloaded (in your Downloads/ folder) and drop it on the Extensions tab.

      Chrome will then install the extension.

4. In the Extensions tab, check the boxes for Enabled, Allow access to file URLs, and Developer mode up top.

5. Ripple needs to be “primed” before you can work with it. That is, it wants you to check-mark that you agree to its license.

   1. To do this, you have to visit a web “app” at a server over the internet.

   2. You can use www.cse.yorku.ca/~godfrey/app/HelloWorld/index.html for instance.

   3. Accept the licence agreement.

   4. Choose WebWorks as the platform.

6. Click the Ripple icon to the right of the URL bar in Chrome and choose Enable.

   1. This should put you into emulator mode! You should see the “HelloWorld” app within a phone screen.

   2. Choose Blackberry Bold 9700 under Devices. That is the closest emulator to the actual Bold 9000's we are using.

   You can do a lot with the emulator for working up your project.

For installing a webapp you have built as a “native” app on the phone, it needs to be packaged.

First, you need your webapp's files — the HTML, CSS, and JS files — collected together in a folder (and perhaps, subfolders). Of course, you have done this already if you have it live on the web server under your www/.

Additionally, the webapp folder needs a manifest, an XML file named config.xml. This tells the phone — say, the Bold 9000 — information it needs to install the app. Grab www.cse.yorku.ca/~godfrey/app/sisStat/config.xml as a template. Change the information to your own. You can easily find more on the configuration directives searching on WebWorks and config.xml.

The packaging process involves archiving the files along with the config.xml into an archive (.zip) file, processing the archive file to make an phone “executable” of the app (one or several .cod files), and signing the .cod files. A .jad file is also made — in the OTAinstall folder, for over the air — which can be downloaded on the phone's web browser to trigger the loading of the app (via .cod files).

One can use Ripple to build the package. It takes care of the various steps involved in the archiving and signing, so one does not have to do these various steps by hand.

Ripple will only build something from the local file system. It will not build from a URL to a server somewhere else! For this, Start Services under Ripple's Build tab. Now Chrome is running a miniature, local web server for you on port 1190! The root of the web directory for this server is RippleSites/ under your home directory on that Windows machine. E.g., C:\Documents & Settings\csexxxxx\RippleSites\. So, make such a directory.

For each folder of each webapp you are working on — e.g., sisStat — you will need to copy that folder locally under your RippleSites/ folder for Ripple to be able to package it. Then, you can access it at the URL http://localhost/sisStat/index.html (assuming your main HTML “root” page is index.html).

You will also need a folder to tell Ripple where to put the package. For myself, I made a folder called RipplePackages/ next to my RippleSites/ folder for this purpose.

In Ripple, open Settings under Build to fill these values in.

• SDK Path
• Project Root
• Archive Name
• Output Folder
• Password

The SDK Path is for the Webworks SDK. Find what it is by looking under C:\Program Files\Research in Motion\ for it. The archive name is the same as the name of the app as stated in the config.xml. The password is the one for your signing key.

After you have Settings set up, clicking Package & Sign will make you a signed package!

To upload the app onto the phone via the package, you will need to move the OTAinstall folder from it to under, say, your PRISM home director's www/ so that the www.cse.yorku.ca HTTPD server can serve it over the air. Point your BB Bold 9000's web browser at it, select the .jad, and the app will load.

Alternatively, one can choose Package & Launch from Ripple's Build. Assuming you have selected 9000-5.0.0.xxx for Simulator under Settings, Ripple will package and sign the app and send it to a software simulator of the BB Bold 9000 phone.

The simulator actually simulates the workings of the phone device on the computer. It is rather slow, but presents a rather accurate picture of how the app will behave on the actual device. (This is different than the light-weight emulators within Ripple. These give you a view of what your app would likely look like on the device, do let you do some testing and debugging, but are not simulating how your app would actually run on the device.) This is an alternate way of testing your app wihtout always needing to upload it to the physical phone each time.

You can check out your phone from the Lab Monitor at the desk in #1006. You should not leave the building with it!

Use the phone unit # assigned to your team! That is where your app(s) will be, and what I grade for you team in the end. If you swap around phones, chaos ensues!

teams

Steal the sisStat webapp from www.cse.yorku.ca/~godfrey/app/sisStat/. Play with it in the Ripple emulator. Rewrite the config.xml to have your information. Build and launch it in the BB Bold simulator and play with it there. Build and sign it and load it onto your actual BB Bold.

Create a new BlackBerry Widget Project in which you can explore accessing local features. Its main HTML page should have buttons that trigger the JavaScript explorations shown here.

This widget uses the Widget API to access the “Personal Information Manager”, PIM, onboard the BlackBerry smartphone. As such, make sure you add a feature permission in the widget's config.xml for every backberry.pim.object that you use.

To create an address object:

    var myAddress = new blackberry.pim.Address();
    myAddress.address1 = "2020 CSEB";
    myAddress.address2 = "4700 Keele Street";
    myAddress.city = "Toronto";
    myAddress.country = "Canada";
    myAddress.stateProvince = "Ontario";
    myAddress.zipPostal = "M3J 1P3";
    

To create a contact object:

    var contact = new blackberry.pim.Contact();
    contact.firstName = "Net-Centric";
    contact.lastName = "Computing";
    contact.workAddress = myAddress;
    contact.save();
    

After you run this fragment, go to the built-in “Contacts App” and verify that an entry has been added.

To search and/or iterate over the PIM database, use the following.

• Use the blackberry.find.FilterExpression object. Note that every entry in the PIM has a unique uid. The Blackberry Widget API has several examples on using find.

This section is for frequently asked questions and will be updated as needed to provide extra information, help, and clarifications.

When I try accessing my CGI via AJAX from an HTML page I have loaded in the browser by file://, it always fails, returning a status of 0, not 200. But it works accessing the HTML page from a server by http://. What is the problem?

This is due to security features in Web standards called cross-domain blocking. Your HTML page appears to come from another domain than the CGI does.

The CGI can override this, by adding the following headers in its response.

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, POST, OPTIONS

Access-Control-Allow-Headers: Content-Type