Skip to content

How to ‘plugman’ify an existing plugin

In a previous post, I talked about adding a new plugin that you wrote to your Cordova CLI project. However, there are a ton of existing plugins out there, and many of them haven’t yet migrated over to the new plugman architecture. What should you do when there is a plugin that solves your problem, but is not installable via plugman?

Your options include:

  • install the plugin the old fashioned way, by downloading and copying its files into your project directory. This is a a bad idea because if there are future bug fixes or feature improvements to the plugin, you’ll have to manually pull them in.
  • forego the plugin. But you are looking at it specifically to save you time or allow you to implement a feature that would otherwise be too hard or time consuming–so you can’t exactly ignore it.
  • search for another plugin that does the same thing–great, if you can find it.
  • make the plugin plugman compatible–this is the best option.

The first step to making a plugin plugman compatible is to file a bug/issue with the project. Perhaps they are already planning to do this work, and a request from you will get it moved up the queue. If so, fantastic–see when they think it will be done. If not, at least you’ve let them (and others who look at the issues list) know that this is something they should do.

If it won’t be done in your timeframe (or at all), you can do it yourself. The main tassks are writing a plugin.xml file, and possibly modifying some javascript files. Start with the plugin.xml spec.

Before you plunge in, though, think about the licensing surrounding the plugin, as, unless you are replacing everything or the license is extremely permissive, your contributions will need to be under the same or a compatible license as the original code, especially if you want to contribute the changes back.

You want to make sure you use version control. If you are modifying a plugin on github, it is as simple as forking that project. You may be able to take the plugin code and import it into your version control system.

Write the plugin.xml file, and make sure to check it into the version control system. Writing a plugin.xml file is straightforward; however, there are two ways to handle javascript–you can treat it as an asset, where plugman dumbly copies it to the www directory wherever you tell it to, or you can treat it as a js-module. Plugman does some extra work for js-module javascript, including injecting it into the index.html and adding the created javascript object to the window object. Using js-module is the preferred method, but you may have to edit the javascript files and remove any cordova.define syntax. Also, if you need to move plugin files around, or rename them to help code maintainability, do so.

Test and install it just as you would any other plugman managed plugin (cordova plugins add http://...).

Once you’ve done this and it works, consider pointing to your plugin.xml in your open bug. Some authors may be receptive to code contributions or pull requests.

In the next post, I’ll discuss how Cordova CLI helps you release your application.

Subscribe to my infrequent Cordova newsletter

How to set up a new plugin for use with Cordova CLI

The first step whenever you feel you need access to native functionality for a phonegap/cordova application is to search for a pre written plugin. Unfortunately, at this time there is no central repository. There is phonegap plugins github repo, but I always find myself reverting to searching with google–there are lots of plugins that are described on blogs (web intent, application preferences) that are not present in the phonegap plugins github repository.

However, if you can’t find a plugin that does something you want, you will have to write your own. First, get the plugin working using an IDE or placing the code directly under the platforms directory in a new project (so that you can minimize external complexities). Get the plugin running in your phone and/or emulator. There are plenty of tutorials on writing a cordova plugin, not least of which is the one in the phonegap docs.

After it is running, you want to convert it to a plugman compatible plugin. Plugman is a tool for managing cordova plugins (and, incidentally, is planning to support a directory of plugins). You configure how plugins are installed by writing a plugin.xml file; here’s the plugin.xml spec. This document well worth reading a couple of times closely, as it specifies what you can ask plugman to do when installing a plugin.

Create a new project in your version control system and copy in the plugin files previously tested, as well as the plugin.xml. Make sure they are all committed.

Then you go to your project and run cordova plugins add http://github.com/path/to/plugin.xml. From the plugman documentation, it looks like you can install a plugin from a local path, rather than a URL, but I have not done so.

Note that when you check out the source tree on a different machine, you will want to run cordova plugins add http://github.com/path/to/plugin.xml again. Putting a list of these in an after_platform_add hook script will ensure that this happens automatically.

The next post will discuss how to take an existing plugin and have it work with Cordova CLI.

Subscribe to my infrequent Cordova newsletter

Platform specific configuration files with Cordova CLI

I previously posted about using the merges directory to handle situations where your css or javascript differed between platforms.

However, there are cases where platform specific Cordova configuration differs from that created by cordova platforms add [platform]. In this case, if you want to version control the configuration changes (and you should) you need to write a hook to copy over the configuration file from a well known location. I create a top level directory called config and underneath that have platform specific directories.

However, there are two types of platform specific configuration to consider. The first type aren’t modified by any other processes–application icons and splash screen images are examples of this. In this case, your hook script can live in .cordova/hooks/after_prepare and be run every time. Therefore, if you switch out a splash screen with a new image, it will show up the very next time you run cordova build.

The second type of platform specific configuration file is one that is modified by other processes; for example, plugins often modify AndroidManifest.xml. In this case, if you were to put the copying script into after_prepare, your plugin changes would be removed unless you reinstalled your plugins every time. The better part of the build lifecycle in which to execute your copy script is after_platform_add. This means, however, that when you need to change such files, you’ll need to remove and re add the platform (or merge your changes manually).

In the next post, I will discuss adding plugins using Cordova CLI.

Subscribe to my infrequent Cordova newsletter

Platform Specific CSS/Javascript with Cordova CLI

Cordova CLI has a really good setup for merging in content that is platform specific under the www directory.

Basically, under the merges directory, you can place platform specific directories; mimic the names under platforms. Under that you can create directories named the same as directories under wwwcssor js, for example, and the files under those directories will be copied to the platforms build directories by the cordova prepare command.

The merges directory is useful, but limited.

When we had a Cordova app mocked up by a great phonegap consultancy, the end deliverable included large chunks of common css, but some platform specific CSS. Cordova CLI has no issue with this. Another use case would be presenting a common interface for plugins for different platforms that have slightly different APIs–you can write platform specific adapter objects, and place the platform specific javascript into merges. Here’s an article about another purpose for merges.

merges are limited, because only directories under www is merged. If there is anything else you want to modify that is outside of that directory (like, say, AndroidManifest.xml), well, you are out of luck.

Luckily, hooks come to the rescue again. In the next post, I will discuss how to update platform specific files using Cordova CLI.

Subscribe to my infrequent Cordova newsletter

Setting up CORS

So, this is not Cordova CLI specific, but being able to develop as much as possible in your web browser (with the quick feedback) is one of the benefits of Cordova, so I’ll cover it briefly.

If your data sources and your application are served from the same server (or proxied so that they look like they are) then you are good to go–no violation of the Same Origin Policy occurs.

If they are on different servers, then your browser is going to restrict access. However, if you aren’t sending any special headers and are only interested in reading data from your remote data source, or POSTing using limited mime types, you can get away with setting the Access-Control-Allow-Origin header to * on your data sever, and everything should work OK.

If you are using PUT, or sending special headers, or doing anything outside the box, you will want to preflight your requests with an OPTIONS header, as outlined here.

Basically, when a request comes in, you have to send back these headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER
Access-Control-Max-Age: 1728000

For development, the * for Access-Control-Allow-Origin is again fine. Note that if you specify a host and the server caches the response (if it is a proxying cache, for example) and you lock down Access-Control-Allow-Origin and more than one host tries to access this server, it will cause issues. Like, “the second request will fail” issues. This is not really a concern for development servers.

In addition, make sure that OPTIONS request can get through (another SO question I asked).

Note that this is only for development in the web browser (including ripple). Once you move to emulators and phones, you will be concerned about Cordova whitelists and not CORS.

In my next post, I will cover the merges directory.

Subscribe to my infrequent Cordova newsletter

Configuration management using Cordova CLI

Managing different builds of your Cordova application is relatively easy using hooks.

I actually have a number of deployment environments, all built from my local source tree.

  • web development, which lets me crank out the non cordova specific look and feel
  • test, which runs qunit/sinon unit tests
  • ripple development, which lets me run in the browser, but still test cordova specific events (online/offline, for example)
  • staging, which is used to build a phone distributable binary, but runs against our QA servers
  • production, the same as stage, but against our production servers

The first two don’t require a cordova prepare but the last three do. The first three let you make changes in files and reload your web browser, where the last two require a phone or emulator to run.

For a while I was switching between these manually, but eventually it became a pain, so I automated it. The automation is driven off an environment variable, which is accessed by a after_prepare hook: TARGET=stage cordova build android sets target to stage, and process.env.TARGET is the nodejs code in the hook script that can access that environment variable.

There is a config directory in the top level of the project and in there is a project.json file that contains project specific configuration for each target environment, like the server hostname.

One wrinkle that took me some time to figure out was how to have code that was in the www directory ‘just work’ out of the version control system, so I could do quick web development. In the end, I have code like this in my javascript files

App.config = {};
App.config.datahostname = /*REP*/'qa-host.com'/*REP*/;

and then this regular expression to replace it with the value from the configuration file when file is being prepared:

function replace_string_in_file(filename,to_replace,replace_with) {
  var data = fs.readFileSync(filename, 'utf8');
  var result = data.replace(new RegExp(to_replace,"g"), replace_with);
  fs.writeFileSync(filename, result, 'utf8');
}

...
// iterate over files to be updated with config info
replace_string_in_file(fullfilename,"/\\*REP\\*/'qa-host.com'/\\*REP\\*/",configobj[target].datahostname);

Note that I don’t read/write files async–this happens rarely enough that the performance increase isn’t worth some of the weirdness you will see if more than one hook acts on your file, or if you edit the file right after running the hook.

Since /*REP*/stuff/*REP*/ isn’t likely to match anything inadvertently, you could probably parse all your files, but my configuration is limited to 3-4 files, so it is easier just to name them explicitly.

Note that if during development, your javascript needs to access data served by a different web server (an API somewhere, for example), you’ll need to set up CORS correctly. We’ll set that up in the next blog post.

Subscribe to my infrequent Cordova newsletter

Hooks and Cordova CLI

Hooks are scripts that you can run before and after each stage of the Cordova CLI lifecycle. They live in a projecthome/.cordova/hooks/before_xxx (or after_xxx) where xxx is the project lifecycle stage (prepare, build, etc).

They are somewhat documented here, and here’s an example you can “borrow” from. As we’ll see in the next few posts, they are a lifesaver at dealing with some of the current deficiencies of Cordova CLI.

But to start with, all you need to know is that hooks are chunks of code that are passed the project base directory as the first argument (and therefore available via var rootdir = process.argv[2]; for node, or $1 for shell scripts). These chunks can be any kind of executable code (shell/node/perl/python/compiled c, etc). All I focus on here are project specific hooks–I don’t know how module hooks would work.

I have typically used hooks to move and manipulate files and used node (though you can use any scripting language) and am a node newbie–therefore stackoverflow and the node filesystem API docs were my friends.

Each hook is executed in alphabetical order within the before_ or after_ directory. A good idea is to name each hook to make the order explict:

  • 001_script
  • 010_script
  • 020_script
  • 120_script

executes scripts in the order you would expect, where:

  • 1_script
  • 10_script
  • 20_script
  • 120_script

does not.

In addition, if you write node scripts, consider using the synchronous versions of the file manipulation commands. While the default node commands (to move a file, say) are asynchronous, and therefore fast, for a build environment I have seen confusing results if I didn’t make everything synchronous. If you need the build process to be faster, then consider going async, but know what you are doing.

In the next post, I will discuss configuration for different environments.

Subscribe to my infrequent Cordova newsletter

Upgrading projects managed with Cordova CLI

I’d like to preface this post by saying that I’ve upgraded Cordova CLI 5-6 times on one project, but haven’t upgraded after submitting to any marketplace (the app store, etc) or after using plugins. I have, however, done some customization of the app.

Like I mentioned before, Cordova CLI is a moving target. So, you should be prepared to deal with upgrading your toolset. There are two types of updates–minor and major. Major will require more testing since APIs could change.

Just a heads up that 2.9.x is the last stable release of the 2.x codebase and the team has promised to support it for a long time (but not with new features). I have no idea how hard it will be to move a app from 2.9.x to 3.0.x, but I imagine there will be many plugins that won’t move to the new architecture, so I expect 2.9.x to be around for quite a while.

You can see if there is a new release of Cordova CLI by running npm outdated -g cordova.

To update either kind of release major release:

  1. Make sure that all your code is checked in (you are using version control, right)
  2. Move your old project directory to project.2.8.1
  3. Move your ~/.cordova directory to ~/cordova.2.8.1
  4. Checkout your project directory from your version control system
  5. Run npm update -g cordova@2.9.3
  6. Check out your project from source control
  7. cd project
  8. mkdir platforms; mkdir plugins
  9. cordova platforms add [your platforms]
  10. cordova plugins add [your plugins]
  11. continue development

This illustrates why it is so important to keep everything in version control. Because Cordova CLI controls the platforms and plugins directories, you have no idea what is happening in there, so any code or configuration that is in there should not be customized. For one thing, when you change versions of cordova, the cordova.js file that lives under platforms may or may not be changed–that’s why we re-add the platforms.

In my next post, I will discuss what hooks are.

Subscribe to my infrequent Cordova newsletter

Placing Cordova CLI projects under version control

If you do software development, you should use version control, and Cordova projects are no different. However, Cordova CLI generates a fair number of derived artifacts which shouldn’t be placed under version control.

The typical Cordova CLI project has at a minimum these directories in the project.

  • www: where your html, css and javascript live
  • merges: platforms specific html, css, javascript
  • .cordova: ‘under the hood’ cordova files and directories, and lifecycle hook scripts
  • platforms: platform specific build directories
  • plugins: downloadable plugins

Based on this Stack Overflow question (which I asked), as well as my experience, the first three directories above should be versioned, and the latter two added to your version control system’s ignore file.

You can, of course, add additional top level directories, and as we continue to explore Cordova CLI, I will show you the directories I have found useful in my development. I don’t think it really matters much which version control system you use–just use one!

In the next post, I will discuss upgrading Cordova CLI, one of the great reasons to keep these directories under version control.

Subscribe to my infrequent Cordova newsletter

Installing And Using Cordova CLI

This will be a short post as Kerri Shots has written up fantastic instructions for installing Cordova CLI. You’ll want to read them carefully. These instructions are a tad out of date, and describe installing the tool on MacOS. I was able to use these as a guide and get Cordova CLI running on Linux (specifically CentOS 6.4), but had to make some modifications (mostly just to get the android SDK running on my version of Linux).

There is also a good doc explaining installation and usage of Cordova CLI in the Github repository.

I also tried installing Cordova CLI on Windows 7. I was using cygwin, but wasn’t able to get the emulator started, and just decided to go with Linux in VirtualBox. Apparently there is an open bug about installing Cordova CLI on Windows 7. For what it is worth, Kerri was skeptical about installing Cordova CLI on any Windows as well.

That said, I know that Cordova supports Windows Phone development (which requires Windows), so I imagine that if this isn’t fixed, it will be soon. If you know any resources for installing Cordova CLI on Windows, please let me know or add a comment.

In the next post I’ll discuss version control.

Subscribe to my infrequent Cordova newsletter