Tutorial: Embed PhoneGap as a Subview in your Native iOS Application

Something cool that many mobile developers (and particularly native developers) might not be aware of at this point, is the option to use PhoneGap (aka Cordova) as a component within your mobile application, as a web “subview” of a whole native application where you want to render HTML/JS content and/or interact with the PhoneGap APIs. In this webview component (sometimes also referred to as Cleaver), you can do anything a traditional PhoneGap application would do, such as access native features like the camera or contacts etc too. This post will expand the steps here and show you a sample application you could download and try yourself. Note that I am not an Objective-C native programmer, but this is just a simple example to show off the capabilities and create awareness. Feel free to post your application or source if you have used this and would like to share with others .

Steps to Embed Cordova WebView

Below are detailed steps on including PhoneGap/Cordova as a web subview in your native application. At the end of this section I show screenshots from a sample application I made available on my github account for you to try this out yourself or refer to things as needed.

1. Create your base native iOS application in XCode (version 4.5 recommended) unless you just plan to add to an existing native application.

In my case I chose to create a new Single View Application in XCode such as the following:



2. Download and extract the Cordova source to a permanent folder location on your hard drive (for example: ~/Documents/Cordova).
You’ll need this for copying Cordova resources into your native application.
3. Close any other Cordova projects and exit XCode (XCode can be quirky, a restart often clears up potential or possible errors).
4. Navigate to the directory where you put the downloaded Cordova source above and copy the Cordova.plist file into your native application folder on the file system (at same level as the AppDelegate files etc, see picture below). Note: you could also use a Cordova.plist from a newly created Cordova application.

   

   This file contains specific Cordova property settings and plugins required for your application to use Cordova.
5. Drag and drop the Cordova.plist file into the Project Navigator of Xcode
6. Choose the radio-button “Create groups for any added folders”, select the Finish button
7. Go to the downloaded source from the previous step above and locate the CordovaLib.xcodeproj in the CordovaLib sub-folder. Drag and drop the CordovaLib.xcodeproj file into the Project Navigator of XCode (at the same level as the .plist file copied in above – again choosing ‘Create groups for any added folders‘)
8. Select CordovaLib.xcodeproj in the Project Navigator
9. Open the File Inspector with Option-Command-1 or by going to View | Utilities | Show File Inspector
10. Ensure that it says “Relative to Group” in the File Inspector for the Location drop-down menu similar to below:



11. Select the project icon in the Project Navigator, select your application under “TARGETS” (should have an A next to it), then select the “Build Settings” tab as shown below:



12. Locate the setting for “Other Linker Flags” (under the Linking section) and double-click the value text field to bring up the box to enter the flags -all_load and -Obj-C as shown here:



13. Select the project icon in the Project Navigator, select your target, then select the “Build Phases” tab.
14. Expand “Link Binaries with Libraries”. Select the “+” button, and add these frameworks (and optionally in the Project Navigator, move them under the Frameworks group):

    AddressBook.framework
    AddressBookUI.framework
    AudioToolbox.framework
    AVFoundation.framework
    CoreLocation.framework
    MediaPlayer.framework
    QuartzCore.framework
    SystemConfiguration.framework
    MobileCoreServices.framework
    CoreMedia.framework



15. Now expand “Target Dependencies”
    Select the “+” button, and add the CordovaLib build product



16. Expand “Link Binaries with Libraries” again and add libCordova.a
17. Go to “Xcode Preferences -> Locations -> Derived Data -> Advanced…” and ensure it is set to “Unique”
18. Go back to Build Settings and locate the Header Search Paths and ensure the following properties are set (including the quotes):
    “$(TARGET_BUILD_DIR)/usr/local/lib/include”
    “$(OBJROOT)/UninstalledProducts/include”
    “$(BUILT_PRODUCTS_DIR)”
    

The result should look like the following:

Code Additions

To actually use the subview, you need to add the following Objective-C code where you want to include it.
Import the following header

#import <Cordova/CDVViewController.h>

Instantiate a new CDVViewController

CDVViewController* viewController = [CDVViewController new];

Set up the view frame

viewController.view.frame = CGRectMake(0, 0, 320, 480);

Lastly, add to your view as a subview

[myView addSubview:viewController.view];

You could optionally set the www folder, start page or option to show the splash screen to something other than the default (default folder is www, start page is index.html and splash screen is no) on that CDVViewController as well with the following lines:

viewController.wwwFolderName = @"myfolder";
viewController.startPage = @"mystartpage.html";
viewController.useSplashScreen = YES;

Here’s an example of actually implementing those lines above in my ViewController.m class that is created with a new native XCode Single View project like discussed above (the added code is in the viewDidLoad function):

#import "ViewController.h"
#import <Cordova/CDVViewController.h>

@interface ViewController ()

@end

@implementation ViewController


- (void)viewDidLoad
{
    [super viewDidLoad];
    CDVViewController* viewController = [CDVViewController new];
    viewController.view.frame = CGRectMake(0, 40, 320, 450);
    [self.view addSubview:viewController.view];
}

- (void)viewDidUnload
{
    [super viewDidUnload];
    // Release any retained subviews of the main view.
}

- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
    if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPhone) {
        return (interfaceOrientation != UIInterfaceOrientationPortraitUpsideDown);
    } else {
        return YES;
    }
}

- (void)dealloc {
    [super dealloc];
}
@end

In my sample application you can see it when you press the Open a new Cordova WebView button. You could choose to add this code wherever you need it, this is just one example for simple illustration.

Sample Application

In the first screenshot below, the header navigator and tab bar at the bottom (with badge), and the second view with all the text and controls are actually native iOS controls, whereas the middle embedded view with the button list is an embedded Cordova WebView containing HTML/JS to interact with the native Cordova/PhoneGap APIs to retrieve contacts, use the camera, etc.

If you’re familiar with Storyboarding in XCode for iOS, the Storyboard shows an overview and flow of the application from the native perspective, so you can see the parts which are iOS Native controls versus the other buttons etc that were included from the HTML/JS as part of the Cordova WebView:

In the next screenshot you can see how we can interact with the Cordova/PhoneGap APIs for native functions like grabbing contacts right there inside our native application:

This next view is all native iOS controls (see storyboard), but includes a button to pop up a new view that uses the same ViewController class and will have the embbeded Cordova subview:

And lastly is our next view from the button pop-up that shows how another view will also have the embedded Cordova WebView:

Grab the sample application from my github account and give it a whirl.

There’s an advanced tutorial dedicated to embedding PhoneGap for Android here, so be sure to check that out too!