Mobile/PhoneGap/Tutorial

Note: The PhoneGap app is officially in maintenance mode, and no new features will be added. We've switched over to Native app development for major platforms.

These notes are a reference to help you build the Wikipedia Android app and start using Phonegap. For iOS build instructions look here.

Target audience: people who do not yet know how to get started with PhoneGap

Goal of tutorial: building Wikipedia Android app using the cross-platform PhoneGap framework with Eclipse

Note to students: Laptops will be more useful than phones; we'll be talking about the Android dev environment.

About PhoneGap

About PhoneGap: http://phonegap.com/about

• http://phonegap.com/about/features
• http://developer.android.com/index.html

Our Wikipedia application: https://market.android.com/details?id=org.wikipedia

Your JS/jQuery etc will be the same crossplatform, but you'll have to download & use different platform-specific devtools and SDKs.

• example: iOS: xcode, iOS SDK

The Phonegap site has tutorials for each of these.

Setup

Setup pre-requisites for building the wikipedia application - download and install:

1. Make sure you have a Java SDK 'sun-java6-jdk' and Ant installed.
2. Download Android SDK http://developer.android.com/sdk/index.html . Grab the latest SDK (r20 as of now). Unpack it with Archive Manager or whatever.
   1. If you on 64bit linux system you'll need 'ia32-libs'
   2. Run 'tools/android' from the command line from wherever you unpacked this.
   3. A GUI window pops up. Under 'Tools' folder, select Android SDK Tools, and Android SDK Platform-Tools. Under 'Android 2.3.3' select 'SDK Platform' and 'Google APIs'. Click the install button to install them.
   4. This triggers a download that may take several minutes. If the download hangs, you may have to kill and restart tools/android, as it doesn't seem to recover nicely from an interrupted connection.
3. Build an AVD (Android Virtual Device) or use your device (Building an AVD lets you use the android emulator - or else you could just use your android device to test).
   1. In the Tools menu, pick "Manage AVDs". This brings up the AVD manager.
   2. Click "New..."
   3. Name your Emulator and select the target platform: Google APIs API Level 10
   4. set SD card size, say, 128 megs
   5. Enable snapshotting - it makes emulator starts fast after the first time
   6. Other defaults are fine!
   7. Hit Create AVD.
   8. Now, click "Start...", then in the Launch Options window, hit "Launch" (the default launch options will work).
   9. You'll see a window pop up & boot. First time, allow 5-20 minutes for booting the virtual phone. Get your power cords, and proceed to the next step while the phone boots up.
4. Fork/Clone- https://github.com/wikimedia/WikipediaMobile. You may need to install git first. Go to wherever you want your source code, go ahead and clone it.
5. Setup the project:
   1. On the command line, change to the folder you've cloned the WikipediaMobile source to.
   2. Use the command 'git submodule update --init' to pull in dependencies
   3. Use the command '<sdk-path>/tools/android update project -p .' to setup the android project (where <sdk-path> is the path you installed the SDK to)
      • You may have to specify the target by appending "-t 8" - choose the Android version defined AndroidManifest.xml (see here)
6. Wait for the emulator (from step 3) to show the phone's home screen, and then: on the command line, in the project folder, type 'ant debug install'. Assuming the emulator has started up, the android app will be installed there. Go to the apps menu within the emulator and launch the Wikipedia app.
   1. If 'ant debug install' fails saying the device is "offline", turn the emulated phone off and back on again. Shuting down the emulator for the first time may take several minutes. If it doesn't shut down at all, kill it (and also kill the tools/android window).
   2. Note that if you notice an old version of the app is being installed try using the command: "ant uninstall && ant clean && ant debug install" to ensure a clean occurs first.

Project Structure

1. Assets folder. How the app is structured: Very little Java -- mostly HTML, CSS, JS. The Package Explorer -- look at the assets/www dir, (HTML/JS/CSS). Inside the platform-specific folders, you find overrides -- you won't have to worry about them right now. The prime code is within the js folder. Look at the app names - self-explanatory. Each of the functions in an app is in its own file, usually. There's jQuery, which is used extensively.

First Exercise

Change default color of searchbar. (Maybe give them a clue as to what file to look at (index.html/app.css)).

class="titlebar" .titlebar background

Second Exercise

Add a Random Article menu item.

1. Look in the HTML. We define the project structure in HTML.
2. Look at assets/www/index.html and open it in your favorite editor. This is a single-page app. Structure is self-explanatory. To add a menu, look at <menu id="appMenu" .... >
3. Add a command with an id and an action="show-random-article"
   1. The action is how you bind this to a proper function.
4. Locate the menu_handlers variable (at time of writing this is in platform.js but if you cannot find it it may have moved)
   1. menu_handlers maps action names to function.s So, add show-random-article to this list.
5. Save and run (using ant debug install)
6. Look at the console -- adb logcat (showing what is happening on the device).
7. Look at the emulator. The menu item shows up on the main page! (Not localised with a proper message yet.) So we know the code is being executed.
8. So, what you want to actually happen is, when the user clicks, use the API 'list=random' to retrieve a list of 1 random page, then navigate to it.
   • http://en.wikipedia.org/wiki/Special:ApiSandbox - you can build a MediaWiki API query here interactively
9. Look in the app.js file to find methods you need for navigation.
10. Then go back to platform.js and make your function:

app.makeAPIRequest({
	action: 'query',
	list: 'random',
	rnlimit: 1
}).done(function(data) {
	app.navigateTo(data.query.random[0].title);
});

11. Save
12. Run
13. In console, you see it installing, starting, etc.
14. Emulator: hit More, hit Random Article.

There you go!

note: if you find that your making changes but not seeing them in the emu. 1) ant debug uninstall 2) ant debug clean 3) ant debug install

Supplementary EXERCISEs

• There are bugs in this implementation.
  • Customize it to load only article pages (note: check params in ApiSandbox)
  • Show how translations work.(Talk about 1. message keys 2. Existence of translatewiki.net as a project (not too detailed) 3. mw.Message + <msg> tag)

Other resources

• https://meta.wikimedia.org/wiki/Mobile_Projects/Contribute#Apps
• At end: go into the feature backlog, such as photo upload. http://meta.wikimedia.org/wiki/Mobile_Projects/features
• IRC channel: #wikimedia-mobile on Freenode
• Mailing lists: https://lists.wikimedia.org/mailman/listinfo/mobile-l and https://lists.wikimedia.org/mailman/listinfo/wikitech-l

A footnote about the /src folder

• Look at the /src directory, and that has the Phonegap plugins. Anything you can do on Android, you can do on Phonegap. Look at com.phonegap.* -- those are readymade, from the official repo.

• The last one is our namespace where we have our code. This is the only Java code here. Most of this is plugins for PhoneGap, plus a native Android search provider. The rest of the app is all HTML/JS.

• Logging - you can read the log from the android device by typing '<sdk-path>/plattform-tools/adb logcat' in the command line. You can use console.log in javascript to debug and it'll turn up righ there.

QUESTION: purpose of PhoneGap -- you don't have to write Java. So why are you telling us about Java? Well, for a few things you need Java, like search integration. But we're able to use relatively little of it. There are standards for most mobile stuff like GPS where we don't need to do anything Android-specific. Additional glue for nonstandard stuff.