Mobile Hybrid Apps

Here you’ll learn how to add PhoneGap into your Moovweb project and create a hybrid app! Check out some screenshots from the final site:

iOS Config

Prerequisites: Mobile Web Apps

Outline


PhoneGap Project Setup

This tutorial uses Cordova to set up PhoneGap in your app. If you don’t have PhoneGap and Cordova installed, follow the documentation here for iOS and Android.

Don’t forget to download our PhoneGap Example Project!

Run the command:

./path/to/cordova-ios/bin/create /path/to/my_new_cordova_project com.example.cordova_project_name CordovaProjectName

For example:

~/apps/cordova-2.5.0/bin/create ~/Desktop/igadget-app com.igadgetcommerce.jqmApp jqmApp

In our sample Xcode iOS project, the Cordova project is: com.igc.phonegap-ios and the Cordova project name is “phonegap-ios”.

Once you’ve created a new PhoneGap project, all you have to do is configure it to use your Moovweb project.

Configuring PhoneGap to use Moovweb

Currently, when you run this project in Xcode or Eclipse, you’ll see a standard index.html page. This needs to be changed to your Moovweb project URL.

To configure this, go into the jqmApp folder and into config.xml and change the line:

<content src="index.html" />

to your project URL.

For example, in the sample project, it’s changed to:

<content src="http://j.igadgetcommerce.com/" />

iOS Config

For the purposes of your project, it will probably look something more like:

<content src="http://musername1234.mysite.com/" />

And you’ve got a working iPhone app!

For Android users, do the same in the config.xml file in the res/xml folder.

Android Config

Adding the Cordova JavaScript Library

In the default PhoneGap project in Xcode or Eclipse, you’ll see that the required Cordova JavaScript library is included in the local project.

In your iOS project, the Cordova 2.7.0 .js file is in the www folder.

In your Android project, the Cordova 2.7.0 .js file is in the assets/www folder.

As shown in the sample project, include all required JavaScript in the Moovweb project in following directories:

For iOS-specific JS: igadget-webapp/assets/javascript/app/phonegap/ios

For Android-specific JS: igadget-webapp/assets/javascript/app/phonegap/android

For iOS & Android common JS: igadget-webapp/assets/javascript/app/phonegap/common


Device Detection

Next, make your Moovweb project “device-aware” by adding an app-specific cookie to our project.

In your iOS project, open your application delegate file AppDelegate.m under the main Classes folder.

Go to the didFinishLaunchingWithOptions() method, and add the following cookie-logic code as shown in the sample project:

NSString *cookieName = @"mw-phonegap-ios";
NSString *cookieVal = @"true";
NSString* stringURL = self.viewController.startPage;
NSURL* server_url = [NSURL URLWithString:stringURL];
NSHTTPCookie *cook = [NSHTTPCookie cookieWithProperties:
                        [NSDictionary dictionaryWithObjectsAndKeys:
                           [server_url host], NSHTTPCookieDomain,
                           [server_url path], NSHTTPCookiePath,
                           cookieName,  NSHTTPCookieName,
                           cookieVal, NSHTTPCookieValue,
                           nil]];
[[NSHTTPCookieStorage sharedHTTPCookieStorage] setCookie:cook];

return YES;

This code sets the cookie mw-phonegap-ios=true, which can then be read in your Moovweb Project.

iOS Cookie

NOTE: You can set the cookie to any name of your choice.

In your Android project, open your main application file. For example, in the sample project, the file is pg_android.java in the folder pg_android/src/com/igc/pg_android.

Go to onCreate() method, and add the following cookie-logic code as shown in the sample project:

CookieSyncManager.createInstance(getContext());
CookieManager cookieManager = CookieManager.getInstance();
cookieManager.setCookie(Config.getStartUrl(), "mw-phonegap-android=true");
CookieSyncManager.getInstance().sync();

This code sets the cookie mw-phonegap-android=true, which can then be read in your Moovweb project.

Android Cookie

NOTE: You can set the cookie to any other name of your choice.

Next, read the app cookie in your Moovweb project so you can write application-specific Tritium code in your project.

For example in the sample Tritium project, open main.ts under folder igadget-webapp/scripts.

The app-specific cookie is read and stored in variable $is_app as shown below:

$is_app = "false"
match($cookie) {
  with(/mw-phonegap-ios=true/) {
    $is_app = "mw-phonegap-ios"
  }
  with(/mw-phonegap-android=true/) {
    $is_app = "mw-phonegap-android"
  }
  log("$is_app = ", $is_app)
}

Once the cookie is read, you can add app-specific logic to your project. For example, open app.ts in the igadget-webapp/scripts folder, and insert the iOS- or Android-specific Cordova JavaScript library based on the cookie.


Adding Native Features

The following tutorials detail how to add native features such as Barcode Scanning and Push Notifications to your hybrid app.

Barcode Scanning

The sample project demonstrates how to use the Barcode Scanning PhoneGap plugin from Scandit, but you could use any Barcode Scanning plugin you wanted in the same way. Scandit was chosen because it is a fully supported PhoneGap Plugin for Barcode Scanning.

Barcode Scanning

For Scandit PhoneGap Plugin Integration for iOS (or Android), go to Scandit/BarcodeScannerPlugin.

Follow instructions under “Manual Scandit SDK Plugin Integration for iOS”.

For Android, follow instructions under “Manual Scandit SDK Plugin Integration for Android”.

Add required JavaScript functions to your Moovweb project to call the Cordova plugin executable.

For example, in the sample Moovweb project, open the file barcodescan.js in the igadget-webapp/assets/javascript/app/phonegap/common folder. This file contains the Scandit SDK Scan functions, and are common to iOS and Android.

Then trigger the Scandit Barcode Scanner by inserting desired events in your mobile app.

For example, in the sample Moovweb project, the Barcode Scanner is launched by pressing the “Scan” tab bar item.

Open file footer.ts in the igadget-webapp/scripts/sections folder.

The ScanditSDK_Scan() function is added to the onclick() event of the “Scan” tab bar item.

Push Notifications

The sample project shows how to use the Urban Airship (UA) PhoneGap plugin. You can also use other available Push Notification SDKs of your choice, such as Xtify.

Push Notifications

For Urban Airship PhoneGap Plugin Integration for iOS (or Android), follow the instructions on http://docs.urbanairship.com/build/phonegap.html.

UA PhoneGap sample projects are also available here.

Add the required JavaScript functions to your Moovweb project.

For example, in the sample Moovweb project, Urban Airship JS files are placed in the igadget-webapp/assets/javascript/app/phonegap/common folder.


Adding Mobile-Only Content

For certain mobile-specific features, such as setting the controls of Push Notifications in your app, you may need to add a new page that doesn’t exist on the desktop site.

Push Settings

In our sample project, we have demonstrated one way you might add a page to control the Urban Airship settings.

In the scripts/sections/app/footer.ts file you’ll see the ._more button is a link to the homepage with the query parameter “?page=settings”. Then in the mappings.ts file, there is a match for this URL so that a separate transformation is performed instead of the normal homepage transformation.

The header and footer content is created as normal and then the container content is replaced with content inserted by Tritium. This content could be also be injected using an HTML template.

This technique is similar to the technique for separating a web application view into multiple pages from our previous tutorial.