Setup iOS Development Environment

1. Apple OSX development environment.
2. Download XCode 4.6.
3. Download PhoneGap 2.50.
4. Download & run uMobile 1.1RC1 quickstart.
5. 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.

...

The PhoneGap website has an excellent iOS 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 > ios directory.
3. The ios 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 ios > 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 iOS start up guide.

...

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

   Code Block
   ./create ~/Documents/umobile-phonegap-ios org.jasig.umobile.phonegap.ios uMobile

2. A complete and ready to launch project will be created under the directory specified.
   Image RemovedImage Added 
3. Navigate to the 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.

...

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

2. From this directory, checkout the uMobile source code.
   

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

3. ...

Creating the Project

A completed example of an XCode project configured to run the uMobile PhoneGap implementation is available on github.

1. Check the uMobile source out into a new project directory.
    

   Image Removed

2. Navigate to umobile-ui/config/js.Your project directory should look similar to the below graphic:
   Image Added

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-ios 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.

   Code Block
   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 caslocal.js.
   3. Open caslocal.js.
      
      1. Set config.uMobileServerUrl to http://localhost:8080.
         
      2. Set config.loginFn to casLogin.
      3. Note: There are bugs with the current login functionality. Only view the portal using the guest layout. This is being addressed.
   Run
   1. 1. 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 root project's 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.

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

Run the Build

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

2. Execute the below command in the Terminal window.

   Code Block
   grunt prod --environment=ios --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 supports Android, iOS and  and Web platforms platforms. Once the build completes a a www directory  directory will be added to the the umobile-ui directory directory. The The www directory  directory houses the production-ready code base to be used with the PhoneGap wrapper. Please see the the documentation on  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.

   Code Block
   cd umobile-ui sudo npm install grunt --environment=ios --config=cas --build=prod

    

5. Drag the production-ready www directory from your finder window to the XCode uMobile project. When done for the first time, XCode will ask you to create a workspace before including the www directory. For the purpose of this project, we created a umobile workspace.
   Image Removed  
6. Choose options for adding the www directory to the project.
   Image Removed 
Configure cordova.plist.

1. In XCode, under the Project Navigator, navigate to uMobile > Supporting Files > Cordova.plist.
2. Under the Root Key:
   
   1. Set OpenAllWhitelistURLsInWebView to Yes.
3. Under the ExternalHosts Key:
   
   1. Add the hostname, any authentication servers and any other servers hosting uMobile resources.
   2. If you're working with the uMobile quickstart, you can just add localhost.
4. Under the Plugin Key:
   
   1. Plugin: SesssionTracking
   2. Type: String
   3. Value: SessionTracking
Image Removed
Add SessionTracking Plugin files into the Plugins folder:

1. SessionTracking.h
2. SessionTracking.m
Image Removed

7. Download MainViewController.m
8. Navigate to uMobile > Classes > MainViewController.m.
9. Replace MainViewController with the downloaded version

   grunt push.prod

10. Your project directory should like similar to below graphic:
    Image Added 

Add uMobile Icons and Splash Screens

The uMobile source code ships with iOS icons and splash screens. Currently, these splash screens and icons have not been designed for the new high-retina displays. Future work on the uMobile source code should focus on updating these icons and splash screens for high-retina displays.

1. In the Finder, navigate to your project location. For this tutorial, our project is housed under the Documents > umobile-phonegap-ios directory.
2. All icons and screens can be found at the following path: umobile-phonegap-ios > src > images > platform > ios
3. Update the images within the ios folder to match your organization or institution.
4. Copy all the icons from ios directory to the umobile-phonegap-ios > uMobile > Resources > icons directory.
5. Copy all splash screens from the ios directory to the umobile-phonegap-ios > uMobile > Resources > splash directory.

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:

   Code Block
   ant start

Run uMobile with the iOS Simulator

1. In Finder, navigate to your project location. For this tutorial, our project is housed under the Documents > umobile-phonegap-ios directory.
2. Double click the uMobile.xcodeproj file. This will open the xCode editor.
   
3. Set the scheme at the top of the project to iPhone 6.1 Simulator and run the project!
   Image Removed
   
   Image Added
   

uMobile Screen Shots

Debugging

uMobile logs helpful events and errors. You can access the log by viewing the console output.