Shazron's Cordova (aka PhoneGap) Blog

at Adobe Systems Inc.

Archive for the ‘phonegap’ Category

What’s new in Cordova iOS 2.5.0

with 20 comments


Mainly bug fixes.

1. New functionality for Plugins

Lots of enhancements, and one removal. See the Plugin Upgrade Guide. Of note, you can load plugins at startup now.

2. config.xml root element is <widget>

Shouldn’t affect your current config.xml since the config parsing doesn’t care about the root element name. There’ll be further changes to config.xml so we conform to the widget spec as we go along.

3. Better FileTransfer errors

Now you get the response body in the FileTransferError object returned.

4. Enable NSURLCache for better app performance

Set in the app template.

5. Added support for Native URIs (iOS’ assets-library:// scheme)

See CB-2213.

Written by shazron

March 4, 2013 at 5:44 pm

Posted in cordova, phonegap

What’s new in Cordova iOS 2.4.0

with 13 comments


1. Removal of JSONKit, replaced with NSJSONSerialization

Since we dropped support for iOS 4.x, this is now possible. See the Plugin Upgrade Guide.

2. Support for ArrayBuffer arguments over the exec bridge

Only for top level arguments (nothing nested). It converts the ArrayBuffer to a NSData object, and vice-versa. See CB-2189 and CB-2215.

3. The start page can be specified in config.xml

Through the content tag.

4. FileTransfer “trustAllHosts” parameter

This is now supported. Set to true to trust hosts with self-signed certificates, for example.

5. InAppBrowser enhancements, and fix

Enhancements are specified here. Basically these are the same settings as in the Project Settings, also presentation and transition styles are added. The fix for InAppBrowser is specified here. Basically, on iOS 6, when you load PDFs in the InAppBrowser, it resets the User-Agent for all UIWebViews which we rely on for our exec bridge — our fix helps work around that, with caveats.

6. Custom url-scheme handler ‘handleOpenURL’ not called on startup

It was not being called on first app launch, but has now been fixed. Resume from backgrounding has always worked.

7. FileTransfer failing for file:/// urls

Fixed. An alternative is to use xhr.

8. require.js lazy loading of cordova.js

This should  work now.

9. Various deprecated methods removed

See the wiki.

10. Default splash-screen sizes 10x smaller

Shouldn’t affect you much.

11. There was an ARC issue in Contacts

See this issue.

12. Support Reading Slices of Text Files.

From Simon McDonald’s blog post regarding Cordova Android 2.4.0:

The File object now has a slice method. Suppose the file we’re reading contains the text:

“All that is gold does not glitter, not all those who wander are lost.” 


  • f.slice(4, 8) would result in “that”
  • f.slice(9) would be “is gold does not glitter, not all those who wander are lost.”
  • f.slice(-5, -1) would be “lost”

[NOTE] I want to also draw attention to cordova-cli being released with 2.4.0. More on Raymond Camden’s blog. In a nutshell, this is an abstraction for the command-line utilities that are included for the different platforms all in one easier to use interface, plus the ability to add and remove plugins.

Written by shazron

February 8, 2013 at 3:44 pm

Posted in cordova, phonegap

What’s new in Cordova iOS 2.3.0

with 38 comments


1. iOS 5.x and above support only

We are dropping iOS 4.x support and only supporting iOS 5.0 and greater, going forward.

2. Cordova.plist is changed to config.xml

The configuration Cordova.plist file has been changed to config.xml – it comes in a new format that is the same as the Android config.xml. If you are upgrading, you will need to convert your existing Cordova.plist by running the bin/cordova_plist_to_config_xml script. The 2.3.0 project itself will warn you (in the console log) if you are still using the old Cordova.plist and tell you to upgrade.

The new project settings are documented here.

An example config.xml:

        <preference name="MySetting" value="true" />
            <plugin name="MyPlugin" value="MyPluginClass" />
        <access origin="*" />

3. InAppBrowser – includes events

More details here. In a nutshell, this has the same functionality as the ChildBrowser, and has events support as well. It supports this simplified spec. Also, the InAppBrowser does not use the app whitelist. Example usage:

var ref ='', '_blank');
ref.addEventListener('loadstart', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('loadstop', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('exit', function(event) { alert(event.type); } );

// also, you can do ref.removeEventListener('loadstart', myfunc) .. etc

4. LocalNotification  plugin event, AppDelegate override

Your project’s AppDelegate.m can add a new AppDelegate override so your plugins can receive LocalNotification events. Uncomment these lines  to enable your plugin to receive the notifications in their overrides.

5. Renaming of Cordova cli commands

The new list of commands are here. Basically debug has been renamed to build, and new release,  and run commands have been added. This is common across all the platforms.

6. Objective-C plugins are not white-listed anymore

With the InAppBrowser release, we restructured the whitelist to only apply to the main Cordova WebView. As a consequence, the whitelist does not apply to all connections for the app, thus connections from your plugins are not whitelisted. To whitelist your connections with the app whitelist, you will need to set the “User-Agent” header of the connection to the same user-agent as the main Cordova WebView.

You can get this by accessing the userAgent property off the main view-controller. The main view-controller (CDVViewController) also has a URLisAllowed method for you to check whether a URL will pass the whitelist. See this guide.

7. Device API changes

Minor changes as specified here. For iOS, device.platform used to return “iPhone”, “iPad” or “iPod Touch” — now it returns (correctly) “iOS”. For iOS, (now deprecated for all platforms) used to return the name of the user’s device (e.g ‘Shazron’s iPhone 5′) — now it returns what device.platform used to return: “iPhone”, “iPad” or “iPod Touch”.  For all platforms, there is a new property called device.model — this returns the specific device model, e.g “iPad2,5″ (for other platforms, this returns what used to return).

8. CommandDelegate overrides

The command delegate could not be overriden properly, now fixed. Please look at this issue on how to override the delegate functions, for inspection.

Check out the Release Notes for other minor changes.

Written by shazron

December 10, 2012 at 9:37 pm

InAppBrowser (based on ChildBrowser) in Cordova 2.3.0

with 97 comments

The inclusion of the InAppBrowser in iOS and Android will be new for Cordova 2.3.0. You can play with the InAppBrowser today if you download the latest code and help us test.

The InAppBrowser is a built-in web browser for your app that has an API that follows web standards. It follows the API, except for a new window target that we introduced: “_system“. Read our simple specification.

Does this mean the ChildBrowser is going away? Not really. These two plugins can co-exist, and ChildBrowser has added features that are not present in the InAppBrowser, particularly events. [UPDATE: see below]InAppBrowser also has no dependencies on a .xib or external images, so it is easy to integrate for upgrades.

What’s also new with the InAppBrowser implementation for iOS is, the white-list is not applied application wide anymore, the white-list will only apply for the main Cordova UIWebView only. Now you can load non-white-listed URLs into the InAppBrowser and the ChildBrowser.

There are several enhancements for plugins related to this new white-list exception functionality as well – please see issue CB-1889. The enhancements should land before the final 2.3.0 is released.

Please help us test by downloading the latest code or RC and giving this new feature a spin!

[Update Nov 28 2012]: The InAppBrowser on iOS has support for events now (Android in progress). You can listen to the ‘loadstart‘, ‘loadstop‘ and ‘exit‘ events. The callback function is passed an event object that has two properties: type, and url. You will need to grab the latest code and javascript (create a new project).

Example usage:

var ref ='', '_blank');
ref.addEventListener('loadstart', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('loadstop', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('exit', function(event) { alert(event.type); } );

// also, you can do ref.removeEventListener('loadstart', myfunc) .. etc

[Update Nov 30 2012]: Changes for InAppBrowser events for Android are in cordova-android now.

[Update Jan 7 2013]: If you have a multi-page app, and you use InAppBrowser, and you use iOS 6, you must use iframe bridge mode. More details here.

Written by shazron

November 21, 2012 at 8:06 pm

Cordova plugins? Put them in your own repo

with 18 comments

[edited: removed reference to pluginstall which is PhoneGap Build centric, to Plugman which is based on pluginstall but is Cordova centric, and more frequently updated]

Right now, there is one repo that contains the majority of plugins available for Cordova at:

We don’t want to “clutter” this repo with code anymore. Authors should maintain the code in their own repos and publish them to the Cordova Plugin Registry.

Having the plugins in separate repos also enables less clutter for pull requests and bugs, with it all being in one repo it is hard to get attention for an issue since that can be buried. I know that I like to fix some of my plugins, but it’s hard with it all lumped in there with other unrelated plugin issues.

As a reminder, this is how to write a Plugin:

For examples of plugins that conform to the Cordova Plugin spec and are plugman-able:


I’ve already moved out the plugins that I started implementation on (iAdPlugin, KeychainPlugin, PayPalPlugin, TorchPlugin, TestFlightPlugin). I suggest that you do the same.

Written by shazron

November 7, 2012 at 11:40 pm

Posted in cordova, phonegap

What’s new in Cordova iOS 2.2.0

with 58 comments

1. Set Xcode 4.5 minimum (iOS 6 SDK, iOS 4.3 deployment target, no armv6)

Submission to the Apple App Store requires the latest SDK, which is iOS 6. The iOS 6 SDK only comes with Xcode 4.5. Xcode 4.5 drops support for armv6, thus the minimum deployment target supported is iOS 4.3. This means that support for the iPhone 3G, and iPod Touch 2nd Generation is dropped.

2. Fixed iOS 6 and iPhone 5 issues

  1. iOS 6 Contacts permissions support – this was the only API issue for iOS 6 that did not make it into 2.1.0
  2. Capture API – for capturing audio, a new microphone image has been added for the iPhone 5 dimensions, and the Capture API view controllers support the new iOS 6 orientation delegate methods
  3. Added iPhone 5 sized Splash Screen
  4. Added new iOS 6 orientation delegate methods, and fixed orientation bug:
  5. iOS 6 LocalStorage changes (backup flag), see issue and new Cordova.plist setting change to allow for iCloud, local or no backup. 

3. FileTransfer API changes

  1. Added support for the onprogress event to get progress events for a FileTransfer operation
  2. Added the abort function to cancel a FileTransfer operation

See the API doc.

4. Cordova.plist new properties, and changed a property

  1. Added the iOS 6 property SuppressesIncrementalRendering - set to YES (defaults to NO) to wait until all new view content has been received before it is rendered.
  2. Added the iOS 6 property KeyboardDisplayRequiresUserAction – set to NO (defaults to YES) to open the keyboard when form elements get focus via JavaScript focus() call.
  3. Changed the property BackupWebStorage (string, defaults to ‘cloud’) – valid values are ‘none’, ‘cloud’ and ‘local’. Set to ‘cloud’ to allow the web storage data to be backed up to iCloud, and set to ‘local’ to only allow local backups (iTunes sync). Set to ‘none’ to not allow any backups of web storage. The previous boolean property is deprecated and mapped to ‘cloud’ (true) and ‘none’ (false).

See the Project Settings doc.

5. Graduated the Globalization plugin to core

This plugin was previously in the phonegap-plugins repo (BB WebWorks 5, iOS, Android). The globalization object obtains information and performs operations specific to the user’s locale and timezone.

See the API doc.

6. bin/create script changes

In 2.2.0 by default, the CordovaLib sub-project is copied into your project folder. Previously the CordovaLib sub-project was linked in to your project as a shared project. To still use a shared CordovaLib, add “–shared” as the first parameter to bin/create. This is useful for committers to just point to the CordovaLib from their git repo.

7. uncrustify hook for committers

Uncrustify is a utility that beautifies your code — essentially it enforces certain code formatting conventions. Right now it is only added to the iOS repo as a trial. See the issue:

In the root of your iOS repo, using the command line:

cd .git
rm -r hooks
ln -s ../hooks .

Otherwise, you should run the bin/ command manually before checking in code on iOS.

8. onReset() override for plugins

Add a onReset() method to your plugin — this is called on top-level navigation or refresh, so that plugins can know to cancel any long-running requests and reinitialize themselves. This is for the situation where your WebView has been refreshed, and any operations and callbacks for plugins are invalid.

9. iOS JavaScript-Obj-C bridge improvements

  1. no longer broken for non file:// pages
  2. No longer shows failed requests in the remote web inspector
  3. 15% speed improvement in benchmarks

10. Splashscreen API

The Splashscreen API is now formally documented for iOS and Android.

View the Release Notes for other changes.

Written by shazron

October 27, 2012 at 4:42 pm

Automatic Reference Counting (ARC) and Cordova Plugins

with 11 comments

With the release of Cordova 2.1.0, CordovaLib will have been fully migrated to use Automatic Reference Counting (ARC). In a nutshell, ARC is automatic memory management for Objective-C objects and blocks (simply – you don’t have to worry about retains and releases for the most part).

What does it mean for your third-party Cordova iOS plugins?

Nothing1, if your project itself does not support ARC, and the default project template does not support ARC for Cordova iOS 2.1.0.

If you do upgrade your project itself to ARC through running the Xcode migration wizard from the menu: Edit -> Refactor -> Convert to Objective-C ARC… (then de-select libCordova.a) then you need to be aware that your plugins need to be upgraded since 99% of the plugins out there are not ARC compatible yet.

How do you get your plugin upgraded?

  1. The plugin author should upgrade the plugin to conditionally support ARC (through the __has_feature(objc_arc) macro) which would maintain compatibility
  2. You can upgrade them yourself using the Xcode migration wizard (Edit -> Refactor -> Convert to Objective-C ARC…) and selectively choose the plugin files only
  3. Don’t upgrade but set a compiler flag for your .m file in your Target settings to not compile your plugin for ARC. Select the Build Phases tab, expand the “Compile Sources” list, and select your .m file. Double-click in the “Compiler Flags” column, and enter the value -fno-objc-arc

[1] In the rare case that you encounter a plugin that is ARC only and you need to use it in your non-ARC project, do step 3 above but use the compiler flag -fobjc-arc instead.

Written by shazron

September 5, 2012 at 1:41 am

11 upcoming changes for Cordova iOS 2.1.0

with 37 comments

1. Automatic Reference Counting (ARC) support

Finally the Cordova core has been upgraded to use ARC. Your project does NOT need to use ARC, but you can upgrade your project if you want using the Xcode menu option “Edit -> Refactor -> Convert to Objective-C ARC…”, then de-select libCordova.a. Note that if you do so, your plugins will need to be upgraded to use ARC as well. If doing so for plugins causes problems, you can disable ARC per file.

2. Removal of the (.pkg) Installer

This frankly was a stop gap in 2.0.0 until we removed it entirely. There is nothing to install now, you just download the source, and put it somewhere on your hard-drive in a permanent location. New projects when created using the command-line tool will refer to the CordovaLib that you ran the script from automatically. Note that if you move the source folder, you will need to run bin/update_cordova_subproject to update any existing projects.

3. Removal of the use of CORDOVALIB

In Cordova versions before 2.1.0, the location of the CordovaLib sub-project was through an Xcode variable called CORDOVALIB. So, when you updated your CordovaLib, your existing projects will pick up the new CordovaLib automatically by referencing this Xcode variable. This has proven to be problematic for using multiple versions of Cordova. Now, when you create a new project, the new project will have a hard-coded location for the CordovaLib sub-project, and to update this location you run the bin/update_cordova_subproject script which is located in a downloaded source version.

NOTE: This script updates the location of the CordovaLib sub-project as “relative to group” which means relative to where your project is located. This means, if you move your project folder, the CordovaLib sub-project reference will break (and you need to run the script again). This is mainly for source control purposes (where an absolute location is not friendly for teams). Watch this jira issue for updates.

4. Removal of the VERSION file dependency in code

The VERSION file is read from CordovaLib and set in JavaScript as the variable device.cordova, the code is not dependent on this file anymore (it may still be referred to in the Makefile), and reads the version from CDVAvailability.h at run-time.

5. Removal of CordovaLibApp and CordovaLibTest targets from the CordovaLib sub-project

When the CordovaLib sub-project is included in your project, all of its targets are included in the Schemes dropdown menu as well. This confused a lot of devs, and we removed the two extraneous targets into its own project. Those two targets are only used for testing. So now your Schemes dropdown menu will only include your project’s target, and the CordovaLib target.

6. Command-line scripts supports spaces in pathnames, symlinks

If you had spaces in your path when you ran any of the command-line scripts in 2.0.0, the script will fail. We fixed the problem in Cordova 2.1.0. If you are running 2.0.0, you can fix the problem by just copying in the updated scripts to your project’s cordova sub-folder.

7.  Whitelist format is less strict

Previously, the whitelist required an exact string match, with hostnames/IPs only. Now you can enter a full url with scheme, paths and query parameters – they will be parsed and only the hostname/IP will be considered.

8. New JavaScript->Native bridge

Our previous method used iframes, and starting with 2.1.0, we added an xhr bridge method by default. More details in this JIRA issue. This is to work around crash issues related to iOS UIWebView WebKit. You can change to the previous bridge implementation as well, the details are in the same JIRA issue linked previously. Note however that there is a bug in using the xhr bridge mode in iOS 4.2, so if you are on iOS 4.x, it will automatically default back to the iframe bridge.

9. iOS 6 compatibility changes

Fixed some issues related to the upcoming iOS 6 release. ‘Nuff said.

10. Diagnostics

There have been a lot of problems related to headers not being found, or the Archive build failing. There will be a diagnostics tool to help debug these issues. This tool is not in the rc1 yet, but will be in the final 2.1 release. Watch the related JIRA issue here.

11. New plugin signature (old signature is deprecated)

The new plugin signature is discussed in the Plugin Development Guide for iOS and also the Plugin Upgrade Guide. The old signature is still supported as per our deprecation policy.

Written by shazron

August 28, 2012 at 1:18 am

Posted in cordova, phonegap

Improvements in Cordova 2.0.0 for iOS

with 45 comments

With the release of Apache Cordova 2.0.0 there are some significant changes for the iOS platform. We’ve removed the problematic Xcode templates, and updated our support to iOS 4.2 and greater only. Support for ARC (Automatic Reference Counting) was planned but pushed to a later release (tentatively scheduled for 2.1.0).

1. Removal of the Xcode Templates

Initially we had Xcode 3 template support, so when Xcode 4 rolled in, we updated our templates to support Xcode 4. However, because of Xcode 4′s template limitations, this resulted in a poor user experience when first creating a new Cordova-based Application. The Xcode 4 template format is undocumented – we couldn’t add a folder reference nor add a sub-project, so we had to include a pre-built Cordova.framework and also make the developer copy in the www folder manually.

A developer had to:

  1. Build once to copy in the “www” folder (from the Cordova.framework) into their project folder on disk
  2. Locate the “www” folder in their project folder on disk
  3. Drag in the “www” folder to their project icon in Xcode

This was very error-prone and did not lead to a good “first-run” user experience. Shipping a pre-built binary (Cordova.framework) also causes problems for certain systems (unreproducible crashes with Reachability) and problems with the inability to debug errors in the Cordova library itself.

The Xcode templates have been replaced by our new command-line utility to create a new project.

2. Create a new Cordova-based Application project from the command line

Install Cordova-2.0.0.pkg and then follow the Getting Started Guide, then see the procedure at

Consult this blog post “PhoneGap 2.0 Getting Started” as well for any errors you encounter.

This template creation method eliminates all the problems with the Xcode 4 template. Create the new project, and you are ready to go immediately. Your new project also links in CordovaLib as a sub-project now, so you have access to the Cordova source code for debugging if you need to.

Moving to a command-line interface also allows for greater flexibility in tooling and packaging.

3. Debug, emulate and view the console log of your Cordova project from the command line

When you create a new Cordova-based application project, you will notice that there is a new “cordova” folder included in your project folder. In there, there are three scripts: debug, emulate and log.

Navigate to the cordova folder from, and you can type the appropriate commands to use these scripts. Using these scripts, you will never need to launch Xcode again. Details on what these scripts do are at

4. Support of iOS 4.2 and greater only (and drop iOS 3 support)

What iOS 4 allows Cordova developers to do now is to include the usage of blocks in their plugins. Also, the iOS SDK API is switching to using blocks in most of the framework APIs, and it would be great for Cordova plugins to take advantage of them. JavaScript developers will be familiar with the power of using blocks, they are similar to how they are used in JavaScript (closures and callbacks).

Also, iOS 4.2 specifically has built-in support in JavaScript for WebSockets, the DeviceOrientation API (accelerometer, gyroscope), new JavaScript data types, XHR-2 support, and others. See this blog post for more details.

5. Xcode 4 and Lion & Mountain Lion support only

Some developers are still using Snow Leopard (10.6) – which only has Xcode 4.2 (iOS 5.0 SDK). With the upcoming release of the iOS 6 SDK, there doesn’t seem to be any Snow Leopard support for it. A SDK release is always coupled with a version of Xcode, and all the newer versions of Xcode are for Lion (10.7) and Mountain Lion (10.8) only. The Apple App Store will only accept apps that are built using the latest version of the iOS SDK. When iOS 6 is released, this will preclude Snow Leopard (10.6).

Next steps:

Currently there is still a GUI based installer that installs CordovaLib into your home folder’s Documents sub-folder, and it also updates the $(CORDOVALIB) Xcode variable. The GUI installer will be removed in a future release, and installation will be through the command-line as well. This will allow us to version and package Cordova iOS through homebrew, for example.

Written by shazron

July 20, 2012 at 6:38 am

Posted in cordova, phonegap, xcode

Apache Cordova lifecycle events in iOS 4 versus iOS 5

with 9 comments

Cordova has lifecycle events – “pause” and “resume” which are documented in but there are two more events for iOS that are undocumented, “resign” and “active”. These events correspond to when the app is leaving the active state (UIApplicationWillResignActiveNotification) and when the app enters the active state (UIApplicationDidBecomeActiveNotification), respectively.

In iOS 4, the “resign” and “active” events can be used to detect when the Wake/Lock button has been pressed exclusively, but in iOS 5, this has slightly changed. In iOS 5, the “pause” (UIApplicationDidEnterBackgroundNotification) and “resume” (UIApplicationWillEnterForegroundNotification) events are triggered as well (see  the section Moving to the Background) BUT only if your app’s UIApplicationExitsOnSuspend setting in your Info.plist is NO (i.e. multi-tasking is enabled) .

This in essence tells devs that apps when in the “locked” state are put into the background as well if the app is allowed to multi-task in iOS 5, while in iOS 4, locking will never put your app into the background, ever.

iOS devices that do not support multitasking (the iPhone 3G and iPod Touch 2nd Generation – even under iOS 4), and apps that set their UIApplicationExitsOnSuspend setting in their app’s Info.plist to YES (i.e. no multi-tasking), will never get the “pause” and “resume” events, of course.

tldr; So – if you want to have your app still in the foreground running when your device is locked – and you are running iOS 5 – you will have to DISABLE multi-tasking for your app (UIApplicationExitsOnSuspend set to YES).


Get every new post delivered to your Inbox.

Join 1,412 other followers

%d bloggers like this: