ngCordova

Si vous voulez développer rapidement une application Phonegap/Cordova sans vouloir utiliser toute la stack mean.io ou ionic, je vous conseille vivement ngCordova.

L’idée est d’encapsuler des plugins Phonegap/Cordova dans des services AngularJS. Mais dans quel but exactement… ?

Ne pas ré-inventer la roue

Bénéficiant d’une communauté active, ngCordova implémente la plupart des plugins nécessaires (photo, network, vidéo…). Trouver son bonheur parmi tous ces plugins n’est donc pas chose difficile. En quelques étapes d’installation, notre plugin est prêt à être utilisé et s’intègre parfaitement dans nos contrôleurs AngularJS. Pas besoin donc de créer soi-même l’encapsulation de ces services, si ce n’est pour savoir le faire.

Installation

L’installation de ngCordova se fait de la même façon que n’importe quel autre composant bower.

bower install ngCordova

Les sources sont téléchargées et copiées dans le sous-répertoire bower_components.

bower_components/ngCordova/
├── bower.json
├── CHANGELOG.md
├── dist
│   ├── ng-cordova.js
│   ├── ng-cordova.min.js
│   ├── ng-cordova-mocks.js
│   └── ng-cordova-mocks.min.js
├── LICENSE
├── package.json
└── README.md

Les sources de ngCordova sont maintenant prêtes à être injectées dans votre application AngularJS. Pour cela, il faut renseigner le fichier dans index.html et la dépendance dans votre fichier app.js.

index.html

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

app.js

angular.module('myApp', ['ngCordova'])

Et voila !

Utilisation

Tous les services ngCordova sont directement injectables dans vos composants AngularJS, par exemple pour utiliser le service des dialogues :

module.controller('MyCtrl', function($scope, $cordovaDialogs) {

  $cordovaDialogs.alert('message', 'title', 'button name')
    .then(function() {
      // Le bouton a été cliqué, écrire le code correspondant ...
    });

});

Et c’est la même chose pour tous les autres services : autre exemple pour utiliser le service de fichiers et des photos :

module.controller('MyCtrl', function($scope, $cordovaFile) {

    $cordovaFile.getFreeDiskSpace()
      .then(function (success) {
         // success in kilobytes
      }, function (error) {
          // error
      });

});

module.controller('MyCtrl', function($scope, $cordovaMedia) {

    var media = $cordovaMedia.newMedia("/src/audio.mp3").then(function() {
        // success
    }, function () {
        // error
    });

    media.play();

});

Il devient alors très facile d’imbriquer tous ces composants afin de construire une application HTML5 riche. Toutes les fonctionnalités de base sont couvertes et sont disponibles sur Github.

ngCordovaMocks

Tester son code sur du vrai matériel n’est pas toujours possible. Pour cela, il nous faut une solution pour tester ses composants sur notre navigateur préféré. C’est là qu’intervient ngCordovaMocks.

Comme son nom l’indique, cette librairie vas nous permettre de “mocker” les appels à certains services.

L’installation se fait de la même manière que pour ngCordova : via bower.

bower install ng-cordova-mocks

Ensuite, il faut rajouter le script dans sa page :

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

Et dans son fichier app.js :

angular.module('myApp', ['ngCordovaMocks'])

Ceci dit, on ne peut pas ajouter ngCordova et ngCordovaMocks sur la même page, et il devient très pénible de devoir changer ces deux lignes à chaque changement d’environnement. Pour cela on va utiliser gulp (site officiel) et son plugin gulp-preprocess (npm) pour éviter de le faire manuellement. Pour une installation et utilisation de gulp, voir cet article.

La page html devient alors :

<!-- @if NODE_ENV='DEVICE-DEVELOPMENT' -->
<script src="lib/ngCordova/dist/ng-cordova.js"></script>
<!-- @endif -->

<!-- @if NODE_ENV='DESKTOP-DEVELOPMENT' -->
<script src="lib/ngCordova/dist/ng-cordova-mocks.js"></script>
<!-- @endif -->

Le fichier app.js devient :

// @if NODE_ENV == 'DEVICE-DEVELOPMENT'
angular.module('myApp', ['ngCordova'])
// @endif

// @if NODE_ENV == 'DESKTOP-DEVELOPMENT'
angular.module('myApp', ['ngCordovaMocks'])
// @endif

Et le gulpfile associé :

gulp.task('device-development', function() {
    gulp.src('./www/gulp_preprocess_me/*.js')
    .pipe(preprocess({context: { NODE_ENV: 'DEVICE-DEVELOPMENT'}}))
    .pipe(gulp.dest('./www/js/'));

    gulp.src('./www/gulp_preprocess_me/index.html')
    .pipe(preprocess({context: { NODE_ENV: 'DEVICE-DEVELOPMENT'}}))
    .pipe(gulp.dest('./www/'));
});

gulp.task('desktop-development', function() {
    gulp.src('./www/gulp_preprocess_me/*.js')
    .pipe(preprocess({context: { NODE_ENV: 'DESKTOP-DEVELOPMENT'}}))
    .pipe(gulp.dest('./www/js/'));

    gulp.src('./www/gulp_preprocess_me/index.html')
    .pipe(preprocess({context: { NODE_ENV: 'DESKTOP-DEVELOPMENT'}}))
    .pipe(gulp.dest('./www/'));
});

En une ligne de commande vous pouvez maintenant choisir d’utiliser la libriaire ngCordova pour un développement sur mobile, ou bien ngCordovaMocks pour un développement sur desktop.

gulp device-development
gulp desktop-development

Attention quand même au déploiement : ne surtout pas envoyer la librairie des mocks en production 🙂

Conclusion

Pour rapidement utiliser ngCordova et ses plugins, une phase de configuration et d’outillage est nécessaire et peut s’avérer un peu longue. Néanmoins, une fois cette étape réalisée, l’installation de nouveaux plugins, leur utilisation, et leur déboggage sont très simplifiés. Toutes les documentations sont disponibles sur http://ngcordova.com/docs/plugins/ et sur les dépôts des plugins. Maintenant, à vos claviers…