Saturday, 31 January 2015

How to manually add Cordova plugins to your app

I have recently been trying to add a plugin to an existing Cordova app (using Cordova 3.7.0).  Since I didn't create my app using the CLI I had 2 options:


  1. Create a new app using the CLI and copy my source files over
  2. Add the plugin files to my existing app


For some reason I don't really like the idea of the CLI and wanted to do do this manually into an existing Android app, using Cordova, rather than use the CLI.  Don't ask me why, I just like doing things manually so I know what's going on under-the-hood I guess

If you are like me and want to add a plugin manually, this is how to do it.  These instructions, though written for Android, will work for any any supported platform.  I will call out any differences between platforms that I know of

Get the plugin source files

You need the source code files for your platform (so .java for Android, .m .h for iPhone etc) as well as the plugin javascript files.  You might be able to get the source files from the internet but if not you need the CLI anyway so get them.  Also if you've never set up your app for plugins before you need a cordova file called cordova_plugins.js

Install the Cordova CLI

Follow the Cordova instructions on how to install the CLI up to the point of having a working cordova command.  You need git and node.js installed

Create a dummy app

Create an app, it doesn't really matter what you call it, we're just using it to create the source files we need so we can copy them.  I've called mine hello after the instructions in the above tutorial

  cordova create hello com.example.hello HelloWorld

This will create a cordova app in a hello directory

Change into the created directory

  cd hello

I don't think you need to add platforms if you're not using the CLI to build the apps.  It doesn't do any harm though so run the command(s) if you want to

Edit: Note you will need to do this if you have never used a plugin in your app before as there is a source file you'll need to copy.  If you are adding Android then Cordova insists on you having Android-19 SDK installed

  cordova platform add android (or whatever platform you want)

At this point you have created your dummy app and can add your plugin(s)

Download the plugin source files

You need the name of the plugin you want to download, which can be obtained from the official Plugin API pages.  The one I wanted was the Network Information plugin, so this is the example I will use.  Replace the name with the one you want

Using the CLI, still in the dummy hello directory, install the plugin

  cordova plugin add org.apache.cordova.network-information

This will install the plugin source files you need.

Copy the source files into your app

The source file you want (eg .java for Android) are in the plugins/<plugin-package>/src/<platform> directory of the dummy app.  Copy this to the source directory of your app.  The file will be in an apache package, so either you need to create that package, or change the source file package declaration

In my case I placed the NetworkManager.java file in an org.apache.cordova.networkinformation package file

Copy the javascript files

The plugin javascript files you want will be in the plugins/<plugin-package>/www/ directory.  You need to create a new directory in the assets/www/plugins directory of your app with the same package name eg
  /assets/www/plugins/<plugin-package>/www/source-file.js

If you've never used a plugin in your app before you also need a javascript source file.  You need to add a platform to do this, so do that as above.  Then copy the platforms/android/assets/www/cordova_plugins.js file to your assets/www directory in your app

Also note that you must call the original (not the plugins one you just copied) cordova javascript file cordova.js.  I had it called cordova-3.7.0.js and it didn't like it

You don't need to link any of these .js files to your .html page, they will be picked up automatically provided you have cordova.js linked, which you should have anyway if you are using cordova

Add entry to config.xml

You need to add an entry to your Cordova config.xml file found at res/xml/config.xml

You can copy it from the dummy app at platforms/<platform>/res/xml

In my case the entry looks like

    <feature name="NetworkStatus">
        <param name="android-package" value="org.apache.cordova.networkinformation.NetworkManager" />
    </feature>

And you're done


That's it, the plugin should now be available for use.  You can use the instructions from the plugin API page as normal.  Have fun :)





Wednesday, 28 January 2015

Manual upgrade of Apache Cordova for Android (2.9.0 to 3.7.0)

I hadn't upgraded Cordova for ages and was still on version 2.4.0 (now at 3.7.0 at the time of writing). so I was surprised, but mostly dismayed, that I now had to use the Cordova tools to create apps.  Maybe it is just me but I liked being able to copy the jar, javascript file and config into an Android app myself.  I did have a go at using the tool, but the npm still didn't create the jar I wanted and I'd be forever tied into using the tool.  So I spent some time working out how to upgrade manually, and this is how to do it.  

This obviously relies on you having java and android installed, which I'd guess you have if you're upgrading an Android app

Step 1

Download the latest zip file from http://cordova.apache.org/ and unzip it.

Step 2 

Install android if necessary and add it to the OS path.  You need ANDROID_HOME set or the android executable on the path.  I added both.

Make sure you have Android version 19 installed from Android's SDK manager

Step 3

Install ant and add it to the OS path so that ant can be executed from the command line

Step 4

Using a command line tool (cmd or bash, or whatever) change directory (cd) to the where you unzipped the cordova zip and cd into the package/framework directory

Run the following command

ant jar

If you get the error message that you need to create 'local.properties' run the following command first (then run ant jar)

android update project -p .

This will create the jar file called cordova-<version>.jar

Step 5

Copy these files from the unzipped cordova directory into your Android app directory structure:
  • the created .jar file to your /libs directory (will be in the framework directory where you created it)
  • cordova.js from the assets directory in the zip file to your app assets directory
That's all I needed to do.  The settings all worked as before and now I've upgraded.  I hope this helps someone and it isn't just me that doesn't want to have to use the Cordova tools :)