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 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 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*/''/*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

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

Results from the PDI/Kettle user survey

I just wanted to post results from the PDI/Kettle user survey I ran a few weeks ago.

I marketed this on the pentaho forums and twitter (got a nice retweet from @pentaho). I wasn’t sure how to reach more of the PDI audience.

I received almost 20 responses, but I know that this is only a tiny portion of the PDI userbase (after all, in the last week, kettle 4.4.0 has been downloaded over 110,000 times since it was released last November). So these results are of mostly anecdotal interest.

Here are the results.

Primary Role Using PDI

The ‘other’ category ranged from “I do everything” to “Data Warehouse Architect”. It was interesting to me that so many folks were developers, but that the resources for testing PDI (and version control and other kinds of developer type tasks) are so sparse.  Or maybe I’m just not aware of these resources.

Number of Years of Using PDI

Again, it is interesting to me that most of the people (over 75%) who responded to my survey have over two years of PDI experience. I would have thought that there would be a higher percentage of new users, at least from the forums.  And I’m bummed Matt Casters didn’t fill it out!

Thanks to everyone who participated!

If you’d like to get on a low traffic list and hear more of my thoughts about Pentaho Data Integration Development, sign up for the PDI development 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

© Moore Consulting, 2003-2017 +