Tutorial practice from 19 Jan 2012

These notes are very messy

Practice for mobile tutorial for SF hackathon 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 Presenter: Tomasz. Attendees: Daniel Kinzler, Yuvi Panda, James Alexander, Sumana Harihareswara NOTE to Sumana: get USB sticks to Tomasz ahead of time Laptops will be more useful than phones; we'll be talking about Android dev env 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 Setup pre-requisites for building the wikipedia application - download and install:

   0) If you don't already have Eclipse, here's a download link for generic Eclipse: http://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/indigosr1 (Download links on the right)

   1) Download Android SDK http://developer.android.com/sdk/index.html .  The Android SDK: http://developer.android.com/sdk/index.html (Note that you should download the SDK and then use its download manager to actually download the required packages)  Grab the latest SDK (r16 as of now). Unpack it with Archive Manager or whatever.

   2) Configure Eclipse http://developer.android.com/sdk/eclipse-adt.html#installing (It's an eclipse plugin, you can find instructions there for installing it from inside eclipse itself).  Go to "Install New Software" option under "Help".  Search for "Android".  If your Eclipse is preconfigured to know about Android Repository, should come up quickly under Developer Tools.  If not, use http://developer.android.com/sdk/index.html  and also install this plugin: https://dl-ssl.google.com/android/eclipse/

   Within Eclipse, go to Preferences.  Android config is now available to you.  Tell Eclipse your SDK Location.

   You now have in the Window menu, SDK Manager option.  Choose the Android 2.33 folder, checkbox SDK Platform and Google APIs by Google Inc., click Install Package

   Do not be turned off by the thought of having to use eclipse - the code is mostly javascript and you can use any editor you want.
   PROBLEM: Ubuntu repo of Eclipse?  Lots of people are having trouble with getting Eclipse to install this plugin.  If you have this problem, apt-get remove Eclipse, and then download from eclipse.org. (you may have to use "apt-get remove eclipse-platform" on ubuntu)

   4) 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).

   AVD Manager, New...,

   Emulator, target: Google APIs API Level 10

   default SD card size, say, 128 megs

   Snapshotting useful within this emulator -- once emulator's been shut down, it's fast to resume.  Enable this.

   Built-in: default is fine.

   Hardware: default is fine.

   Hit Create AVD.

   Now, click Start, hit Finish

   You'll see a window pop up & boot.  First time, allot 5-20 minutes.  Get your power cords!

   5) 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.   .... we'll try to find the locale of the phone, but if we can't figure it out, default to English.

   6) Import Project.

   Within Eclipse, File: Import.

   Choose "Existing project into the workspace."  Select root directory -- that's wherever you cloned the app.  Hit Finish.

   7) Launch.  Now, go to Package Explorer and see that the codebase is now within Eclipse, checked out from master.  Let's start it!  You can run the app within the emu.  Click the green Play button in the navbar.  It built the Android app and installed it within the emulator

   8) 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.

   IN CASE ANYONE ASKS ABOUT /src : 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.

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. LET US TRIM ALL OF THIS /SRC STUFF FROM THIS PARTICULAR TUTORIAL. QUESTION: 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 Phonegap site has tutorials for each of these. First Exercise: change color of default app. Maybe give them a clue as to what file to look at. Second Exercise: add a Random Article menu item. Look in the HTML. We define the project structure in HTML. 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" .... > Add a command with an id and disabled="false" and an action="show-random-article" The action is how you bind this to a proper function. Go to js/chrome.js at the top, menu_handlers mapping action name to a function. So, add show-random-article to this list. Hit Save. Hit Run. Look at the console -- Window: Show View: Console. Also Window: Show View: LogCat (showing what is happening on the device). The console.log messages show up in the LogCat view. 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. 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. Look in the app.js file to find methods you need for navigation. Then go back to chrome.js and make your function: app.navigateToPage("http://en.m.......Special:Random'); Save Run In console, you see it installing, starting, etc. Emulator: hit More, hit Random Article. There you go! Supplementary EXERCISEs: there are bugs in this implementation.

   Customize it to work for any language.
   Show how translations work.

Should we instead do lots of things on the command line? you can start the Android SDK Manager from command line and then there is a GUI?

   because the Android SDK comes with Ant.

INSTEAD: Download Android SDK

   get what you need. Follow "installing the SDK guide" but do not install the Eclipse plugin.
   Unzip it.
   In that directory, go to tools, and do a ./android and you will get the SDK Manager
   Select the SDK to install -- same as above.
   Type ./android and go to Tools, Manage AVDs, then it is exactly the same as above.

You no longer need to Import Project -- instead, edit stuff in your favorite editor. To deploy into the emulator, go to the full path of your Android SDK and then the tools subdirectory, and do "ant debug install" Other resources: https://meta.wikimedia.org/wiki/Mobile_Projects/Contribute#Apps At end: go into the feature backlog, such as photo upload. This page will be better by Saturday morning. IRC channel, mailing list, etc.