iOS WebViews

This guide shows how to embed a Cordova-enabled WebView component within a larger iOS application. For details on how these components can communicate with each other, see Application Plugins.

Support for WebViews for iOS started with Cordova version 1.4, using a Cleaver component for which the Xcode template serves as a reference implementation. Cordova 2.0 and later versions only support the subproject-based Cleaver implementation.

These instructions require at least Cordova 4.x and Xcode 8.0, along with a config.xml file from a newly created iOS project. You can use the procedure in The Command-Line Interface to create a new project, then obtain the config.xml file from within the named application's subdirectory within platforms/ios.

To follow these instructions, make sure you have the latest Cordova distribution. Download it from cordova.apache.org and unzip its iOS package.

You have two methods for adding Cordova to your project. The first is using Carthage, and the second is to manually add Cordova. Note that Carthage support is only in cordova-ios version 4.4.0 or greater.

After using either of these two methods, continue with the "Using CDVViewController" section.

1. Add Cordova.framework to the Xcode Project using Carthage

1. Install Carthage

2. In your Cartfile, add (substitute <versionortag> for the appropriate version):

   git "git://git.apache.org/cordova-ios.git" "<version_or_tag>" # Apache
   

3. Run

   carthage update
   

4. Add Carthage/Build/iOS/Cordova.framework into your Xcode project.

2. Adding Cleaver to the Xcode Project (CordovaLib Sub-Project)

1. Quit Xcode if it is running.

2. Open a terminal and navigate to the source directory for Cordova iOS.

3. Copy the config.xml file described above into the project directory.

4. Open Xcode and use the Finder to copy the config.xml file into its Project Navigator window.

5. Choose Create groups for any added folders and press Finish.

6. Use the Finder to copy the CordovaLib/CordovaLib.xcodeproj file into Xcode's Project Navigator

7. Select CordovaLib.xcodeproj within the Project Navigator.

8. Type the Option-Command-1 key combination to show the File Inspector.

9. Choose Relative to Group in the File Inspector for the drop-down menu for Location.

10. Select the project icon in the Project Navigator, select the Target, then select the Build Settings tab.

11. Add -force_load and -ObjC for the Other Linker Flags value.

12. Click on the project icon in the Project Navigator, select the Target, then select the Build Phases tab.

13. Expand Link Binaries with Libraries.

14. Select the + button, and add the following frameworks. Optionally within the Project Navigator, move them under the Frameworks group:

    AssetsLibrary.framework
    CoreLocation.framework
    CoreGraphics.framework
    MobileCoreServices.framework
    

15. Expand Target Dependencies, the top box with that label if there's more than one box.

16. Select the + button, and add the CordovaLib build product.

17. Expand Link Binaries with Libraries, the top box with that label if there's more than one box.

18. Select the + button, and add libCordova.a.

19. Set the Xcode Preferences → Locations → Derived Data → Advanced... to Unique.

20. Select the project icon in the Project Navigator, select your Target, then select the Build Settings tab.

21. Search for Header Search Paths. For that setting, add these three values below, including the quotes:

    "$(TARGET_BUILD_DIR)/usr/local/lib/include"
    "$(OBJROOT)/UninstalledProducts/include"
    "$(OBJROOT)/UninstalledProducts/$(PLATFORM_NAME)/include"
    "$(BUILT_PRODUCTS_DIR)"
    

    As of Cordova 2.1.0, CordovaLib has been upgraded to use Automatic Reference Counting (ARC). You don't need to upgrade to ARC to use CordovaLib, but if you want to upgrade your project to use ARC, you should use the Xcode migration wizard from the Edit → Refactor → Convert to Objective-C ARC... menu, de-select libCordova.a, then run the wizard to completion.

Using CDVViewController

1. Add the following header:

   #import <Cordova/CDVViewController.h>
   

2. Instantiate a new CDVViewController and retain it somewhere, e.g., to a class property:

   CDVViewController* viewController = [CDVViewController new];
   

3. Optionally, set the wwwFolderName property, which defaults to www:

   viewController.wwwFolderName = @"myfolder";
   

4. Optionally, set the start page in the config.xml file's <content> tag, either a local file:

   <content src="index.html" />
   

   ...or a remote site:

   <content src="http://apache.org" />
   

5. Optionally, set the useSplashScreen property, which defaults to NO:

   viewController.useSplashScreen = YES;
   

6. Set the view frame. Always set this as the last property:

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

7. Add Cleaver to the view:

   [myView addSubview:viewController.view];
   

Adding HTML, CSS and JavaScript Assets

1. Create a new directory within the project, www for example.

2. Place HTML, CSS and JavaScript assets into this directory.

3. Use the Finder to copy the directory into Xcode's Project Navigator window.

4. Select Create folder references for any added folders.

5. Set the appropriate wwwFolderName and startPage properties for the directory you initially created, or use the defaults (specified in the previous section) when instantiating the CDVViewController.

   /*
       if you created a folder called 'myfolder' and
       you want the file 'mypage.html' in it to be
       the startPage
   */
   viewController.wwwFolderName = @"myfolder";
   viewController.startPage = @"mypage.html"