Two-Minute Tutorials 0

TMT0 Use AppLaud to Create a Web App Project, Run it on a Device or Simulator

*Primer tutorial for MDS AppLaud 1.2 Eclipse Plugin for PhoneGap for Android

AppLaud Plugin Intro Video

The first Two-Minute Tutorial (TMT0) presents in detail the steps to create a new project, understand project and file contents, enable and review JSLint settings, and run the app on a device or simulator. Users who have already run a PhoneGap app from Eclipse may prefer to skip to TMT1. The MDS
AppLaud Plugin includes 5 demo projects ready to run out-of-box.

This tutorial uses the basic PhoneGap demo. See all 5 demo apps included with
AppLaud.

Prerequisites

Part 1 Use Project Creation Wizard to create new Web App Project

1. The image below shows a pristine Eclipse workspace, after installing the AppLaud Plugin (and restarting as directed) and before creating any projects.
  • The PhoneGap icon launches the PhoneGap Project Creation Wizard
  • Notice the current Java perspective in the upper right corner (will be JavaScript after project creation)
  • Action: Click on the Project Creation Wizard icon
Note: Most widgets/items include hints in hover text - make use of them to learn Eclipse quickly

Note: The equivalent menu path for new project creation is File -> New -> Project... -> PhoneGap for Android Project

2. Use the Wizard to create a new Project

The first page of the wizard is shown below.
  • Action: Select the auto-inclusion of PhoneGap
  • Action: Select the PhoneGap example source for the app
  • Action: Select Next
Note: TMT1 will use a UI Framework (jQuery Mobile). This demo keeps it simple!

Note: For alternate version of PhoneGap, download it to your host and select Enter path to installed PhoneGap, follow instructions from there.

3a. Android Project Config (SDK Tools 14 and later)

Assign name to project in the first window:
Click Next twice (we'll come back)

Update Application Info:
  • Assign package name
  • Set minimum SDK to the minimum Android Version to support
  • Click Back
  • Select the latest Target as your Build Target
  • Note that PhoneGap is designed to work with recent Build Targets and support old versions with minSDK
    • Choosing a Target Name < 2.3 will require you to later remove from AndroidManifest.xml :  android:xlargeScreens="true"
Continue to Step 4.

3b. Android Project Config (Only For SDK Tools 13 and earlier)

The second and last page of the wizard is shown below.

  • Action: Enter a project name ( becomes top level directory for project)
  • Leave selections in Content area as they are
    • Note: Changes to Content area is not supported
  • Action: Select the build target (targets vary by SDK installation)
    • Choose the latest available Target (use Min SDK to specify the minimum target you need to support)
  • Action: Enter an Application name (the app name that will show on your phone)
  • Action: Enter a package name (e.g. com.[company-or-group].appname),
  • Action: Enter an Activity class (no spaces)
  • Action: Enter the Min SDK corresponding to the minimum Android version you need to support
    • PhoneGap 1.0 and later do not support earlier versions than Android 2.1 (Min SDK <- 7)
    • Ignore the Eclipse warning about different versions 
  • Action: Click Finish to complete project creation
Note: A known issue exists regarding the unchecking of Use default location. Please leave this checked.

4. Review of PhoneGap Project Structure

Upon project creation, Eclipse will look similar to the image below.
To take you straight into editing your web app, the MDS AppLaud Plugin automatically:
  • loads index.html into the editor
  • opens the assets/www directory
  • sets the perspective to Javascript (click icon to left of JavaScript to see other perspectives)
Note the contents of assets/www directory:
  • index.html - required, and the launch point of the web app
  • phonegap-<version>.js file - required, the PhoneGap javascript API
  • apis - directory containing javascript code for this project: PhoneGap APIs
  • index.css - the css for this project (as we are not using a UI Framework)
Typically all web app sources live in assets/www: html, javascript, css, plugins, frameworks, images, etc.

5. Enable JSLint on the new project

JSLint with option modifications is integrated with the MDS
AppLaud plugin, and can be enabled for any project to help you write "more correct" javascript code (meaning: less time with coding errors and debugging them).
  • Action: Right click on the top level directory of your project (the project name) and select Enable jslint4java.
  • Action: Review the default preferences in the Window -> Preferences window, select jslint4java in the left panel (repeat the last two actions to toggle jslint4java off)
The default preferences are as shown below.
  • Example of strict setting: if a semicolon is required by javascript, a warning message will appear in the left margin of the editor at that line of code
  • It is possible to exclude files or directories from jslint4java, which may be useful when including javascript not written by you (plugins, frameworks, etc)
  • Action: Close the jslint4java window to return to the editor
  • Action: Project -> Clean to see any changes
6. Add the Console to the Javascript perspective

It is useful to use the console for debugging your setup and app.

  • Action: Window -> Show View -> Console
  • When deploying your app to a device or AVD, the status of loading, installing and starting the activity is displayed in the console
The image below shows example console output from a successful app deployment on a device
Note: The Console view (Eclipse) described above is not to be confused with the Android SDK's LogCat window in the DDMS (debugging) Perspective and the use of console.log(). Links to DDMS documentation and AppLaud User Tips for DDMS here.

Part 2 Run the App on a Device or Simulator (AVD)

7. The demo projects need no editing and are ready to run on your device.

7a. Running the app on the simulator (Android Virtual Device)
  • Action: Select your project at the top level in the Project Explorer
  • Action: From the menu bar select Run -> Run Configurations
  • Action: Select the Target tab (between Android and Common tabs)
  • The Run Configurations window should look similar to the image below
  • Action: Verify your project is selected under Android Application, and in the Name field at the top
  • Action: Select Automatic or Manual (Automatic recommended for AVD)
  • Action: Select the AVD in the list of virtual devices
  • If AVD list is empty, see Android documentation on AVD setup
  • Action: Select Run to launch the simulator
  • Wait patiently for the AVD to start up, unlock the screen, wait for app to run!

7b. Running an app on a real device
  • Action: Attach the Android device to your development host, confirm USB and debugging are enabled on your device 
  • Action: Select your project at the top level in the Project Explorer
  • Action: From the top menu bar select Run -> Run Configurations
  • The Run Configurations window should look similar to the image in AVD section above
  • Action: Verify your project is selected under Android Application, and in the Name field at the top
  • Action: Select the Target tab (between Android and Common tabs)
  • Action: Select Manual (as opposed to the Automatic selection in AVD instructions)
  • Action: Select Run to get to the next window, as shown below
  • If your device is not listed, see Android documentation on vendor id

Your device should be listed here with a state of Online.
  • Action: Select the device to run the app on
  • Action: Select OK to see your app load and run on your device!
  • Example screen from Samsung Galaxy Tab 10.1 below
 After creating a run configuration, you will be able to run your app in that configuration with CTRL+F11 (or the Run -> Run menu command).

Alternate way to run the app, useful when you have multiple projects:
  • Right click on the project (top level, or project name) in the Project Explorer
  • Select Run As ->  1) Android Application
To use AppLaud more efficiently and spend less time on javascript errors, see TMT0.1 User Tips Including DDMS and AVD.

Ready for your next app? Use 
AppLaud to play media in TMT1: Media Player and jQuery Mobile UI.

Had trouble with the above - or found it helpful? - let us know here!

Return to the main tutorial page.
Comments