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:
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
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.
In my case I placed the NetworkManager.java file in an org.apache.cordova.networkinformation package file
/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
- Create a new app using the CLI and copy my source files over
- 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.jsInstall 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 declarationIn 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 :)
Comments
Post a Comment