Chapter 1

As I’ve mentioned before, Apache Cordova is a pretty fast moving project. There’s a lot of people on the team and because there’s multiple parts, separate teams work on each. The end result of this is that each part of Apache Cordova (CLI, Plugman, APIs, platform support) has its own release process. Since they’re broken out into separate releases, there’s no common version maintained across the whole project.

As you know, the book is called Apache Cordova 4 Programming and the intent was to cover Apache Cordova 4.x and support (as much as possible) the major version that follows as well. When the Apache Cordova team released Apache Cordova 4 in October 2014, it was only the CLI that was numbered with the 4.0 version; the platforms and plugins were all in a 3.x version. Early in 2015, platforms like the Android platform and others were updated to 4.0.

The good news is that for the most part most things interact pretty well regardless of the version, as long as they’re close. More good news is that some of the mobile platform components were upgraded to version 4.x right about the time this book came out.

The bad news? The Cordova CLI was updated to version 5.0 about a week after this book was released. So, if you’re looking at this book, with 4 in the title, and the Cordova web site and seeing that 5.0 has been released, you may think that this book is obsolete. It’s not!

The reason the Cordova team made the leap from Cordova 4 to Cordova 5 was because of some pretty major changes to the CLI. Since Cordova 3 and the CLI was released, the Cordova team has struggled a bit with where to put things. If you remember from the early days of the CLI, plugins were originally published on GitHub and you loaded the plugin using the plugin’s GitHub repository name. Very quickly thereafter, the team started instead to have the CLI access plugins by their unique ID (org.apache.cordova.device for example). Next, everything started moving to npmjs.org (Node Package Manager) and they decided to change the CLI version number when they did so.

This changes nothing for Cordova developers for the first 6 months, everything will continue to work the same. Later, after things have stabilized, all plugin IDs will change and everything will be loaded using npm. Look at Everything as Node Modules topic for more information about this change.

Chapter 4

Setting Plugin Search Path

In Chapter4, I explained how you could pass some JSON content on the command line to the Cordova Create command to automatically set configuration values in the project’s config.json file (.cordova/config.json):

cordova create test2 com.johnwargo.test2 Test2 "{\"plugin_search_path\":\"d:/dev\"}"

This no longer seems to be working with later versions of the CLI. I’ve asked the Cordova Development team to clarify.

Everything as Node Modules

While I was working on the book, the Cordova team started planning a move of much of the framework’s supporting project files and plugins to npm. Beginning with Cordova CLI version 5.0, that migration has been completed and all of the core Cordova plugins are now retrieved from npmjs.org. You can read more about this at http://cordova.apache.org/announcements/2015/04/21/plugins-release-and-move-to-npm.html.

Because npm packages have a different naming structure, as part of this migration to npm, the Cordova team changed the names of all of the plugins. Yeah, I know, nightmare.

Previously, the plugins used a reverse domain format, so the device plugin was accessible using the following ID:

org.apache.cordova.device

In the new version, the plugin IDs are based on cordova-plugin-plugin_name, so, for example, to add the device plugin to a project using the Cordova 5 CLI, you would use:

cordova plugin add cordova-plugin-device

Fortunately, the Cordova team has implemented a mapping between the old naming scheme and the new one, so for 6 months (or so) from the Cordova CLI 5.0 release, you’ll be able to install any of the core plugins using its old ID. At the end of this period, the plan is to remove the mapping and everything should have moved over to the new ID naming scheme.

You can use the new ID now, for example when you list plugins using the following command:

cordova plugins

You get a plugin list that looks like the following:

cordova-plugin-device 1.0.0 "Device"
cordova-plugin-whitelist 1.0.0 "Whitelist"
org.apache.cordova.contacts 0.2.16 "Contacts"

Where I’ve installed some plugins using the new ID format and some with the old ID format. All of this works now, the only problem will be in 6 months when the mapping is removed and only the new ID format will be used.

The mechanics of plugin management haven’t changed, only the IDs for the core Cordova plugins although I expect that most plugin developers will adopt this naming as well. Refer to the article referenced in the first paragraph of this page for information on how to add your plugins to the mapping feature so users will be able to install your plugins using both the old and new ID format.

Chapter 05

Whitelist Changes (Whitelist Plugin)

On page 132, I describe how you can use the access element in a Cordova project’s config.xml file to control what server endpoints the application can access. By default, the access element is set to:

<access origin="*" />

Which means that the application can access any endpoint. The intent is that access is wide open by default and before the application is published, the developer removes the default setting and replaces it with one or more access elements that the application actually needs. With the correct settings in place here, the application can only access content from the specified sources, and the application is protected (more or less) from malware.

For security reasons, the Cordova team decided that this wasn’t enough protection, so they re-architected the security model and implemented this whitelist capability as a core plugin. By default, Cordova applications can now access only file URLs. To access any remote endpoints, the developer (you) will need to add the new Whitelist plugin to your application (the plugin is described here: https://github.com/apache/cordova-plugin-whitelist) and make some different changes to the plugin.xml file.

The plugin.xml file supports new elements that control the whitelist plugin:

<!-- Allow links to jwargo.com -->
<allow-navigation href="http://johnwargo.com/*" />
<!-- Wildcards are allowed for the protocol, as a prefix
     to the host, or as a suffix to the path -->
<allow-navigation href="*://*.johnwargo.com/*" />
<!-- A wildcard can be used to whitelist the entire network,
     over HTTP and HTTPS. *THIS IS NOT RECOMMENDED* -->
<allow-navigation href="*" />
<!-- The above is equivalent to these three declarations -->
<allow-navigation href="http://*/*" />
<allow-navigation href="https://*/*" />
<allow-navigation href="data:*" />

When you look at the default config.xml created by the Cordova 5 CLI, you’ll see that the file includes new settings that allow a developer to identify the external connection types it will allow as well:

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.johnwargo.cdva5" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
   <name>CDVA5</name>
   <description>
       A sample Apache Cordova application that responds to the deviceready event.
   </description>
   <author email="dev@cordova.apache.org" href="http://cordova.io">
       Apache Cordova Team
   </author>
   <content src="index.html" />
   <plugin name="cordova-plugin-whitelist" version="1" />
   <access origin="*" />
   <allow-intent href="http://*/*" />
   <allow-intent href="https://*/*" />
   <allow-intent href="tel:*" />
   <allow-intent href="sms:*" />
   <allow-intent href="mailto:*" />
   <allow-intent href="geo:*" />
   <platform name="android">
       <allow-intent href="market:*" />
   </platform>
   <platform name="ios">
       <allow-intent href="itms:*" />
       <allow-intent href="itms-apps:*" />
   </platform>
</widget>

Chapter 15

Inconsistent use of platforms

During the formal manuscript proof review I noticed that I illustrated something inconsistently. In the commands I executed to create the sample project, I showed the commands being executed on my Windows box, but later added ios as a platform option to the code. I did this for demonstration purposes, that would not have worked (today) on Windows.

In order to do this accurately, I should have done the example on OS X and showed the appropriate output. My apologies.

The Cordova team is playing around with allowing you to manage projects with platforms that are not supported on the OS running the CLI, but I don’t think that’s been implemented yet.

Chapter 16

Publishing Plugins

As part of the move to npm for plugins described in this post, there is an extra step you need to complete to prepare your plugin for publishing plus there’s a new publishing process. All of these steps are described in http://cordova.apache.org/announcements/2015/04/21/plugins-release-and-move-to-npm.html.

Basically, you create the plugin.xml and code your plugin’s stuff. Before publishing, open a terminal window and execute the following command:

plugman createpackagejson [PLUGIN DIRECTORY]

This will create the package.json file npm needs to publish your plugin.

Next you’ll want to add a readme.md file to the plugin project folder. Populate the file with anything you want your plugin users to know about your plugin.

With those two pieces in place, navigate to the plugin directory and execute the following command to publish your plugin to npm:

npm publish

That’s it, that’s all there is to it.

I published the mol plugin from Chapter 16 to https://www.npmjs.com/package/johnwargo-cordova-plugin-mol. You can add it to a project using the following command:

cordova plugin add johnwargo-cordova-plugin-mol

I published the carrier plugin from Chapter to https://www.npmjs.com/package/johnwargo-cordova-plugin-carrier. You can add it to a project using the following command:

cordova plugin add johnwargo-cordova-plugin-carrier