Mobile/PhoneGap/Tutorial

Building the Wikipedia Android app using the cross-platform PhoneGap framework, San Francisco Hackathon January 2012

These notes are a reference to help you build the Wikipedia Android app and start using Phonegap. It helps to also watch the accompanying video. For iOS build instructions looks 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 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 (r16 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 1" - choose the Android version defined AndroidManifest.xml (see here)
6. Wait for the emulator (from step 4) 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 Zepto, which is jQuery-like and jQuery-compatible.

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. Go to js/chrome.js
   1. at the top, menu_handlers mapping action name to a function. 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, navigate to the Special:Random page.

en.m.wikipedia.org - you'll need to prepend the m to get a mobile version of the site.

1. Look in the app.js file to find methods you need for navigation.
2. Then go back to chrome.js and make your function: app.navigateToPage("http://en.m.......Special:Random');
3. Save
4. Run
5. In console, you see it installing, starting, etc.
6. 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 work for any language. (note: use app.urlForTitle)
  • 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. the NearMePlugin lets us use that geo stuff in Android. But in the long run we'll be shifting stuff all to JS/CSS.

• 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 Google Maps integration. But we're moving away from 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.