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 :)





No comments:

Post a Comment