Installing ngCordova in an Ionic 1.x Application

In just about any Ionic tutorial I write that uses Cordova plugins, I use ngCordova. So, instead of writing a mini tutorial on how to get it up and running and what exactly it does in all of those tutorials, I thought it would make sense to do a single post explainining it in a little more depth.

What is ngCordova?

ngCordova is a collection of AngularJS services and extensions created by Ionic and driven by the community. These services make it easier to integrate Cordova plugins into Ionic applications. Rather than calling a plugin manually as it is defined in the documentation for that specific plugin, you can instead use the AngularJS service to do the work for you.

For example, if you were using the Cordova Camera Plugin manually you might do something like this:

navigator.camera.getPicture(cameraSuccess, cameraError, [cameraOptions]);

where cameraSuccess and cameraError are callback functions. When using the ngCordova version you would do something like this:

$cordovaCamera.getPicture(options).then(
  function (imageData) {
    //Do something
  },
  function (error) {
    //Do something
  }
);

One of the biggest differences and benefits of ngCordova is that it uses promises. You can read this article about promises to gain a better understanding of what exactly a “promise” is, but this quote from the article sums it up well:

In the example above, the imageData won’t be available until the user has finished taking the photo. By using a promise in the form of .then() we can tell our application to do something with the data when it becomes available, and also handle errors if necessary. Now, this isn’t entirely different to just creating callback functions in the form of:

navigator.camera.getPicture( cameraSuccess, cameraError, [ cameraOptions ] );

but the beauty of promises comes when we want to chain multiple promises together. We could do something like this for example:

$someService
  .getSomething()
  .then(function (result) {
    //Do (something)
  })
  .then(function (result) {
    //Do something else
  })
  .then(function (result) {
    //Do something else
  });

Each of these blocks of code will only execute when the previous has finished fetching whatever it needed, and the first promises “promise” won’t be fulfilled until all of the promises have finished executing. Writing this with callbacks would be extremely messy, and is often referred to as “callback hell”.

Another benefit of ngCordova is that it acts as a curated list of awesome and stable plugins. There’s a lot of great plugins supplied by the community, but some are definitely better and more stable than others. If you’re using a plugin from ngCordova then there is a good chance that it is going to be pretty well maintained.

Installing ngCordova

Setting up ngCordova in an Ionic application is super easy, just follow these steps:

Run the following command to include the ngCordova library

bower install ngCordova

Add the ngCordova library to your index.html file

<script src="lib/ngCordova/dist/ng-cordova.js"></script>
<script src="cordova.js"></script>

Require ngCordova in the angular module in app.js

angular.module('starter', ['ionic', 'ngCordova']);

ngCordova should now be installed and ready to use in our application.

Installing an ngCordova Plugin

Even with ngCordova installed, you still need to install the plugin as you usually would in your application by running:

cordova plugin add [plugin name]

when you do this, make sure you find the plugin you wish to use on the ngCordova website. ngCordova can only be used with plugins that it officially supports, so your selection will be limited to those you can find in the link above.

There’s currently over 60 plugins supported, and these are generally the more popular plugins. So chances are you’ll find most plugins you need here but in the case of more obscure plugins you’ll need to go back to using them the normal way.

Using an ngCordova Plugin

When using an ngCordova plugin you must first inject it into wherever you want to use it. If I wanted to use the camera plugin in one of my controllers I would do this:

.controller('MainCtrl', function($scope, $state, $cordovaCamera) {
    $cordovaCamera.getPicture(options).then(function(imageData) {
        //Do something
    }, function(error) {
        //Do something
    });
});

You will have to look up the documentation for the plugin you are using on the ngCordova website for specific instructions on how to use it, but in general all the plugins follow the promise structure we talked about before.