Comment ajouter de l'aide sous la forme d'un guide pas à pas dans une appli AngularJS

Aujourd'hui je vais m'intéresser à l'aide visuelle sur un site web ou une application web en entreprise. Certains diront que la meilleure documentation reste une application simple et intuitive mais les utilisateurs n'ont pas tous la même approche des outils informatiques et nous devons penser à comment les aider pour prendre en main une application.

La méthode la plus simple est de leur fournir une aide textuelle. Mais ces aides sont rarement lues car pas très funs et souvent difficiles à suivre. Je me suis intéressé dernièrement à cette problématique et il existe des solutions simples pour répondre à ce besoin. Je me suis surtout intéressé à Boostraptour qui s'intègre bien dans les applications à base de Bootstrap et à la solution intro.js. Au final mon choix s'est porté sur la deuxième solution qui possède une bonne intégration avec les applications Angular JS (angular-intro.js)

Nous allons voir comment l'intégrer dans un projet.

Les sources des exemples de l'article sont disponibles sous Github. Le projet exemple a été généré par la solution Yeoman et le générateur d'application AngularJS. L'application est assez simple et ressemble à ceci

Installation

Pour installer angular-intro.js, vous devez ajouter les librairies nécessaires via la commande

bower install angular-intro.js

ou en modifiant votre fichier bower.json

{
  "name": "introjs",
  "version": "0.0.0",
  "dependencies": {
    "angular": "^1.3.0",
    "bootstrap": "^3.2.0",
    "angular-cookies": "^1.3.0",
    "angular-intro.js": "1.2.2"
  },
  "devDependencies": {
    "angular-mocks": "^1.3.0"
  },
  "appPath": "app",
  "moduleName": "introjsApp"
}

Un premier exemple

Nous sommes prêt pour démarrer. Le but de Intro.js est de repérer des éléments dans le DOM, de mettre en avant le nœud HTML sélectionné, et d'afficher un message dans une fenêtre qui sera placée à l'endroit où vous le précisez (en haut, en bas, à droite, à gauche).

Nous allons commencer par modifier notre page HTML principale et charger les scripts suivants

<script src="bower_components/intro.js/intro.js"></script>
<script src="bower_components/angular-intro.js/src/angular-intro.js"></script>
<link rel="stylesheet" href="bower_components/intro.js/introjs.css" />

Dans le fichier de configuration de l'application nous allons définir une dépendance vers le module angular-intro.js

angular.module('introjsApp', ['angular-intro']);

L'étape d'après consiste à ajouter les directives ng-intro à votre template de page. Par exemple

<div ng-include="'views/main.html'" ng-controller="MainCtrl" ng-intro-options="introJsOptions" ng-intro-method="initIntro"></div>

La directive ng-intro-options pointe vers une variable du scope contenant les options choisies et les différents messages. Cette notion de scope est importante. Ici j'ai défini ng-intro-options au niveau d'un bloc ou le scope est celui du controller MainCtrl. C'est donc dans ce dernier que je vais définir mes options Intro.js

angular.module('introjsApp')
  .controller('MainCtrl', function ($scope) {
    $scope.introJsOptions = {
      steps: [
        {
          element: '#step1',
          intro: '<strong>Etape1</strong> Welcome in our website',
          position : 'bottom'
        },
        {
          element: '.step2',
          intro: 'We used Yeoman to generate this example',
          position : 'right'
        }
      ]
    };
  });

Les éléments sont identifiés par leur sélecteur Jquery. Par exemple

• element: '#step1' fait référence à la balise portant la propriété id="step1"
• element: '.step2' fait référence à la balise portant la propriété class="step2"

La directive ng-intro-method permet de définir le nom d'une méthode que vous pouvez utiliser pour lancer la présentation. Par exemple

<a class="btn btn-lg btn-success" ng-click="initIntro()"><span class="glyphicon glyphicon-question-sign"></span></a>

Quand vous lancez la page un clic sur le bouton lancera la présentation

Aller un peu plus loin

Pour le moment l'exemple est assez simple. On pourrait aller plus loin et faire en sorte que l'aide se lance automatiquement la première fois où l'utilisateur vient sur le site et qu'elle ne se lance pas les fois suivantes quand il a choisi de quitter la présentation.

Nous allons utiliser les cookies pour enregistrer le choix de l'utilisateur. Au niveau de votre module ajouter la déclaration du nouveau angular

angular.module('introjsApp', ['angular-intro', 'ngCookies']);

Nous allons rajouter deux méthodes au niveau de la configuration générale de l'application qui vont se charger de regarder si une variable est définie ou non dans les cookies

angular.module('introjsApp').run(function ($rootScope, $cookieStore) {
 $rootScope.exitIntro = function(){
    $cookieStore.put('intro-autostart', false);
  };

  $rootScope.autostartIntro = function(){
    return $cookieStore.get('intro-autostart') !== false;
  };
});

Et ajouter de nouvelles directives angular-intro.js à celles déjà définies pour lier ces fonctions que l'on vient de définir à Intro.js

<div ng-include="'views/main.html'" ng-controller="MainCtrl" ng-intro-options="introJsOptions" ng-intro-method="initIntro" ng-intro-autostart="autostartIntro()" ng-intro-onexit="exitIntro"></div>

Et le tour est joué...

Conclusion

Comme vous avez pu le constater, l'ajout de cette aide utilisateur n'est pas très compliquée. Si vous voulez plus d'informations sur ces solutions je vous laisse regarder les sites Intro.js et angular-intro.js. Les sources des exemples donnés ici sont disponibles sous Github