Setup Android Development Environment

Requirements

1. Choose one of the following IDE options:
   
   1. Eclipse Development Environment
      
      1. Download Android SDK
      2. Install Android Eclipse Plugin
   2. Android Development Tools Bundle.
2. PhoneGap 2.5
3. Running uMobile 1.1RC1 application server.
4. Download & install node.
   
   1. Node is used to automate the build process for our JavaScript, HTML and CSS assets.
   2. Node is installed locally and is leveraged for convenience.
   3. Node v0.8.12 is recommended for this documentation.

Getting Started with Android

The PhoneGap website has an excellent Android start up guide. It is recommended but not mandatory that you walk through their startup guide before continuing to familiarize yourself with the overall process.

Creating the Project

Extract PhoneGap

1. Navigate to the folder where you downloaded PhoneGap 2.50. Find the phonegap-2.5.0.zip file and extract its contents.
2. Expand this folder and navigate to phonegap-2.5.0 > lib > android directory.
3. The android directory is where we will be working to create a new project.

Open Terminal

1. Open a new Terminal window.
2. In the Terminal window, navigate to the android > bin directory from the extracted PhoneGap code base.

Create a Project from the Terminal

There are 3 ordered, required parameters for creating a project from the command line. For more detailed information on these parameters visit the PhoneGap Android start up guide.

1. Project Location: This is the directory where the Xcode project and files for the application will be located.
2. Package Name:  This is the package name. (i.e., com.YourCompany.YourAppName) Note: The package name is specific to your institution.
3. Project Name: This is the name of the actual project.

To create a project

1. In the Terminal window with android > bin as your current directory, enter the 3 required parameters with the create command.

   ./create ~/Documents/umobile-phonegap-android org.jasig.umobile.phonegap.android uMobile

2. A complete and ready to launch project will be created under the directory specified.
   
3. Navigate to the assets/www directory. Open the directory and delete all of the folder contents. Do not delete the www directory itself. The www directory is the folder that houses our custom HTML, CSS and JavaScript implementation. In this step, we are simply removing stubbed files provided by the PhoneGap code base.

Adding the uMobile Source

1. In a Terminal window, navigate to your project location. For this tutorial, our project is housed under the Documents > umobile-phonegap-android directory.

2. Continuing on the terminal, navigate to the umobile-phonegap-android directory. From this directory, checkout the uMobile source code.

   git clone git@github.com:Jasig/umobile-app-phonegap umobile-ui

3. Your project directory should look similar to the below graphic:
   

Configure the uMobile Source

Install Dependencies

1. In a Terminal window, navigate to your project location. For this tutorial, our project is housed under the Documents > umobile-phonegap-android directory.
2. In the same Terminal window, navigate to the umobile-ui directory.

3. Execute the following command to load all the ui dependencies. Note: Node must be installed.

   sudo npm install

Configure Authentication

1. uMobile currently supports three different authentication strategies: CAS, Local & Mock.
   
   1. Each strategy has a cooresponding configuration file under the umobile-ui/config/js directory (i.e., cas.js, local.js and mock.js).
   2. Choose one of the three authentication strategies. For this documentation, we will use local.js.
   3. Open local.js.
      
      1. Set config.uMobileServerUrl to the url for your instance of the uMobile quickstart. Be sure to also use your local ip address. For example: http://192.168.1.1:8080
      2. To find your local ip address, type ifconfig (Mac) or ipconfig (Windows) in a terminal window.
      3. Set config.loginFn to localLogin.

Configure Build Process

1. Navigate to the umobile-ui/config directory.
2. Open the config.json file in an editor of your choice.

3. Set the external property to the path of your project's assets/www file directory. See the below code snippet for an example. The external property tells the build process where we want to push production-ready code. In this instance, we are telling it to place our production-ready code in the www container provided by the PhoneGap code base. Note: It is important to point out that while we have the capability to push production-ready code to an external source, we do not have the ability to clean or remove previously pushed code that lives outside of the umobile-ui directory. This is a limitation of the grunt libraries being leveraged on this project. Future updates to this code base could improve this functionality.

   {
   	"port": 5000,
   	"environment": "web",
   	"auth": "mock",
   	"mode": "dev",
   	"less": {
   		"dest": "./src/css",
   		"src": "./src/less",
   		"prefix": "/css",
   		"debug": true
   	},
   	"external": "../assets/www"
   }
   

Run the Build

1. In a Terminal window, navigate to the umobile-ui directory.

2. Execute the below command in the Terminal window.

   grunt prod --environment=android --auth=local

3. The above command starts the build process for the uMobile source code. The build process configures the uMobile source code with the necessary dependencies needed to run in a given environment. Currently, the uMobile project supports Android, iOS and Web platforms. Once the build completes a www directory will be added to the umobile-ui directory. The www directory houses the production-ready code base to be used with the PhoneGap wrapper. Please see the documentation on the uMobile HTML5 build for more information on configuring the build script.

4. Once built, execute the below command to push the built code to the PhoneGap www directory.

    grunt push.prod

5. Your project directory should like similar to below graphic:
    

Start the uMobile Server

1. The requirements section of this documentation states that you need to download and start the uMobile quickstart (i.e., uMobile 1.1RC1). The uMobile quickstart houses all the content leveraged by the uMobile application for this tutorial. For more information on the uMobile quickstart visit the project's main site.

2. Once the uMobile server is downloaded and extracted. Navigate to the root folder and execute the following command:

    ant start

Load Project into Eclipse

1. Launch Eclipse.
2. Select File > New > Project.
3. Select Android > Android Project from Existing Code.
   
4. Set the Root Directory to match your project location. For this tutorial, our project is housed under the Documents > umobile-phonegap-android directory.
   
5. Click Finish.

Resolve Eclipse Errors

After your project has been loaded into Eclipse, a red X icon may appear on the root of your project. If this occurs, follow these additional steps:

1. Right click on the uMobile project folder.
2. Select Properties from context menu.
3. In the properties dialog, select the Android menu option.
4. Make sue you are using at least Android 4.0 for the Project Build Target.
    
5. Click Ok.
6. Select Project > Clean.
7. All errors should disappear.

Deploy to a Device

I would strongly recommend developing and testing against an actual Android device. The emulator that ships with Android Developer Tools is incredibly slow and difficult to operate. To set up your device walk through the steps described in the Setting Up a Device for Development article on the Android developer site.

Run the Project

1. From the Project menu in Eclipse, select the uMobile project.
2. Select Project > Clean.
3. Run the project by right-clicking the project name, then selecting Run as > Android application.

Debugging and Logs

• When running the app via Eclipse, app logs are available via the LogCat view. To open this view, navigate to Window > Show View > Other, then select Android > LogCat.
• If you need to set breakpoints, launch the application via debug instead of run.