Update 14th May 2016: It's been a very long time since I last wrote a Cordova based app, and these instructions were written based on Cordova v2.x, which was at the time the current version. As mentioned in the post, a new Cordova build and package system was unveiled in v3.0, one which isn't so easy to integrate with CocoaPods. These instructions therefore are probably out of date, but have been retained for reference! There is this nifty thing that converts CocoaPods Podspecs to Cordova plugin definitions that you may wish to give a spin. Alternatively, you may wish to give Carthage a go for your native bits as this seems to fit in better with Cordova's workflow.
While I prefer to develop mobile applications natively, whenever there's a specific requirement to build a hybrid mobile app, I've usually opted for using Apache Cordova.
These days, I always use CocoaPods with most of my iOS development. There are plenty of good introductions to CocoaPods, so to keep mine brief, it makes integrating third party components for Mac & iOS that much easier - you don't have to worry about whether the library uses ARC, which files to include or leave out, etc. Interestingly, there is a Pod (third party component on CocoaPods) for Cordova, but there's little out there to show how to integrate it.
First of all, as usual with CocoaPods you'll need to create your project in Xcode. You almost certainly won't be needing Storyboard as Cordova-based apps need few view controllers. Depending on whether you're planning to write any native classes, you may create unit tests if you wish. Similarly, using ARC is entirely up to you, although obviously using it does make coding that much easier!
Once you have your project set up in Xcode, close it then create a file called "Podfile" in the root of your project. Without going too much into detail, this would look like:
platform :ios, '5.0'
pod 'Cordova', '~> 2.9.0'
Typing pod install in a terminal at this point would create a workspace containing your project & all of the Objective-C code from the specified version of Cordova, which at the time of writing is version 2.9.0.
At this point, you'll need to copy a few files from the Cordova iOS template into your Xcode project. These files can all be found at Cordova's iOS project on GitHub, and make sure when downloading you use the tag corresponding to the version you're using on CocoaPods. Now, navigate to bin/templates/project and:
- Copy the contents of the
wwwfolder into yourwwwfolder. Include it in your project as a folder reference. If you're building this app for many platforms, I would recommend making this folder a git submodule that is shared across all platforms. - Copy all classes, header files & the XIB file from
__TESTING__/Classesinto your project. - Make sure you also include a
config.xml- a sample is in the__TESTING__folder.
You're almost there now - you need to include the AddressBookUI, AssetLibrary and ImageIO frameworks as these are currently omitted from the Cordova pod.
Interestingly, it was only recently when I found out the Cordova CocoaPod also includes the Cordova JavaScript file. If you look at Pods/Pods-resources.sh in your project, you'll see that the cordova.js file is copied to the root of your app bundle. So if you're serving your HTML assets locally, make sure you reference it correctly - for example, if your HTML file is in the www folder, make sure your script tag for the Cordova JavaScript file looks like <script type="text/javascript" src="../cordova.js"></script>.
Now you'll be good to go. But you can always use my example up on Github instead if you get stuck anywhere or just want to skip these steps!
So why do this? Personally, I think it makes working with any other native components so much easier. In a recent Cordova-based app I worked on, I used Google Analytics, Urban Airship & DDURLParser - including all of these would have been more difficult if I wasn't using CocoaPods. I also feel it saves including Cordova related files unnecessarily in the git repository.
There are drawbacks of doing this too. As I've already mentioned, the Cordova pod doesn't include all of the required frameworks. Also, in the past the CocoaPods version was behind the latest stable Cordova version, but this has improved in recent days & I hope it'll continue to keep up.
Cordova has its own plugin mechanism for handling its own plugins, which also consists of its own repository, which is especially useful when targeting more than iOS in your Cordova project. Personally though, I still like to take advantage of CocoaPods itself for Cordova plugins as well, and I'll cover this process in a later post.
As with any tutorial or example I write here, feel free to chip in with any improvements in the comments box below if you have any enhancements.