PhoneGap/Cordova – Adding Plugins

April 9, 2014By 11 Comments

If you’re using the PhoneGap or Cordova CLI’s, it’s important to know there are multiple ways to add a plugin to your project but the end result is the same. At first it may seem a little confusing with the different ways of adding them, and some may think it’s actually a different plugin being added depending on which CLI or specific command being used, however, it’s all the same in the end. The CLI’s are meant to be compatible and flexible, and you should always keep in mind that the PhoneGap CLI is just a wrapper over the Cordova CLI with command line support for PhoneGap Build. The point of this post however, is to clear-up plugin addition confusion.

This information pertains to those using PhoneGap/Cordova v3.0. If you’re not using it, it’s highly recommended. :)

Adding Plugins

If you are starting a project and ready to add some core PhoneGap/Cordova API plugins, you have many choices. Here are some examples of adding the Camera plugin for instance:

Using the PhoneGap CLI

Add Plugin Commands

  • $ phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
  • -OR-

  • $ phonegap local plugin add org.apache.cordova.camera

Using the Cordova CLI

Add Plugin Commands

  • $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
  • -OR-

  • $ cordova plugin add org.apache.cordova.camera
The console output looks a bit different but the package and end result is the same.

Console Output

You should also be aware that between and within the CLI’s, the console output from your plugin add command varies slightly, but don’t let that confuse you. For instance, notice the console output from adding plugins with the different commands below:

Using the PhoneGap CLI

Via Repo URL

$ phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git

Console Output
[phonegap] adding the plugin: https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
[phonegap] successfully added the plugin

Via Plugin Registry

$ phonegap local plugin add org.apache.cordova.camera

Console Output
[phonegap] adding the plugin: org.apache.cordova.camera
[phonegap] successfully added the plugin

Using the Cordova CLI

Via Repo URL

$ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git

Console Output
Fetching plugin "https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git" via git clone

Via Plugin Registry

$ cordova plugin add org.apache.cordova.camera

Console Output

Fetching plugin "org.apache.cordova.camera" via plugin registry

These messages are simply meant to be informative and tell you where the plugin is being retrieved from, but the end result in every case will be the same exact plugin code with the package name of org.apache.cordova.camera.

I personally like to use the package name syntax when adding plugins. Mostly because it’s the shortest and easiest to remember since all of the core plugins have the same package name up to the final package (ie: org.apache.cordova.*).

Adding 3rd Party Plugins

You can also add any 3rd party plugins found in the Plugin Registry via the package name, similar to above. For instance, if you now want to add this 3rd party plugin to your project using either the PhoneGap or Cordova CLI with the package syntax, you could simply add it like this:

  • $ phonegap local plugin add com.photokandy.videothumbnail
  • $ cordova plugin add com.photokandy.videothumbnail

Non-Registry Plugin Addition

There are also many plugins out there that are PhoneGap/Cordova 3.0+ compatible, but may not have been submitted to the Official Plugin Registry. You may find these in a Google search and end up at a github location, but not find it in the Plugin Registry. In this case, you can still add them, you just need to use the github URL syntax.

For example, let’s assume you want to use this custom Social Sharing plugin that you found the github location for via Google. The first thing you should do is check for the plugin to be 3.0 compatible. The easiest way I find to do this is to look for the existence of the plugin.xml in the root of the project. Fortunately most developers also mention the version in the Readme. (Most of the ones I’ve come across have been updated for v3.0, so this should not be an issue).

Then just run the command below from your chosen CLI, pointing to the github root URL, and the plugin will be installed and ready to use:

  • $ cordova plugin add https://github.com/EddyVerbruggen/SocialSharing-PhoneGap-Plugin
  • $ phonegap local plugin add https://github.com/EddyVerbruggen/SocialSharing-PhoneGap-Plugin
The method above pertains to creating your own custom plugins as well. You just need to ensure you’ve created the plugin.xml and then put your plugin in a public github account to be used by anyone. See here for more details on what is needed specifically. If you do create your own plugin and want to make it public, the best thing is to submit to the Official Plugin Registry too for easy discovery.

The last thing I want to make note of here, is that there is no difference between a PhoneGap or Cordova Plugin. They are one and of the same regardless of wording or title. I’ve been asked about this multiple times before so I want to make it clear that they can be used the same within any project whether you’re using either the PhoneGap or Cordova CLI or PhoneGap Build, they ALL extend from the same base classes. Please feel free to comment if you have further questions on any of the above.

Filed in: CordovaMobile DevelopmentPhoneGapPhoneGap 3.0 Tags:

About the Author ()

Comments (11)

Trackback URL | Comments RSS Feed

  1. Nathan Prather says:

    Thanks for the great article!

    I’m thinking about creating a custom plugin for Phonegap and looking for the best way to distribute it so this article helps a lot…

    I do have a question, I’ll provide some details:

    I plan to create a custom plugin that will be a free open source scaled down version hosted on GitHub. It’s going to be a lot of work for me to build and support it and I have bills to pay so I was going to also create a premium version of the plugin for sale on a separate website…

    Ideally I could have the code for the premium version be more like a library and just include the binaries instead of the full open source…

    Is this possible with Phonegap? What about using it with the Phonegap Build Service?

    Thanks!
    Nathan

    • Hi Nathan!

      Yes, you can have binary in the project for a premium version of a PhoneGap plugin, however it’s not currently supported in PhoneGap Build. The support for it should be coming in the future, just no particular date I can give you as of yet. Take a look at this plugin built by one of the Senior PhoneGap engineers for reference to including binary – https://github.com/shazron/TestFlightPlugin. You can see it includes a TestFlight.jar file in the src/android/libs folder.

      Hope that helps!
      Holly

  2. Glen says:

    Always find your blog informative. Have you had a chance to work with one of the email plugins yet?

  3. Adam says:

    How can I submit a plugin to the Official Plugin Registry?

  4. Jim Bergman says:

    Hi Holly, your write ups are always terrific and very useful. A question about updating plugins. I’ve checked the plugman CLI and the plugin specs, and can’t find anything about updating a plugin to the latest version. Is uninstall/reinstall the only way right now, or is there an update option, like with npm? Thanks sensei!

  5. Sam Clopton says:

    Hi Holly,

    Is there a way to manage/install a specific version number of a plugin so that us — as developers — can lock down our plugin dependencies? Would be nice to see phonegap/cordova have a dependency manager similar to bundler, npm, bower, cocoapods, etc… that could keep track of this for us.

  6. Greg says:

    Exactly what I needed thank you!

  7. Has anyone figured out a way to deal with the intermittent (or consistent) issue where adding a plugin via the CLI does *not* also copy the plugin source files down to each existing /platform folder? Please don’t say the process should be to remove platform and re-add it (?!).

Leave a Reply