FrAngular : AngularJS en français

Drupal + AngularJS : l'ultime solution de theming pour Drupal ?

2014-02-21T22:45:00.000+01:00

Customiser le code HTML créé par Drupal et ses modules est sans doute l'un des points les plus difficiles à comprendre. Les solutions proposées pour tenter de faciliter cette tâche sont nombreuses : Starter thèmes, modules type Panels ou Display Suite, modules d'intégration de bibliothèques JavaScript, la liste est infinie. On passe beaucoup de temps dans la création d'un site sous Drupal à tenter de livrer un code HTML qui conviendra à l'intégrateur, qui de toute façon s'arrachera les cheveux à un moment ou un autre.

AngularJS est un framework Javascript qui adapte et étend le HTML grâce à des directives qu'on y inclut. Mes premiers pas avec AngularJS m'ont donné à penser qu'il pourrait bien être complémentaire de Drupal. Parlons de ces premiers pas justement, la communauté AngularJS propose un tutoriel pour débuter qui permet de créer une application Phonecat qui affiche des informations techniques à propos de téléphones portables.

Je vous propose donc de modifier cette application pour qu'elle récupère ses informations depuis Drupal via des web services. Drupal servirait alors uniquement de backoffice à l'application AngularJS, chose que ce CMS fait très bien.

Fonctionnement

L'idée est donc la suivante :

A partir de Drupal je vais créer un nouveau type de contenu classiquement qui générera des nodes. La liste de ces nodes sera créée via le module Views. Ensuite, la vue et les nodes seront exposés via des webservices REST grâce au module Services.

Côté client, j'utiliserai $resource d'AngularJS pour les accès à ces services REST, et les données pourront être exploitées par les contrôleurs et présentées par les templates de l'application.

Installation de Drupal et de Phonecat AngularJS

J'ai décidé de positionner l'application AngularJS à la racine de mon répertoire et d'avoir un sous-dossier Drupal dans ce répertoire. Voici l'arborescence que j'ai obtenue après installation :

Créer un virtualhost ng-drupal

J'ai commencé par créer un nouveau virtual host dans Apache qui mène à mon répertoire Drupal/Angular. Voici mon ng-drupal.conf :

<VirtualHost *:80> 
  DocumentRoot /home/desktop/s/ng-drupal 
  ServerName ng-drupal.tld 
  <Directory /home/desktop/s/ng-drupal> 
    AllowOverride all 
  </Directory> 
</VirtualHost>

Cloner le tutorial Phonecat / Angular

Je suis parti du tutorial officiel proposé sur le site officiel AngularJS. Si vous ne connaissez pas ce framework, je vous encourage à le lire dans son ensemble.

Placez-vous à la racine du répertoire précédemment créé et exécutez les deux commandes suivantes. La première permet de copier le code source du tutoriel et la seconde de se placer à la dernière étape.

git clone https://github.com/angular/angular-phonecat.git .
git checkout -f step-12

A l'adresse suivante, j'ai maintenant le tutoriel qui s'affiche :
http://ng-drupal.tld/app/

Installation de Drupal

J'ai ensuite installé Drupal 7 dans le sous-répertoire /drupal du dossier principal. Si vous ne connaissez pas ce CMS, vous pouvez utiliser mon livre librement téléchargeable chez Framabook.

Pour accéder à l'installateur, j'ai lancé cette url : http://ng-drupal.tld/drupal

Après quelques minutes, Drupal était installé :)

Installation de la Feature angular-phonecat

Pour vous éviter de longues configurations et saisies, j'ai créé une « Feature » (module) qui contient les éléments Drupal qui permettent de créer les webservices pour l'application Phonecat. Elle contient :

un type de contenu phone avec tous les champs des téléphones du tutorial
du contenu qui utilise le type de contenu Phone
une vue qui liste tous les téléphones du site
un service qui permettent d'exporter sous forme de JSON la vue ou un élément du contenu

J'ai donc installé cette Feature dans le répertoire drupal/sites/default/modules (à créer si il n'existe pas).
Vous pouvez télécharger cette feature ici.

Installation des dépendances

Ce module a des dépendances manquantes, je les ai installées

Ctools : boîte à outils utilisée par un grand nombre de modules Drupal
Features : permet de créer des fonctionnalités sous forme de module
Field_group : utilisé pour regrouper les nombreux champs du contenu phone
Node_export_features : permet d'inclure du contenu dans une feature
Universally Unique ID : module permettant d'attribuer un id unique à chaque contenu
Services : permet à Drupal de créer des webservices
Views : permet d'extraire différents types de données de Drupal et de les présenter
Libraries : permet aux modules Drupal d'utiliser des bibliothèques externes
REST Server : permet de créer un serveur REST
Services views : permet à Services d'exposer le résultat des vues

Pour plus de rapidité, j'ai utilisé la commande Drush suivante :

drush dl ctools features views services field_group node_export uuid libraries services_views

J'ai ensuite pu activer les modules et ma feature. J'ai dû m'y reprendre à deux fois car mes contenus ont été importés avant mon type de contenu.

L'installation coté Drupal est terminée !

Les contenus dans Drupal

Vous avez maintenant la possibilité d'ajouter de nouveaux téléphones graphiquement avec Drupal :
Menu Content – Lien Add content – Phone

Voici l'interface que j'ai utilisée pour ajouter les quatre téléphones de la Feature que j'ai créée.

Pour ceux qui connaissent mal Drupal, sachez que vous pouvez créer ce type de formulaire graphiquement dans Drupal en choisissant les champs qui les composent.

Vous pouvez modifier le type de contenu Phone (Menu Structure – Content types, puis lien manage fields de Phone) :

La page de liste

J'ai commencé par créer la page de liste des téléphones.

La vue dans Drupal

Cette liste utilise 4 champs pour chaque téléphone :

Le titre
La description
Le nid (pour créer un lien vers le détail d'un téléphone)
L'image

J'ai donc créé une vue Phone-list dans Drupal (menu Structure – Views, puis lien Edit de la vue Phone-list)

Notez que j'ai utilisé le redimensionnement en 100x100 pour l'image, mais j'aurais pu en créer une autre facilement.

Le webservice dans Drupal

Ensuite, pour exporter cette vue en JSON, j'ai utilisé le module services (menu Structure – Services, puis lien Edit Resources du service phones).

J'ai indiqué que le chemin à utiliser pour accéder au service sera phones (onglet Edit) et que ca sera un serveur REST. J'ai autorisé le webservice à accéder à la lecture des nodes pour le détail des téléphones et aux vues pour accéder à celle que je viens de créer : Phone-list (onglet Ressources).

Voici le chemin complet à utiliser pour accéder à une vue via un webservice :
http://example.com/<endpoint path>/views/<view name>

Ce qui m'a donné :
http://ng-drupal.tld/drupal/phones/views/phone_list.json

Récupération dans Angularjs de phone_list.json

Au terme de ce tutoriel, j'aurai donc deux services : un basé sur Views qui me permettra de récupérer la liste des téléphones, un autre sur Nodes qui me permettra de récupérer un seul téléphone.

J'ai donc commencé par créer le premier service, dans le fichier services.js de l'application Phonecat :

phonecatServices.factory('Phones', ['$resource',
  function($resource){
    return $resource('http://ng-drupal.tld/drupal/phones/views/phone_list.json', {}, {
      query: {method:'GET', isArray:true}
    });
  }]);

J'ai utilisé ce service avec le controller PhoneListCtrl dans le fichier controllers.js :

phonecatControllers.controller('PhoneListCtrl', ['$scope', 'Phones',
  function($scope, Phones) {
    $scope.phones = Phones.query();
    $scope.orderProp = 'age';
  }]);

Grâce à Batarang, je vois que le JSON est bien chargé.

Affichage dans le template

Il ne reste donc qu'à charger les bons éléments dans le template partials/phone-list.html

Titre et description :

Les champs s'appellent maintenant node_title, nid et description :

<a href="#/phones/{{phone.nid}}">{{phone.node_title}}</a>
<p>{{phone.description}}</p>

Image :

Pour le champ image, j'injecte directement le html provenant du JSON grâce à la directive ng-bind-html. Pour qu'elle fonctionne, il me faut ajouter la dépendance ngSanitize à mon module phonecatService dans services.js :

var phonecatServices = angular.module('phonecatServices', ['ngResource', 'ngSanitize']);

Je dois également ajouter le script angular-sanitize.js dans index.html :

<script src="lib/angular/angular-sanitize.js"></script>

puis, je complète mon fichier phone-list.html pour l'affichage des images

<a href="#/phones/{{phone.nid}}" class="thumb" ng-bind-html="phone.images"></a>

Filtres

Tout est bien chargé, il ne me reste plus qu'à faire fonctionner les filtres en changeant les noms des champs.

Dans partials/pḧone-list.html :

<option value="node_title">Alphabetical</option> 
<option value="nid">Newest</option>

Dans controller.js , indiquer la valeur par défaut (nid) :

$scope.orderProp = 'node_title';

La liste des téléphones fonctionne maintenant ! Finalement, je n'ai eu à changer que les noms de champs !

Page détail

Création du service dans Drupal

Rien à faire ou presque pour cette page détail coté Drupal puisque le module Service fournit par défaut un moyen de récupérer le JSON d'un node. Il m'a suffit pour cela de cocher le service node/retrieve pour que mon webservice fonctionne avec l'adresse :
http://ng-drupal.tld/drupal/phones/node/1.json

Modification du service dans AngularJS

Coté AngularJS, il faut modifier l'url de la ressource Phone :

phonecatServices.factory('Phone', ['$resource',
  function($resource){
    return $resource('http://ng-drupal.tld/drupal/phones/node/:phoneId.json', {}, {
      query: {method:'GET', params:{phoneId:'phones'}, isArray:true}
    });
  }]);

L'argument n'est donc plus le nom du téléphone, mais le nid drupal du node.

Toutes les données sont chargées, il faut maintenant les afficher !

Modification du phone-detail.html avec le json de Drupal

J'ai eu un travail assez long pour récupérer les valeurs intéressantes dans le JSON généré par Drupal avec l'application Angular. Il a fallu gérer quatre types de données :

Type texte simple :

Par exemple, le champ RAM est affiché comme cela à l'origine :

{{phone.storage.ram}}

Il devient alors :

{{phone.field_ram.und[0].value}}

« und » est bien connu des drupaliens et veut dire undefined, c'est à dire que la langue n'est pas définie pour ce champ. 0 est l'indice du champ en cas de valeur multiple

Type texte multiple :

Il est possible d'avoir un champ qui contient un nombre non défini de valeurs sous Drupal. C'est par exemple le cas du champ dimensions.

J'ai donc dû boucler sur le tableau phone.field_dimensions.und pour récupérer et afficher chaque valeur :

<dd ng-repeat="dim in phone.field_dimensions.und">{{dim.value}}</dd>

Type booléen :

A l'étape n°9 du tutoriel Angular, un filtre checkmark est ajouté. Il évalue si la valeur est à true ou false alors que Drupal retourne 0 ou 1. J'ai donc dû changer la règle du filtre :

return input == 1 ? '\u2713' : '\u2718';

Et afficher le résultat ainsi :

{{phone.field_infrared.und[0].value | checkmark}}

Les images :

J'ai rencontré un petit souci pour afficher les images car les données du json ne fournissaient qu'un lien vers une url Drupal (public://).

Conclusion

Après la rédaction de ce tutoriel, je n'ai pas de réponse pour savoir si la cohabitation entre Drupal et AngularJS est possible. J'ai trouvé des solutions à tous les problèmes qui se sont posés à moi et j'ai pu entrevoir le potentiel d'AngularJS . Cela m'a donné l'envie d'aller plus loin :

Comment fonctionnerait une authentification ?
Peut-être aurait-il été encore plus facile et versatile de créer un petit module Drupal utilisant la fonction drupal_json_encode (lien?)
L'initiative développée pour Drupal 8 (https://groups.drupal.org/wscci) facilitera-t-elle ce type de développement ?

N'hésitez pas à partager vos réflexions sur le sujet. Si vous avez un projet à développer et que vous aimeriez utiliser Drupal et AngularJS, n'hésitez pas à me contacter !

Téléchargez le dossier app de l'application modifiée.

Scope isolé dans les directives AngularJS

2013-10-31T01:25:00.000+01:00

Second sujet que j'ai traité au Meetup chez Google, il s'agit des scopes isolés dans les directives. Les slides se trouvent ici, et une vidéo a été mise en ligne là ; mon intervention commence par un sujet sur l'usage des services, et celui-ci est à la suite.

Le scope isolé est un outil bien pratique mis à notre disposition par AngularJS pour faciliter la création de widgets. Mais il ne faut pas l'utiliser n'importe quand, ni en faire n'importe quoi.

L'arbre des scopes

Les scopes d'AngularJS sont des objets qui servent de contexte d'évaluation des expressions contenues dans les templates.

Ils forment un arbre, dont la racine est le seul scope de l'application qui est aussi publié comme un service, sous le nom $rootScope. Ce $rootScope est associé à l'élément contenant toute l'application AngularJS, celui sur lequel on met la directive ngApp : ça peut être l'élément <html> lui-même, ou le <body>, ou un <div> à l'intérieur, peu importe.

La structure arborescente des scopes est calquée sur celle des éléments de la page HTML. Chaque scope est lié à un élément du DOM, mais la réciproque n'est pas vraie. Il n'y a pas un scope pour chaque élément, seulement pour certains des éléments de la page HTML, parce qu'on a placé sur ces éléments une directive AngularJS qui crée un nouveau scope. C'est le cas des directives ngController, ngView, ngRepeat, etc.

Quand une directive crée un scope sur un élément HTML, ce scope aura pour parent le premier scope rencontré en remontant les éléments HTML.

Scope d'un élément

Quand on crée une directive, qui sera déclenchée sur un élément HTML soit en lui ajoutant un attribut soit par le nom de l'élément lui-même, on fournit un objet de définition de la directive. Il y a trois options possibles quant à la propriété scope de cet objet :

false pour ne rien faire (c'est la valeur par défaut si la propriété scope est absente)
true pour créer un scope enfant
{...} (un objet JavaScript avec des propriétés) pour créer un scope isolé

Le scope isolé tout comme le scope enfant a un scope parent, référencé par sa propriété $parent. La différence c'est l'héritage : seul le scope enfant hérite des données de son scope parent, le scope isolé n'en hérite pas, c'est pour ça qu'il est dit "isolé". Il ne s'agit pas de gros sous, mais de l'héritage par prototype de JavaScript. Quand l'interpréteur JS ne trouve pas une propriété dans un objet, il va la chercher dans son prototype. Puis éventuellement dans le prototype du prototype, tant qu'il n'est pas arrivé au bout de la chaîne des prototypes, ou qu'il n'a pas trouvé la propriété.

Le scope parent est positionné par AngularJS comme prototype de ses scopes enfants, mais pas des scopes isolés. Du coup un scope enfant hérite automatiquement des données de son scope parent, y compris celles que le parent a hérité de ses propres parents. Il est donc inutile d'aller chercher des données explicitement dans le scope parent en utilisant la propriété $parent, puisqu'elles sont héritées. Au contraire, le scope isolé n'héritera d'aucune donnée, et on peut dans certains cas (assez rares) avoir besoin de récupérer son scope parent via sa propriété $parent.

Ce qu'il est très important de comprendre, c'est que même si c'est au niveau d'une directive qu'on indique si elle doit créer un scope enfant ou un scope isolé, ce scope est créé pour l'élément HTML. Ce sera dont le scope récupéré par toutes les directives placées sur cet élément, et aussi celles placées sur ses éléments enfants s'ils n'ont pas eux-mêmes leur propre scope. Les trois premiers paramètres de la fonction link de la directive, en l'occurrence le scope, l'élément et l'objet contenant les attributs, ne dépendent pas de la directive, et seront les mêmes pour toutes les directives du même élément. Ils ne dépendent que de l'élément lui-même, ce qui fait que toutes les directives d'un même élément reçoivent le même scope, celui de l'élément, et tous les attributs de l'élément HTML.

Evidemment, ça ne peut fonctionner que si les directives d'un élément HTML ne formulent pas de demandes contradictoires. Si une directive demande la création d'un scope enfant, alors que les autres ne demandent rien (leur propriété scope est à false), alors AngularJS crée un scope enfant pour cet élément, qui sera passé à toutes les directives, même celles qui n'ont rien demandé. Mais il est impossible d'avoir sur un même élément une directive demandant un scope enfant et une autre demandant un scope isolé, ou deux directives demandant un scope isolé, chacune avec sa propre définition. Dans ces cas d'incompatibilité, le framework signale une erreur.

Quand et pourquoi un scope isolé ?

La plupart des directives n'ont pas à créer de nouveau scope, que ce soit un scope enfant ou isolé. Quand une directive demande la création d'un nouveau scope, ce n'est pas anodin car ça la rend incompatible avec d'autres directives.

Si elle demande un scope isolé, c'est encore plus contraignant, car ça veut dire qu'aucune des données du scope parent ne sera disponible dans le scope de l'élément sur lequel elle est appliquée. Ça signifie qu'il ne sera pas possible d'utiliser sur ce même élément ou sur n'importe quel élément enfant une autre directive qui prend dans un attribut (généralement du nom de la directive) une expression à évaluer sur le scope. Vu que les données ne seront pas présentes dans le scope, l'évaluation de l'expression ne peut que mal se passer.

Il faut limiter l'usage des scopes isolés à des éléments sans contenu et sur lesquels on ne met pas d'autres directives, du moins pas de directive comme ngShow par exemple, dont l'expression serait alors évaluée sur un scope isolé ne contenant pas les données. Bon le ngShow, on peut toujours le mettre sur un <div> englobant l'élément, mais pour les directives se trouvant dans le contenu de l'élément c'est mort.

L'usage typique d'un scope isolé, c'est dans une directive qui crée un composant complet, un widget comme un agenda, une carte, un graphique.

Alors s'il y a de telles limitations à l'usage d'un scope isolé, pourquoi s'en servir ? Parce que dans les cas où l'on peut le faire, ça simplifie le code de la directive, et ça évite le risque d'impacter involontairement les données du scope parent.

On peut publier tout ce qu'on veut dans le scope isolé, et on peut évaluer toutes les expressions qu'on veut sur le scope isolé, tant qu'on n'accède pas explicitement à sa propriété $parent, on est sûr qu'il n'y aura aucune modification - ni même lecture d'ailleurs - des données du scope parent. Le scope isolé créé par une directive, c'est un peu comme le scope local d'une fonction. A l'exécution d'une fonction, en JavaScript ou dans n'importe quel autre langage, les variables locales définies dans la fonction n'existent qu'à l'intérieur de cette fonction, et il ne peut pas y avoir de collision avec des variables externes à la fonction.

L'analogie va plus loin : les propriétés définies dans le scope isolé vont s'apparenter aux paramètres de la fonction. En définissant une propriété dans le scope isolé, on lui donne un nom local à la directive, enfin plus précisément dans le scope de l'élément donc pour toutes les directives de cet élément s'il y en a plusieurs. Dans la directive, on travaille alors uniquement avec les propriétés définies dans le scope isolé, sans aller chercher manuellement les valeurs des attributs de l'élément.

Bindings des propriétés du scope isolé

Chaque propriété définie dans le scope isolé va être liée par un binding d'un certain type à un attribut de l'élément HTML.

On va avoir trois utilisations différentes pour les attributs de l'élément :

des attributs de type texte, qui peuvent éventuellement contenir une ou plusieurs expressions entre doubles accolades {{...}} (comme la directive ngSrc)
des attributs de type expression qui servent à faire un binding sur la valeur de l'expression (comme la directive ngBind)
des attributs de type expression qui servent à déclencher une action (comme la directive ngClick)

Ces trois cas d'utilisation correspondent aux trois symboles utilisables dans la définition des propriétés du scope isolé :

'@' pour un attribut texte
'=' pour une expression valeur
'&' pour une expression action

@ : attribut texte

On indique le nom de la propriété, et dans une chaîne de caractères le nom de l'attribut de l'élément HTML précédé par le signe @ :

    scope: { prop1: '@attr1' },

On peut aussi omettre le nom de l'attribut s'il est identique au nom de la propriété, dans ce cas on met seulement le signe '@'.

Prenons un exemple concret :

    <person name="{{user.firstName}} {{user.lastName}}"/>

    scope: {
        name: '@'
    }

Ici le scope isolé est défini avec une propriété name, qui référence l'attribut texte du même nom. AngularJS crée un binding monodirectionnel de l'attribut vers la propriété du scope isolé.

Ça veut dire que la propriété name du scope isolé recevra automatiquement la valeur texte de l'attribut référencé, dans laquelle les éventuelles expressions entre {{...}} auront été évaluées. Ici le prénom de l'utilisateur, un espace, puis son nom. Et ce binding est permanent, chaque fois que user.firstName ou user.lastName changera de valeur, celle de la propriété name du scope isolé sera recalculée. La réciproque n'est pas vraie, le binding est monodirectionnel : si on modifiait à l'intérieur de la directive la valeur de la propriété name du scope isolé, ça n'aurait aucune conséquence sur user.firstName ou user.lastName.

Et bien sûr, l'évaluation des expressions de l'attribut se fait sur le scope parent, pas sur le scope isolé qui n'a hérité d'aucune donnée, et dans lequel ni user.firstName ni user.lastName ne sont définis.

= : expression valeur

La syntaxe est la même, pour une propriété qui référence un attribut contenant une expression à utiliser comme une valeur, on fait précéder le nom de l'attribut par le signe =, et on peut encore omettre le nom de l'attribut et mettre un signe '=' seul s'il correspond au nom de la propriété.

    scope: { prop2: '=attr2' },

Un exemple :

    <person name="user.lastName"/>

    scope: {
        name: '='
    }

Ici on a défini dans le scope isolé une propriété name, qui référence l'attribut name contenant une expression, pour qu'AngularJS crée un binding bidirectionnel entre la propriété du scope isolé et la valeur de cette expression (toujours évaluée sur le scope parent).

Ça signifie ici que la propriété name contiendra toujours la valeur de l'expression indiquée dans l'attribut name. Si la valeur de user.lastName est modifiée dans le scope parent, la propriété name du scope isolée sera recalculée. Et réciproquement, si dans le code de la directive on change la valeur de la propriété name, alors AngularJS mettra à jour user.lastName dans le scope parent. C'est plus simple que de devoir le gérer à la main.

& : expression action

De la même façon, pour définir une propriété référençant un attribut contenant une expression à utiliser comme une action, on fait précéder le nom de l'attribut par le signe &, et on peut là aussi omettre le nom de l'attribut et mettre seulement le signe '&' s'il correspond au nom de la propriété.

    scope: { prop3: '&attr3' },

Un exemple :

    <delete-button action="remove(user)"/>

    scope: {
        action: '&'
    }

Ici AngularJS fournit comme valeur de la propriété action du scope isolé une fonction a exécuter pour déclencher l'action, c'est-à-dire l'évaluation de l'expression contenue dans l'attribut action. Il n'y a pas de binding dans ce cas, c'est juste une fonction à exécuter pour déclencher l'action.

On peut même passer à cette fonction un objet contexte dont les données vont surcharger celles du scope parent. Supposons qu'on exécute ceci dans la directive :

    scope.action({user: previousUser});

Le user sera alors celui de l'objet passé en paramètre, il ne sera pas pris dans le scope parent. Par contre la fonction remove() viendra elle du scope parent, car elle n'est pas fournie dans l'objet contexte passé en paramètre de l'action.

Et sans scope isolé ?

Ces trois différents usages possibles des attributs au moyen de propriétés définies dans le scope isolé sont certes très pratiques, et permettent de simplifier le code de la directive. Mais on a vu avant qu'on ne peut pas utiliser un scope isolé dans tous les cas, loin s'en faut.

Alors comment faire dans la fonction link de la directive quand on doit se passer du côté pratique du scope isolé ? Et bien ce n'est pas beaucoup plus compliqué.

    link: function (scope, element, attrs, ctrl) {
        // ...
    }

Pour un attribut texte, on utilise la méthode $observe() de l'objet attrs contenant les attributs de l'élément, avec le nom de l'attribut à observer :

    attrs.$observe('xxx', function(value) {    // xxx est le nom de l'attribut
        // ...
    });

Pour une expression valeur, on utilise la méthode $watch() du scope, avec comme expression à surveiller la valeur de l'attribut fournie par la propriété correspondante (en camel case) de l'objet attrs :

    scope.$watch(attrs.xxx, function(newVal, oldVal) {
        // ...
    });

Et en sens inverse, pour mettre à jour la valeur de l'expression contenue dans l'attribut, s'il s'agit d'une expression assignable bien sûr, on utilise le service $parse, et la méthode assign() de l'objet qu'il renvoie :

    $parse(attrs.xxx).assign(scope, value);

Pour une expression action, on utilise encore le service $parse, et on appelle la fonction renvoyée par $parse, en lui fournissant le scope en premier paramètre, et éventuellement en second paramètre un objet contexte qui surcharge certaines données du scope.

    $parse(attrs.xxx)(scope, locals);

Même si c'est un peu plus complexe que de manipuler directement les propriétés du scope isolé, ça reste très raisonnable comme quantité de code à écrire.

Exemple de directive avec un scope isolé

Vous pouvez retrouver l'exemple de la directive Google Maps que j'ai montré lors de cette présentation ici sur Plunker.

Dans le code de la directive, on manipule uniquement les propriétés du scope isolé, que ce soit pour placer des watches afin d'impacter la carte affichée quand les données changent dans le scope (parent), ou pour mettre à jour les données du scope d'après les événements de la carte Google Maps.

Voilà, avec tout ça vous avez de quoi jouer, avec ou sans scope isolé.

Services ou événements dans l'optique des tests

2013-10-26T16:49:00.001+02:00

Quelques réflexions complémentaires à mon article sur l'usage des services, qui partent d'une question que l'on m'a posé à la fin de ma présentation au Meetup AngularJS Paris chez Google. Quelqu'un m'a demandé si les événements pouvaient être utilisés pour simplifier les tests unitaires d'un contrôleur. En limitant les injections de services en dépendances, on évite la nécessité de versions factices (mock objects) de ces services.

Cette question me turlupinait dans le trajet retour, et j'ai essayé de pousser plus loin la réflexion en explorant cette piste et diverses alternatives.

Trop de services dans un contrôleur

En faisant un service pour chaque fonctionnalité, voire parfois plusieurs services pour une même fonctionnalité, ne risque-t-on pas de devoir injecter beaucoup trop de services à un même contrôleur ? Partons du principe qu'on a correctement isolé tout le modèle de données et les traitements métier dans des services, et que le contrôleur se contente de publier dans le scope ce qui est utilisé dans les expressions des templates. Il ne doit y avoir aucun traitement complexe dans les contrôleurs, qui devraient donc être faciles à tester.

Si l'on a un contrôleur auquel on injecte de nombreux services, c'est clairement le signe d'un problème, et pas seulement pour tester ce contrôleur. On est typiquement dans le cas de l'anti-pattern “God object”, l'objet qui en fait beaucoup trop. Evidemment il va être complexe à tester, mais il est surtout trop complexe tout court. Le fait qu'il soit difficile à tester n'est qu'un révélateur, pas le cœur du problème.

Que faire avec un tel contrôleur ? On peut déjà sans doute le découper en plusieurs contrôleurs. S'il s'agit d'un contrôleur associé à une des vues de l'application (le template associé à une route), une vue certainement assez complexe, il est quand même probable que certains des services injectés ne sont utilisés que dans une portion de la vue. On peut alors associé un contrôleur séparé à cette portion de la vue, avec une directive ngController sur l'élément HTML, ce qui crée un scope enfant. Ce nouveau contrôleur n'aura besoin que d'un seul service, ou d'un tout petit nombre de services, pour l'initialisation de ce scope enfant, qui hérite aussi de tout ce qui est publié dans son scope parent.

Il ne faut pas hésiter à créer plusieurs contrôleurs à l'intérieur d'une vue, le code sera bien plus lisible avec plusieurs petits contrôleurs qu'avec un seul contrôleur obèse, et chacun sera plus facile à tester, parce qu'on aura réduit le nombre de dépendances.

On peut aussi sans doute limiter le nombre de services à injecter en faisant des services de plus haut niveau. Les fonctionnalités un peu complexe de l'application méritent d'être découpées en plusieurs services, mais il s'agit de découper l'implémentation, pas l'interface. Si ça revient à devoir injecter plein de petits services, ça ne va pas. Il faut faire un service de haut niveau en frontal, à injecter dans les contrôleurs et autre services qui l'utilisent, et dont l'implémentation est découpée en plusieurs services plus élémentaires. Mais les services élémentaires ne doivent pas être manipulés ni même connus de l'extérieur, ils doivent être encapsulés dans le service de plus haut niveau. Donc le fait d'avoir des services du niveau d'abstraction que manipule le contrôleur doit permettre d'éviter cette multiplicité des injections.

C'est par ces deux méthodes, en séparant des parties du code dans des petits contrôleurs liés à des portions de la vue et en créant des services de plus haut niveau, qu'on va pouvoir régler le problème à la source, plutôt que d'essayer de trouver comment tester plus facilement un contrôleur mal écrit.

Communication entre services ou par événements ?

Vaut-il mieux faire communiquer plutôt les services entre eux, ou passer par les événements d'AngularJS pour découpler d'avantage.

Le fait de découpler est généralement plutôt une bonne chose, mais même des bonnes choses il ne faut pas abuser. Les événements d'AngularJS ont trois caractéristiques très importantes :

ils s'appliquent sur les scopes dans la vue, ce qui implique qu'il ne peut pas y avoir d'événement entre les services, en l'absence de scope
la propagation se base sur l'arborescence des scopes, vers la racine ou dans l'autre sens
il peut y avoir plusieurs listeners d'un même événement, ou aucun

Ça veut dire qu'utiliser un événement n'a du sens que s'il faut prévenir de quelque chose un nombre inconnu de listeners attachés aux scope parents ou enfants suivant le sens de propagation choisi, donc en quelque sorte aux éléments HTML parents ou enfants. Ce n'est pas du tout le même paradigme qu'un appel de méthode sur un objet (un service injecté).

Utiliser un événement pour éviter d'appeler directement une méthode d'un service, et surtout éviter d'avoir à l'injecter, c'est détourner le concept pour en faire une utilisation illogique. Ce n'est certainement pas la meilleure façon de rendre le code lisible et facile à comprendre.

Ça revient à compliquer le code, en détournant le concept d'événement, en devant enregistrer un listener et émettre l'événement, pour simplement espérer simplifier un peu les tests. Combattre le mal par le mal, ce n'est pas une bonne idée, au moins en informatique, donc inutile d'essayer de corriger un problème par l'ajout d'un autre problème.

Clairement, il faut limiter l'usage des événements du scope aux rares cas où les trois caractéristiques citées plus haut s'appliquent pleinement, et ne surtout pas essayer d'en faire l'outil générique qu'ils ne sont pas.

Les événements simplifient-ils vraiment les tests ?

Imaginons quand même qu'on veuille utiliser des événements du scope dans l'objectif des tests unitaires. Les rendent-ils vraiment plus simple ?

Avec un couplage par événement, il n'y a aucun paramètre à injecter. Pour les tests qui ne sont pas liés à l'événement, il n'y a donc rien de particulier à faire, pas d'objet à substituer. Mais bien sûr, il faut aussi tester que l'événement est bien déclenché lorsqu'il doit l'être et avec les bonnes données. Deux solutions sont possibles :

utiliser un faux scope, pour vérifier l'appel de $emit() ou $broadcast()
utiliser une mini hiérarchie de scopes avec un listener, pour vérifier qu'il reçoit bien le bon événement

La première est la plus simple : un même mock object du scope pourra faire les vérifications concernant les émissions d'événements pour tous les tests des contrôleurs.

Et avec un service injecté comme dépendance du contrôleur ? Il faut lui substituer un faux service, pour tester seulement le code du contrôleur et non celui du service. Pour les tests qui ne concernent pas ce service, on peut carrément le remplacer par null. Mais pour ceux qui entraînent l'utilisation du service, il faut le remplacer par un objet factice spécifique à ce service, et vérifier les appels de méthodes qui lui sont faits.

On peut créer cet objet factice du service en utilisant un framework de doublure. Il en existe plusieurs en JavaScript, donc un qui est inclus dans Jasmine. Celui-ci peut créer des objets factices, mais aussi remplacer une méthode réelle d'un objet réel par une implémentation factice. Il suffit d'une seule ligne pour obtenir un mock objet avec les méthodes souhaitées.

Donc en fin de compte, si l'on utilise un framework de doublure, le test d'un contrôleur avec injection de service sera aussi simple à écrire que celui d'un contrôleur avec événement.

Evénements entre les services

En isolant chaque fonctionnalité de l'application dans un service, éventuellement subdivisé en plusieurs services plus petits, on va créer pas mal de dépendances entre des services. Bien sûr là aussi il faut s'inquiéter d'un même service qui en prendrait beaucoup d'autres en dépendance, un tel service mériterait sans doute un bon refactoring. Mais on va couramment avoir un service qui prend comme dépendances un ou deux autres services.

Dans une application plutôt conséquente, on peut vouloir limiter le couplage entre certains services, et créer un système d'événements. Attention, il ne s'agit évidemment pas d'utiliser les événements des scopes pour faire communiquer deux services. Les services ne sont pas liés aux scopes. Mais on peut introduire de toutes pièces, sous la forme d'un service bien sûr, un pattern Observer (ou Listener) utilisable entre les services de l'application.

Dans ce cas il n'y a évidemment aucune propagation, simplement un événement qui est envoyé par un unique service de gestion des événements aux listeners enregistrés. L'intérêt est évidemment le découplage entre le déclencheur de l'événement et un nombre quelconque d'observateurs.

Il n'existe pas de système d'événements de ce type en standard dans AngularJS, mais il est très facile d'en faire une implémentation basique bien suffisante, et d'un usage plus large que les événements des scopes.

On peut éventuellement lier ce système d'événements à celui des scopes, en le mettant dans le $rootScope pour propager aux services inscrits, et qui ne sont pas nécessairement publiés dans le scope, des événements tels que les $routeChange*.

Je me souviens d'avoir vu passer un retour d'expérience qui affirmait que sur une grosse application AngularJS, il était indispensable d'avoir un véritable Event Bus. Ou un autre pattern équivalent, mais je ne sais plus où j'ai lu ça. Je ne serais peut-être pas aussi catégorique au point d'en faire une obligation. Mais sur une grosse application, on a vraiment intérêt à faire du découpage, et à la diviser en plusieurs parties bien isolées. Et un Event Bus sert justement à découpler les différentes parties, en remplaçant une dépendance entre deux parties par une dépendance de chacune sur l'Event Bus. On pourra signaler un changement de contexte important dans l'application sans se préoccuper directement des impacts, car dans n'importe quelle autre partie de l'application les services concernés par ce changement se seront inscrits auprès de l'Event Bus et en seront notifiés.

En fait sur une grosse application, il est très probable qu'un Event Bus entre les services s'avère très utile, et si je ne le présente pas comme une obligation, c'est juste parce que je préfère qu'un pattern soit introduit quand on en a constaté le besoin, plutôt que sur des recommandations trop générales, ou parce que ça fait chic.

Et il ne faut surtout pas essayer de remplacer ainsi toutes les dépendances entre les services, et tous les appels de méthodes par des événements, ça n'aurait aucun sens. Il s'agit juste d'introduire un petit nombre d'événements, pour retirer quelques liens trop directs entre des parties autrement séparées de l'application. L'essentiel des appels de méthodes entre services doivent rester inchangés, sur des services injectés comme dépendances.

***

Voilà pour ces quelques réflexions et digressions, et juste en résumé s'il faut retenir 4 conseils :

découpez vos contrôleurs, en extrayant des services et des sous-contrôleurs

n'utilisez les événements des scopes que dans le cadre très restreint où ils peuvent être pertinents

dans les tests unitaires, utilisez un framework pour créer des mocks objets des services à injecter

créez un service Event Bus pour gérer des événements entre les services, si la taille ou la structure de votre application le justifie

Usage des services AngularJS

2013-10-23T00:03:00.006+02:00

Cet article est basé sur la présentation que j'ai faite hier au Meetup AngularJS Paris chez Google. Les slides se trouvent ici, et une vidéo a été mise en ligne là. Mais comme les slides perdent beaucoup de leur intérêt sans les explications qui vont avec, ça méritait bien un article - et même plusieurs, puisque j'ai mis deux exemples dans des articles séparés (les liens sont vers la fin). Je vais aussi en écrire un sur l'autre partie de ma présentation, sur les scopes isolés dans les directives.

S'il y a une fonctionnalité que les développeurs qui débutent sur AngularJS sous-estiment énormément, c'est bien les services. Je me rend compte régulièrement en formation ou lors d'audits que beaucoup de code pourrait être largement simplifié en utilisant plus efficacement les services. Ça n'a d'ailleurs rien d'étonnant, on commence à partir des exemples qu'on trouve sur internet, qui sont des exemples courts et n'ayant évidemment pas toute la structure d'une vraie application. Des exemples qui montrent comment ça marche, pas comment il faut faire.

Dans une application non triviale, au moins 90 % du code JavaScript devrait être dans les services. Il peut y avoir quelques directives et filtres bien sûr, dont une partie peut d'ailleurs être commune à plusieurs applications, mais ce sont les contrôleurs qui doivent être aussi réduits que possible. Un contrôleur AngularJS est juste une fonction d'initialisation du scope correspondant, et il doit essentiellement se limiter à cela : faire quelques affectations dans l'objet scope. Il ne doit pas faire de requêtes HTTP, ni des traitements sur les données, ni gérer le stockage des données.

Qu'est-ce qu'un service ?

Un service n'est rien d'autre qu'un singleton publié sous un certain nom. On peut publier n'importe quelle valeur comme service, un objet JavaScript (y compris un tableau ou une fonction), ou même une valeur primitive : chaîne de caractères, nombre, booléen.

AngularJS gère l'injection des services là où ils sont indiqués comme dépendances, dans des contrôleurs, dans d'autres services, dans des directives ou des filtres. Il s'occupe aussi d'instancier le service, si ce n'est pas un objet préexistant qui est publié. Une fois instancié et publié, chaque injection du service fournira le même objet, par référence, ou une copie de la même donnée primitive. C'est pourquoi un service permet de stocker des données qui seront conservées tant que l'application s'exécute, et qui peuvent bien sûr être modifiées en cours de route.

Pour les différentes façons de créer un service, voir cet article antérieur :
- Les différentes façons de créer un service avec AngularJS

Que mettre en service ?

Pour faire simple, il faut écrire l'essentiel du code d'une application sous la forme de services. Si l'on excepte les directives et les filtres, et qu'on limite les contrôleurs au strict minimum qui est de publier dans le scope les données et fonctions utilisées dans les templates, tout le reste va dans les services.

La liste qui suit est donc loin d'être exhaustive.

Tout le code métier

En particulier, tout le code métier, sans exception, doit être organisé en services cohérents qui correspondent aux différentes fonctionnalités de l'application. C'est la seule façon de s'y retrouver quand l'application prend de l'ampleur.

Si l'on peut concevoir qu'on prenne des raccourcis dans les exemples, et qu'on puisse avoir des règles métiers dans les contrôleurs et les vues, c'est totalement exclus dans une vraie application sur laquelle différents développeurs interviennent, et ce sur une durée plus ou moins longue. Comment s'y retrouver si chaque fonctionnalité de l'application est éparpillée dans de multiples contrôleurs et templates ? Même si AngularJS est un framework qui requiert peu de code, si on ne l'organise pas correctement il sera vite ingérable.

Ça veut dire que pour chaque fonctionnalité de l'application, il faut créer un service qui en regroupe tout les aspects, qui gère les données et fournit toutes les méthodes utiles. Attention en particulier aux règles métier qui peuvent facilement se dissimuler dans les conditions des templates.

Par exemple si l'on crée une application qui gère un compte bancaire, on peut vouloir ajouter une classe CSS 'warning' pour afficher en rouge le solde négatif d'un compte. Si on met des ng-class="{warning: compte.solde < 0}", ça n'a l'air de rien, mais c'est une règle métier qu'on a glissé dans les templates, sans doute à plusieurs endroits. Et le jour où la règle métier change, parce qu'il faut maintenant mettre la classe 'warning' lorsque le solde est en dessous du découvert autorisé, il va falloir revoir tous les templates, au risque d'en oublier et d'avoir des incohérences dans l'application. Alors que si l'on a fait ça proprement, en mettant la règle métier dans une fonction hasWarning() du service 'compte', on n'a qu'un seul endroit à changer pour la modifier.

A l'exception de certaines conditions purement techniques, comme le fait de tester qu'une propriété est définie, toutes les autres se rapportent plus ou moins à des règles métier, et doivent aller dans les services. Avantage supplémentaire, le fait de les mettre sous la forme de fonctions dans les services les rend testables, contrairement aux expressions en dur dans les templates.

Le code de présentation

Les services ne se limitent pas au code métier de l'application. Il y a aussi toute une partie du code, qui est plutôt du code de présentation général sans lien direct avec le métier, qui mérite aussi d'être organisé en services.

J'indique plus loin deux exemples (dans des articles séparés) qui sont directement des fonctionnalités liées à la présentation : la conservation des valeurs des critères d'une page de recherche, et les notifications à l'utilisateur.

Ce sont juste deux exemples de fonctionnalités qui doivent être factorisées dans des services, même si on ne les utilise qu'à un seul endroit, car le fait de créer un service permet d'isoler la fonctionnalité, et de la tester plus facilement et indépendamment de tout contrôleur. Et ça améliore nettement la lisibilité du code de l'application. Ce n'est pas quelque chose de spécifique à AngularJS, c'est tout simplement la technique de refactoring "Extract Class", enfin plutôt "Extract Object" en JavaScript : le fait d'extraire un objet du code du contrôleur permet de lui donner un nom significatif (le nom du service), de nommer ses méthodes, et de l'isoler du reste du code. Les bonnes pratiques de la programmation objet ont toujours cours dans une application AngularJS.

Les requêtes

Les requêtes HTTP à des web services ne sont qu'un exemple de code métier qui n'a rien à faire dans les contrôleurs.

Bien sûr dans les petits exemples on en voit partout, parce que c'est simple et que ça permet de montrer uniquement le fonctionnement des requêtes sans devoir expliquer tout le reste. Je fais aussi de tels exemples. Mais il faut les prendre pour ce qu'ils sont, des démonstrations techniques et surtout pas des exemples à suivre de la façon d'architecturer une vraie application.

Les requêtes à des serveurs posent un problème particulier quand on veut les mettre dans un service, c'est la gestion de l'asynchronisme. Comment écrire un service fournissant des données, mais qui doit faire des requêtes pour les obtenir, et donc qui n'a pas encore les données au moment où il devrait les renvoyer ?

Le service ne peut évidemment pas renvoyer des données qu'il n'a pas encore. Il n'est pas possible non plus d'attendre l'arrivée des données dans la fonction du service qui est appelée, car l'interpréteur JavaScript du navigateur est mono-thread, et la possibilité d'attendre n'existe pas. La fonction doit renvoyer quelque chose immédiatement. Trois solutions sont couramment utilisées :

utiliser une fonction callback : la méthode du service ne renvoie pas de valeur, mais prend en paramètre une fonction callback qui sera appelée plus tard en lui passant les données reçues
renvoyer un objet ou un tableau vide, qui sera alimenté plus tard ; c'est ce que fait $resource
renvoyer une promise, qui sera résolue avec les données quand elles seront reçues du serveur

Donc il est tout-à-fait possible de mettre les requêtes HTTP dans des services, en utilisant l'une ou l'autre de ces solutions, avec une préférence pour la troisième car l'API de promises est puissante et simplifie beaucoup la gestion de l'asynchronisme.

Petite remarque au passage sur les promises, depuis la toute récente version 1.2.0-rc3 les promises ne peuvent plus être utilisées directement dans les expressions AngularJS. Jusque là l'interpréteur d'expressions remplaçait chaque promise par sa valeur de résolution une fois qu'elle était résolue, ce qui permettait d'utiliser une promise de résultat différé comme le résultat lui-même. Cette possibilité est maintenant deprecated, et a même été désactivée par défaut.

Le modèle de données

Un contrôleur AngularJS publie dans son scope les données nécessaires à l'évaluation des expressions du template.

Ca ne veut pas dire que le modèle d'une application AngularJS doit résider dans les scopes, bien au contraire. Il doit être géré, et conservé quand c'est nécessaire, dans des services.

Certains de ces services seront stateless, et d'autres statefull s'il s'agit d'une entité du modèle qui doit être conservée de façon globale, comme par exemple l'utilisateur connecté. Au contraire, si une vue de l'application affiche dans un formulaire une instance d'une collection d'entités fournies par un serveur REST par exemple, dans ce cas le service va être stateless, et simplement renvoyer pour qu'elle soit publiée dans le scope l'entité correspondant à la vue courante.

Ça dépend si l'on veut que l'instance soit conservée de façon globale et qu'on la retrouve dans le même état quand on revient sur la vue, ou s'il faut que cette vue charge une instance précise dont l'identifiant est passé dans l'URL de la route.

Mais dans tous les cas, qu'il conserve ou non l'instance courante, le service contient tout le code des traitements qui s'y appliquent, soit directement comme des méthodes du service, soit comme des méthodes ajoutées à l'instance.

Le fait que le modèle soit géré dans les services permet aussi d'injecter ces services dans d'autres services, et donc de bien organiser le découpage de son modèle de données (incluant les traitements) sous la forme d'un ensemble de services correctement isolés et qui coopèrent, chose totalement impossible si les données se trouvent uniquement dans les scopes.

Différents patterns sont utilisables pour créer les services qui travaillent sur des entités persistantes, comme par exemple le pattern Active Record popularisé par Ruby on Rails, le pattern Repository du DDD (Domain Driven Design), ou encore pour des services statefull le pattern Entity Home abondamment utilisé dans le framework Seam.

Découper les services

Après avoir dit de rassembler tous les constituants de chaque fonctionnalité de l'application dans un même service, me voici à recommander de les découper.

Comme de façon générale en programmation objet, il vaut mieux éviter d'avoir des services obèses. Si une fonctionnalité peut être découpée, parce qu'elle recouvre plusieurs aspects distincts, ou qu'elle concerne plusieurs couches différentes comme la communication avec le serveur, les traitements métier et la présentation, alors il vaut mieux faire plusieurs services qu'un seul. Le code n'en sera que plus compréhensible, et ce n'est pas contradictoire avec le fait de rassembler les éléments d'une même fonctionnalité si l'on ne mélange pas plusieurs fonctionnalités entre elles.

Il faut prendre exemple sur AngularJS lui-même, car le framework est conçu comme un assemblage de petits services, avec des services de haut niveau et d'autres de bas niveau.

Pour les requêtes HTTP, le service $http s'appuie sur un service $httpBackend qui réalise l'envoi de la requête et la réception de la réponse. Ce découpage permet de remplacer ce service de bas niveau $httpBackend par une version 'mock object' fournie avec AngularJS, qui évite de faire réellement les requêtes dans les tests unitaires. On a même le service de plus haut niveau $resource qui s'appuie sur $http, pour gérer des entités persistantes sur un serveur REST.

Pour la gestion du routage interne à l'application, le service $route s'appuie sur le service bas niveau $location qui gère l'URL.

En faisant de même, en découpant nos propres services lorsqu'ils s'y prêtent, on aura un code plus facile à comprendre, et aussi plus facile à tester. Si une fonctionnalité est découpée en plusieurs petits services, ce sera plus facile de tester chaque petit service séparément, en remplaçant les autres par des implémentations factices (mock objects). S'il y a un seul service et que certaines parties doivent être courcircuitées dans les tests unitaires, il va falloir bricoler l'unique objet au niveau de ses méthodes, en espérant que les parties en questions sont au moins dans des méthodes séparées, mais ça sera de toute façon beaucoup moins pratique qu'avec plusieurs services.

Pour les services classiques permettant l'accès à des entités persistantes, et qui font aussi quelques traitements sur ces données, notamment après leur réception du serveur ou avant leur envoi pour sauvegarde, il y a une séparation naturelle entre les traitements sur les entités et la communication avec le serveur, qui gagneront donc être séparés en deux services distincts.

Préférer les services aux événements du scope

Je n'ai jamais caché que je ne suis pas fan des événements qu'on peut propager entre les scopes. Ce n'est pas le concept en soi qui me gêne, mais plus le fait qu'il soit largement trop utilisé, et presque toujours dans des conditions où il n'est pas judicieux, et où un service serait bien plus adapté.

Bon évidemment, quand on a utilisé jQuery depuis des années, on doit trouver qu'AngularJS manque d'événements, et du coup les événements du scope doivent activer un réflexe pavlovien révélateur d'un conditionnement dont beaucoup de développeurs ont du mal à s'extraire. D'ailleurs si je me méfie beaucoup des événements du scope, j'ai une aversion bien plus grande pour l'attribut ng-change des champs de formulaire, qui ressemble davantage à une approche jQuery qu'à celle d'AngularJS. Mais j'en reparlerai une prochaine fois.

Les événements du scope, qui se propagent dans un sens ou dans l'autre de l'arborescence des scopes, n'ont de sens que pour une communication liée à la structure du HTML. Dans tous les autres cas, bien plus fréquents, il est plus logique et plus simple d'utiliser un service.

La façon naturelle avec AngularJS de partager des données entre deux contrôleurs... c'est de ne pas le faire. Car comme je l'ai expliqué plus haut, les données doivent être gérées dans les services, et si deux contrôleurs utilisent le même service, ils travaillent naturellement sur les mêmes données et les mêmes traitements, et il n'y a aucune raison pour qu'ils essaient de communiquer autrement.

De plus l'héritage par prototype entre les scopes fait qu'un objet publié dans son scope par un contrôleur associé à un élément HTML sera accessible aux scopes et contrôleurs correspondant à des éléménts enfants.

Du coup, s'il existe des cas où l'utilisation des événements est pertinente, je ne le nie pas, ils sont plutôt rares, et il vaut bien mieux avoir d'abord le réflexe service plutôt que le réflexe événements. Mais c'est l'inverse que je constate, avec des utilisations complètements illogiques des événements, allant jusqu'à récupérer le $rootScope pour propager un événement dans toute l'arborescence des scopes parce que le scope cible n'est pas dans la bonne branche, ce qui est véritable hérésie.

Exemples d'utilisation des services

Deux des exemples que j'ai présentés hier méritent un article séparé, car ils sont facilement réutilisables en dehors du cadre de cette présentation des usages des services. Vous pouvez donc les trouver sur les pages suivantes :

J'ai parlé aussi d'un service gérant l'utilisateur connecté, en donnant des pistes pour son implémentation. Il est important de créer un service pour la gestion de l'utilisateur, avec ses données et des fonctions par exemple pour vérifier ses droits, plutôt que de mettre ça plus ou moins en vrac dans le $rootScope.

Attention, je n'ai rien contre le fait de publier dans le $rootScope l'utilisateur connecté. C'est une donnée globale de l'application, et si on l'utilise à pas mal d'endroits pour conditionner l'affichage en fonction de ses droits, le plus simple est effectivement de l'avoir dans le $rootScope, pour y accéder depuis n'importe quel template. Mais il faut d'abord en faire un service, et publier ce service (ou une partie de ce service) dans le $rootScope. Comme ça le service lui-même peut être injecté dans d'autres services, ou dans une directive, sans avoir à aller chercher les données dans le scope - qui comme je l'ai dit n'est pas l'endroit où stocker les données du modèle.

Donc notre service pourra être un objet de ce style (et probablement moins simpliste) :

{
    profile:  {
        firstname: "Thierry",
        lastname: "Chatel"
    },
    hasRole: function (role) {
        return ...
    }
}

On crée un contrôleur sur l'élément <body>, qui publie le service complet dans le $rootScope. Si on a un service qui est un objet plus complexes, et donc seulement une partie concerne les templates, on peut faire un sous-objet avec cette partie, et publier seulement celle-ci dans le scope. N'hésitez pas à être imaginatifs.

Une remarque importante qui concerne la sécurité de l'application : il ne faut jamais cacher côté client des données auxquelles l'utilisateur ne doit pas avoir accès. C'est bien trop facile à contourner. Les données non autorisées ne doivent pas être envoyées par le serveur. Donc quand je parle de conditionner l'affichage en fonction des droits de l'utilisateur, c'est pour ne pas afficher une section ou un formulaire vide dans la page (les données n'ayant pas été envoyées par le serveur), c'est de l'esthétique et pas de la sécurité.

***

Voilà pour ce long article, bravo à ceux qui ont eu le courage de le lire jusqu'au bout, et amusez-vous bien avec les services !

J'ai écrit quelques réflexions complémentaires dans un nouvel article, qui peut compléter celui-ci :
- Services ou événements dans l'optique des tests

Conserver les valeurs des critères de recherche

2013-10-23T00:02:00.000+02:00

Comment conserver lorsque l'on change de vue à l'intérieur d'une application AngularJS des données correspondant à l'état de la vue, comme les valeurs des critères d'une recherche ?

Imaginons qu'on affiche dans une vue une liste d'objets, avec des critères permettant de faire un filtrage en local. Et sur chaque objet, un lien permet de naviguer vers une vue des détails de l'objet. Quand l'utilisateur revient sur la liste, il s'attend à la retrouver dans le même état. Ça suppose que les valeurs de filtrage saisies soient conservées.

Or si ces valeurs sont simplement dans le scope de la vue, elles seront perdues à chaque changement de vue, car le scope de l'ancienne vue est détruit par AngularJS. La solution simple pour les conserver est de les stocker dans un service.

Vous pouvez voir un exemple sur GitHub, avec le lien vers la démo (c'est le même que pour l'article "Service AngularJS de notification"). Saisissez une valeur de filtre dans le catalogue, et changez de vue par exemple en cliquant sur l'image d'un des articles. Revenez ensuite au catalogue, par le lien du menu ou avec le bouton "Page précédente" du navigateur. La valeur du filtre a été conservée.

Il suffit pour cela de publier un service qui est un simple objet vide. Le code dans le fichier js/services.js se résume à cette ligne (appliquée à l'objet module) :

.value('search', {})

Tout service AngularJS est un singleton, on est assuré de récupérer à chaque fois le même objet, ce qui permet d'y conserver des données tant qu'on reste sur l'application.

Ce service est injecté au contrôleur CatalogCtrl de la vue catalogue, et publié dans le scope associé (dans le fichier js/controllers.js) :

$scope.search = search;

Dans le template partials/catalog.html, le binding du champ de saisie du filtre se fait par la directive ngModel sur une propriété du service, qu'on utilise aussi dans le filtre 'filter' :

<input ng-model="search.text"/>

<li ng-repeat="game in catalog | filter:search.text">

C'était simple, non ?

Et pour aller plus loin...

Bien sûr cette technique peut s'utiliser pour conserver toutes sortes de données liées à l'état d'une vue, comme des options de visualisation, ou le nombre d'éléments affichés simultanément dans le cas d'une liste paginée, ou encore les colonnes affichées d'une table si on permet à l'utilisateur de les choisir.

On peut créer un service un peu plus sophistiqué, avec une méthode qui renvoie l'état conservé d'une vue d'après un identifiant quelconque attribué à la vue et passé en paramètre, et qui l'initialise si nécessaire avec un état par défaut passé en second paramètre. Il n'y a plus qu'à utiliser cette méthode dans chaque contrôleur d'une vue qui a des données à conserver, et publier l'état dans le scope.

On aura une utilisation de ce service, appelons-le viewState, qui pourra ressembler à ça :

$scope.state = viewState.get('MainListView', {
    pageSize: 50,
    showComments : false
});

Et ce service viewState n'est pas compliqué à écrire, il suffit d'appeler sur le module :

.factory('viewState', function () {
    var states = {};
    return {
        get: function (id, defaultState) {
            return states[id] || (states[id] = defaultState);
        }
    };
})

Service AngularJS de notification

2013-10-23T00:01:00.000+02:00

Un autre exemple de service qui peut être très utile : il s'agit d'afficher des notifications pendant quelques secondes, comme le font les applications de Google, avec un lien dans le message permettant d'annuler l'action.

C'est typiquement le genre de truc qu'on imagine compliqué, mais si on le prend bien, avec AngularJS ça s'écrit en quelques lignes - enfin sans compter le CSS qui finalement est le plus gros du boulot.

L'exemple se trouve ici sur GitHub, et il y a un lien vers la démo (c'est le même que pour l'article "Conserver les valeurs des critères de recherche"). Ajoutez des articles au panier, et quand vous en supprimez du panier, vous avez une notification avec un lien pour annuler l'action.

Cette fonctionnalité de notifications est dans deux fichiers : un template à inclure et un module à ajouter comme dépendance.

Un template

Le template partials/notifications.html, à inclure dans la page index.html de l'application, n'a rien de compliqué : un <div> avec un contrôleur, un <ul> avec un <li> répété sur le contenu de la liste des notifications - il peut y en avoir plusieurs en même temps.

<div id="notifications" ng-controller="NotificationsCtrl">
    <ul>
        <li ng-repeat="notif in notifications">
            <span ng-bind="notif.text"></span>
            <a ng-if="notif.canUndo()" 
                  ng-click="notif.undo()" href="">Annuler</a>
        </li>
    </ul>
</div>

Chaque notification affiche son texte, et si elle le undo est possible, un lien "Annuler" qui appelle la fonction undo() quand on clique dessus.

Le module se trouve lui dans le fichier js/notif.js. Il contient le contrôleur, qui se contente de publier la liste des notifications dans le scope :

.controller('NotificationsCtrl', function ($scope, notification) {
    $scope.notifications = notification.list;
})

Un service

Tout le code - pas si long que ça - est en fait dans le service notification, dans le même module :

.factory('notification', function ($timeout) {
    var service = {
        list: {},
        add: function (text, undo, delay) {
            var timestamp = (new Date()).getTime();
            service.list[timestamp] = {
                text: text,
                canUndo: function () {
                    return angular.isFunction(undo);
                },
                undo: function () {
                    if (angular.isFunction(undo)) {
                        delete service.list[timestamp];
                        undo();
                    }
                }
            };
            $timeout(function () {
                delete service.list[timestamp];
            }, (delay || 5) * 1000);
        }
    };
    return service;
});

Le service conserve une liste des notifications, nommée avec beaucoup d'originalité list.
Et une fonction d'ajout d'une notification, qui prend en paramètres le texte de la notification, la fonction d'annulation, et une durée d'affichage en seconde.

Cette fonction d'ajout utilise un timestamp en millisecondes comme identifiant de la notification - c'était suffisant pour la démo, où il faudrait que l'utilisateur soit particulièrement rapide pour qu'il arrive à faire plusieurs opérations pendant la même milliseconde. Mais pour que ce service soit plus général, et que des notifications puissent éventuellement être créées par d'autres services sans risque de collision, il faudrait utiliser un identifiant plus unique que ça.

Donc la fonction ajoute à la liste un objet contenant le texte de la notification, une fonction canUndo() qui indique si l'on a fourni une fonction d'annulation, et une fonction undo() à appeler pour annuler l'action et qui retire aussi la notification de la liste pour qu'elle disparaisse après annulation.

Après l'ajout dans la liste, elle programme un $timeout pour retirer la notification au bout de la durée d'affichage indiquée, ou 5 secondes par défaut.

Utilisation du service

Alors comment s'utilise ce service ? C'est dans le fichier js/controllers.js que ça se passe. La fonction de suppression d'un article du panier est celle-ci :

        remove: function (row) {
            var self = this;
            delete self.rows[row.game.ref];
            notification.add("Article supprimé : " + row.game.name + ". ", 
                             function () {
                self.rows[row.game.ref] = row;
            }, 6);
        }

Après le delete qui supprime la ligne du panier de l'objet indexé rows, elle appelle l'ajout d'une notification, en passant le message, une fonction d'annulation qui se contente de remettre la ligne supprimée à sa place antérieure, et une durée.

Et le tour est joué !

Validateur pour vérifier qu'une date est postérieure à une autre

2013-10-14T18:05:00.000+02:00

Voici un exemple de validateur spécifique, qui répond au besoin classique de vérifier que la date saisie dans un champ est postérieure à celle saisie dans un autre champ du formulaire. Typiquement, on demande de saisir une date de début et une date de fin, et on veut s'assurer qu'un utilisateur étourdi n'a pas rentré une date de fin qui précède la date de début.

L'exemple est intéressant, car il permet de voir comment valider un champ par rapport à un autre, ce qui n'est pas expliqué dans la documentation d'AngularJS.

Pourquoi un validateur spécifique ?

Evidemment, on peut toujours conditionner l'affichage d'un message d'erreur sur une simple condition portant sur les propriétés du scope, par exemple :

endDate >= startDate

C'est tout simple, mais ça ne s'intègre pas à la validation des formulaires d'AngularJS. Le message d'erreur va s'afficher correctement, mais le formulaire ne sera pas considéré comme invalide.

Ça veut dire qu'il faut penser à ajouter aussi cette condition là où l'on se base sur la validité du formulaire, par exemple pour désactiver le bouton de soumission. Le fait d'ajouter une condition comme celle-ci de façon externe au mécanisme de validation du framework va conduire à devoir l'ajouter à plusieurs endroits, avec le risque d'oublier, et donc d'avoir des incohérences. Surtout si c'est un autre développeur qui ajoute plus tard une condition portant sur la validité du formulaire, il y a peu de chances pour qu'il pense à ajouter cette condition entre les deux dates.

C'est donc une solution simple, mais qui a un impact plutôt négatif sur la robustesse du code. Heureusement, ce n'est pas bien compliqué non plus de créer un vrai validateur qui s'intègre au mécanisme du framework.

Une directive pour valider

En réalité il n'y a pas en soi de validateurs dans AngularJS, ce qu'on crée pour ajouter des conditions de validation spécifiques, ce sont tout simplement des directives, qui peuvent ajouter ou non un parser au champ de saisie.

Donc ce qu'on va créer, c'est une directive dateAfter, à utiliser sur la date de fin, pour spécifier qu'elle doit être postérieure à la date de début :

<input ng-model="data.toDate" date-after="data.fromDate"/>

La valeur de cet attribut date-after placé sur la date de fin est une espression AngularJS, exactement la même que celle du ng-model du champ de saisie de la date de début.

Vous pouvez voir le code complet de l'exemple ici sur Plunker, et faire des essais. L'exemple utilise le date picker de UI Bootstrap pour la saisie de la date, lequel convertit la date saisie en un objet Date JavaScript dans le modèle, ce qui simplifie d'ailleurs la comparaison.

La directive elle-même n'est pas bien compliquée :

  .directive('dateAfter', function () {
    return {
      require: 'ngModel',
      link: function (scope, element, attrs, ngModelCtrl) {
        var date, otherDate;
        scope.$watch(attrs.dateAfter, function (value) {
          otherDate = value;
          validate();
        });
        scope.$watch(attrs.ngModel, function (value) {
          date = value;
          validate();
        });
        function validate() {
          ngModelCtrl.$setValidity('dateAfter',
                 !date || !otherDate || date >= otherDate);
        }        
      }
    };
  })

Elle récupère bien sûr le ngModelController (contrôleur créé par la directive ngModel) de l'élément courant, en l'occurrence le champ de saisie de la date de fin, pour pouvoir indiquer sa validité.

Or la validité doit être revérifiée si l'une ou l'autre des dates change. Il suffit pour cela de mettre deux watches sur le scope :

un qui porte sur l'autre date, en surveillant l'expression qui est dans l'attribut date-after (récupérée via attrs.dateAfter)
et l'autre qui porte sur la date du champ courant, le champ sur lequel est placée la directive, en surveillant l'expression de l'attribut ng-model (via attrs.ngModel)

Ces deux watches stockent la nouvelle valeur de l'expression qu'ils surveillent dans une variable locale de la directive, et déclenchent la fonction de validation. Dans la fonction de validation, il suffit d'utiliser la méthode $setValidity() du ngModelController pour positionner une clef de validation 'dateAfter' avec un booléen indiquant si le champ est valide.

Pas de parser ?

Les exemples de validateurs spécifiques qui sont dans la documentation d'AngularJS (Forms, § Custom Validation) ajoutent au ngModelControler un parser qui est chargé de valider la valeur saisie.

On pourrait faire la même chose pour la date du champ courant, mais dans ce cas il faudrait mettre le parser en fin de tableau, pour qu'il s'exécute après celui du date picker de UI Bootstrap.

Mais je préfère utiliser le $watch, car de cette façon, ça marche même si on modifie la date de début via du code JavaScript dans le contrôleur. Tandis qu'un parser refait la validation seulement quand l'utilisateur fait une saisie dans le champ, pas lorsque la propriété est modifiée par du code.

Voilà pour cet exemple qui pourra être utile à tous ceux qui ont besoin de valider un champ par rapport à un autre.

AngularJS et performances

2013-05-28T16:03:00.002+02:00

La plupart des applications AngularJS ne posent pas de problèmes particuliers de performances. Mais dans certains cas, où une page peut comporter un grand nombre de bindings, il va falloir y prêter attention pour éviter les ralentissements.

Les développeurs d’AngularJS ont toujours indiqué que le framework est capable de supporter sans problème 2000 bindings dans une page web, sur une machine un peu ancienne. C’est un ordre de grandeur, un ordinateur récent avec un navigateur web rapide pourra en supporter beaucoup plus sans soucis. Par contre sur un smartphone un peu poussif, il faudra être prudent pour éviter de se retrouver avec une application pénible à utiliser.

Ça peut paraître beaucoup, 2000 bindings, et dans la majorité des pages d’une application on sera très loin de cette limite théorique, mais avec un gros tableau on peut l’atteindre facilement. Dans le cas d’un tableau comportant 10 colonnes, avec un binding par colonne, il suffit d’afficher 200 lignes pour arriver aux 2000 bindings. Dans tous les cas où l’on va afficher tout un ensemble de données pour chaque élément d’une collection potentiellement grande, que ce soit sous la forme d’un tableau, d’une liste ou de toute autre façon, il va falloir faire attention.

Fonctionnement du dirty checking et des watches

Pour rafraîchir la vue dynamique créée à partir du template HTML, AngularJS utilise des watches. La méthode $watch du scope associe un traitement à exécuter lorsque la valeur d’une expression est modifiée.

A chaque événement, AngularJS parcourt tous les watches, et évalue toutes les expressions, pour déclencher si nécessaire les traitements correspondants. Quand dans le template on met une expression entre double accolades pour afficher un texte provenant du modèle de données, ou qu’on le fait avec un attribut ng-bind, la directive crée un watch pour cette expression, avec du code qui rafraîchit le contenu texte de l’élément HTML si la valeur de l’expression est modifiée.

Et bien sûr, si on le fait à l’intérieur d’un ng-repeat, ça va créer autant de watches que d’occurrences dans la répétition.

Ne pas surveiller n’importe quoi

L’expression d’un watch doit être très rapide à évaluer. Ça peut être un accès à une propriété d’un objet, ou le résultat d’une fonction simple, ou n’importe quel calcul très rapide.

Il ne faut jamais faire de watch sur une expression coûteuse à évaluer, car AngularJS va l’évaluer un grand nombre de fois, et ça aurait forcément un impact très négatif sur les performances de l’application. C’est vrai aussi pour les watches implicites, ceux créés par les directives, ce qui implique qu’il ne faut jamais utiliser une expression coûteuse à évaluer dans une directive qui place un watch.

L’extension Chrome Batarang permet de visualiser les watches d’une application AngularJS, et dispose d’un onglet “Performance” permettant de connaître l’impact en temps d’exécution de chaque expression utilisée dans un watch. C’est la première chose à aller voir en cas de problème de lenteur dans une application.

Mettre en cache dans le scope

On peut améliorer les performances facilement en mettant en cache les résultats des évaluations complexes. Plutôt que de faire évaluer systématiquement une expression coûteuse, on va stocker son résultat dans le scope, et le recalculer seulement lorsque c’est nécessaire. Pour cela, on place dans le contrôleur un watch explicite, avec la méthode $watch du scope, qui fait le calcul complexe et stocke son résultat dans le scope.

C’est ce que j’ai fait dans mon outil de présentation de slides. Le code source des slides est au format Markdown, il est parsé et converti en HTML. Mais ce code source est rarement modifié. S’il y avait des bindings avec comme expression la fonction qui convertit le source Markdown en HTML, la conversion serait faite plusieurs fois à chaque événement tel que l’appui sur une touche, et les performances seraient désastreuses. Au contraire, un simple watch explicite sur le contenu du code source va déclencher la conversion seulement lorsqu’il est modifié :

$rootScope.$watch('source.markdown', function () {
    $rootScope.slides = Presentation.parseSource($rootScope.source.markdown);
});

Le résultat de la conversion est stocké dans le scope, et les bindings portent sur ce résultat, sans nécessiter de faire la conversion à chaque évaluation d’un binding.

Paginer côté client

Parfois ce n’est pas suffisant, aucun watch n’est très coûteux en soi, mais c’est leur grand nombre qui pose problème. C’est le cas quand on fait une répétition sur une grosse collection.

La solution la plus simple est alors de paginer. Si on limite les données affichées dans la page en faisant la répétition (ngRepeat) sur seulement une portion de la collection, alors les directives utilisées dans la partie répétée ne vont plus placer des watches pour tous les éléments de la collection, mais uniquement pour ceux qui sont pris en compte dans la répétition. Quand on pagine côté client, les performances d’AngularJS vont être liées au nombre d’éléments affichés simultanément, et non plus au nombre d’éléments total de la collection.

Problème du scroll infini

Si on préfère une ergonomie en scroll infini à de la pagination, en limitant le nombre d’éléments sur lesquels on fait la répétition au départ, on va aussi améliorer les performances. Mais quand on va scroller, beaucoup scroller, ce nombre va augmenter de plus en plus et peut finir par poser problème. Or il n’est pas facile d’enlever les watches des éléments qui ne sont plus visibles parce qu’on a scrollé, tout en conservant un fonctionnement normal de l’ascenseur.

Mais il y a une autre façon d’optimiser les performances, c’est de générer moins de watches, lorsque c’est possible. Souvent, les données des éléments de la collections ne seront jamais modifiées, et du coup il est inutile d’avoir des watches qui vont surveiller en les recalculant sans arrêt des expressions dont la valeur ne changera jamais.

Imaginons qu’on veuille faire une page web comme la timeline de Twitter, qui fonctionne avec du scroll infini ; enfin pas si infini que ça d’ailleurs, mais on peut quand même scroller longtemps avant d’arriver au bout de la collection de tweets. Les données des tweets n’évoluent pas, et si on a récupéré des centaines de tweets, c’est du gâchis d’avoir des watches qui surveillent le texte des tweets ou le nom de leur auteur, ou encore l’adresse de son image de profil...

Binding sans watch

Dans un tel cas, il faudrait pouvoir faire des bindings résolus une seule fois, qui ne placent pas de watch dans le scope, et n’ont donc pas de gros impact sur les performances. Ce n’est pas possible avec les directives fournies par AngularJS, mais on peut le faire en écrivant ses propres directives.

Ou alors on peut aussi, et c’est encore plus simple, utiliser une directive déjà écrite comme celle-ci : “Bindonce”. Elle permet de faire un bind sans watch sur des données qui ne sont pas susceptibles d’évoluer. On peut même l’utiliser avec des données récupérées en asynchrone, auquel cas il y a quand même un watch temporaire, mais un seul watch sur l’objet complet, et qui est supprimé lorsque les données sont arrivées. De toute façon à l’intérieur d’une répétition, la portion du template ne sera répétée qu’une fois que les éléments de la collection auront été chargées, donc le watch temporaire est inutile.

Directive spécifique

Il est aussi possible de réduire le nombre de watches en créant une directive spécifique à ce qu’on veut afficher, qui va construire la portion de template répétée en manipulant le DOM, et sans placer toute une série de watches inutiles.

Dans l’exemple des tweets, on peut faire une directive qui affiche complètement un tweet. Mais il ne faut pas qu’elle utilise un template avec les directives standards d’AngularJS qui impliquent la pose de watches. Elle doit récupérer les données du tweet dans le scope et construire directement dans le DOM, et une fois pour toute, la portion de HTML à afficher.

C’est faisable, mais ça demande plus de travail que d’utiliser une directive générique comme celle citée précédemment (Bindonce). Et ce n’est pas forcément beaucoup plus efficace en terme de performances.

Pas d’optimisations prématurées

Dans tous les cas, il y a une règle générale concernant les optimisations, qui n’a rien de spécifique à AngularJS : il ne faut optimiser que lorsqu’il y a un problème de performances. Dans la plupart des cas tout se passe très bien, et il n’est pas souhaitable de complexifier l’application inutilement. S’il n’y a pas trop de bindings dans la page, le gain de performances serait sans doute trop faible pour que l’utilisateur s’en rende compte, et pour justifier des optimisations superflues.

Communauté AngularJS France, et rédacteurs pour FrAngular

2013-03-22T15:15:00.000+01:00

Je me suis dit qu'il manquait un espace pour les échanges et les annonces concernant AngularJS en France. Les rencontres, soirées ou conférences sur notre framework préféré commencent à se multiplier, et il devient difficile de savoir ce qui a lieu en France, ou comment avertir le public intéressé.

Du coup je viens de créer une communauté sur Google+ intitulée - après une longue réflexion - “AngularJS France”. Ce n'est peut-être pas hyper original, mais on moins on comprend assez vite de quoi il s'agit. Elle est toute fraîche, les pixels ne sont pas secs, et j'en suis encore le seul membre mais j'imagine que ça ne va pas durer. Elle n'a pas pour but de concurrencer la communauté AngularJS officielle, mais simplement de permettre de trouver facilement les infos locales sur le sujet.

J'y ai mis une première annonce d'événement, la session AngularJS que j'animerai ce mercredi (27 mars) à Devoxx France, de 13h30 à 16h30. Trois heures, ça laisse le temps de montrer plein de choses. Par contre ça représente beaucoup de préparation, et je ne pourrai sans doute pas écrire de nouvel article pour ce blog avant quelques temps, la fin du mois de mars et le début d'avril s'annonçant très chargés.

S'il y a des développeurs AngularJS qui ont envie d'écrire des articles sur FrAngular, qu'ils n'hésitent pas à se manifester. Pour l'instant nous ne sommes que trois à y avoir pondu quelques articles, tous les trois de Montpellier où AngularJS commence à être bien connu, et pas seulement grâce à moi puisque Benjamin n'avait assisté à aucune de mes interventions lorsqu'il m'a contacté. Mais nous ne sommes pas sectaires, les contributeurs sont acceptés d'où qu'ils viennent.

Voilà, alors à bientôt à Devoxx France pour ceux qui y vont, et sur la communauté AngularJS France pour tout le monde.

Comment aborder AngularJS ?

2013-03-14T18:29:00.000+01:00

Si vous avez lu les articles publiés sur FrAngular qui détaillent des aspects techniques du framework, c'est que vous avez peut-être déjà dépassé le stade de l’initiation. Néanmoins, pour ceux qui découvrent AngularJS, je vais expliquer comment on peut aborder ce framework dont l’apprentissage risque de s’avérer quelque peu déroutant.

Commencez par JavaScript

JavaScript est certainement le langage le plus mal connu de ses utilisateurs de toute l’histoire de l’informatique. Combien de développeurs qui font du JavaScript ont vraiment pris le temps de l’apprendre ? On y reconnaît une syntaxe familière parce qu’on a déjà fait du Java, du C++, du PHP, enfin quelque chose qui y ressemble de très loin, et du coup en tâtonnant on arrive à écrire du code JavaScript qui fonctionne à peu près. Mais du très mauvais code JavaScript. Je suis passé par là, comme presque tout le monde.

Les concepts de JavaScript - un langage objet sans classes et avec un forte composante fonctionnelle - sont complètement différents des autres langages objets les plus répandus. Il y a plus de ressemblance entre Java, C#, Python, Ruby, et même PHP en version objet, qu’entre n’importe lequel de ces langages et JavaScript.

AngularJS ne requiert pas une très grande expérience de JavaScript, mais pour être à l’aise sur les exemples et le développement d’applications, il faut avoir compris les principaux concepts du langage : les fonctions et le fait qu’elles sont de vrais objets, leur utilisation comme constructeur, le mécanisme de closure, les différentes façons de créer des objets, etc.

On m’a dit au Marseille JUG qu’AngularJS c’est du JavaScript décomplexé. J’ai bien aimé l’expression, car en effet c’est juste du JavaScript, mais du vrai JavaScript qui n’essaie pas de ressembler à un langage objet basé sur des classes. Donc si on aborde le code des applications AngularJS en ayant en tête le paradigme objet de Java, C# ou autre, il y a de quoi être perplexe.

Mieux vaut commencer par un peu de lecture sur JavaScript, dans un bouquin ou avec un tutoriel en ligne. AngularJS est un framework qui bouscule nos habitudes, et s’il faut en même temps comprendre JavaScript, la première marche de l’apprentissage peut être trop haute et rebuter même les plus courageux.

Le passage obligé du tutoriel officiel

Le tutoriel du site officiel est particulièrement bien fait, et il ne faut surtout pas passer à côté. Il permet, en étant guidé pas à pas, de découvrir l’essentiel des fonctionnalités et la façon de développer une application avec AngularJS. Seule la création de ses propres directives (les composants d’AngularJS) n’est pas abordée, à raison car c’est une partie qui demande déjà une certaine compréhension du framework. Commencez par utiliser celles qui existent, avant de vouloir écrire les votres.

En suivant toutes les étapes du tutoriel, grâce à l’utilisation judicieuse de branches Git, on découvre les différents aspects de la création d’une application mono-page, qui incluent les tests unitaires et les scénarios de tests fonctionnels.

Donc commencez l’apprentissage directement par le tutoriel de bout en bout, plutôt que par la documentation. N’essayez pas de lire la doc avant d’avoir fait le tutoriel, beaucoup de notions qui pourraient paraître hermétiques à la lecture seront bien plus compréhensibles si vous les avez déjà rencontrées de façon concrète au travers du tutoriel.

Le guide du développeur, et autres ressources

Les articles du guide du développeur, sur le site officiel, expliquent les différents aspects du framework : les contrôleurs, modules, services, l’injection de dépendances, les directives, etc. Le premier à lire est celui intitulé “Conceptual Overview” qui décrit en détails le fonctionnement d’AngularJS, il peut même être lu avant d’aborder le tutoriel.

Toute la documentation “API Reference” est comme son nom l’indique une doc de référence dans laquelle piocher pour connaître le détail de l’utilisation et du fonctionnement de chaque directive ou service fourni avec le framework. Elle contient de nombreux exemples d’utilisation. Bien sûr, même si elle est déjà volumineuse et très utile, elle reste perfectible, et toutes les questions n’y trouveront pas forcément une réponse. Il y a de nombreux échanges sur des questions techniques dans la mailing list ou sur Stack Overflow. Malgré tout, même s’il ne s’agit pas de la documentation idéale dont rêve tout développeur, peu de frameworks en ont une aussi complète.

En dehors du site officiel, il faut évidemment citer les vidéos de John Lindquist, de courtes séquences où il présente et explique la plupart des aspects du framework.

Oubliez jQuery

Il vaut mieux apprendre AngularJS sans que jQuery soit chargé. AngularJS utilise jQuery s’il est présent, mais il contient en interne une implémentation “jQuery lite” contenant tout ce dont il a besoin, ce qui le rend parfaitement autonome.

Le danger, si jQuery est présent, c’est de prendre les choses à l’envers. On ne peut pas ajouter de l’AngularJS à une application jQuery. C’est un framework très structurant, qui impose sa façon de développer une application web. Pour un développeur habitué à jQuery, ou à d’autres outils de ce type, le plus dur c’est sans doute d’oublier ce qu’il connaît, et de ne pas se raccrocher à ses habitudes.

Le fonctionnement des vues dynamiques d’AngularJS n’a rien à voir avec les manipulations de DOM que beaucoup de développeurs web ont intégré comme un mal nécessaire, au point de finir par trouver naturel de développer ainsi une application. Toutes ces manipulations techniques qui constituent souvent la plus grande partie du code n’ont aucune raison d’être avec AngularJS. Dans une application AngularJS, on ne touche jamais au DOM. On utilise des directives, dont certaines peuvent modifier le DOM de la page web, mais la création de tels composants est la seule exception à la règle. Les contrôleurs et services ne travaillent que sur le modèle de données, ils n’ont même pas accès à la vue. Mélanger du code JavaScript ou jQuery manipulant le DOM dans les templates d’une application AngularJS, c’est une erreur qui est fréquente chez les débutants.

Bien sûr on peut encapsuler un composant jQuery UI dans une directive AngularJS, et dans ce cas il faudra que jQuery soit chargé. Mais si on n’utilise aucune directive de ce genre, alors autant ne pas charger jQuery. L’implémentation interne à AngularJS est suffisante pour écrire ses propres directives, et ça évitera le mauvais réflexe d’utiliser jQuery ailleurs que dans une directive.

Il y a une discussion sur Stack Overflow, intitulée “How do I ‘think in AngularJS’ if I have a jQuery background?”, qui est intéressante à lire sur le sujet. Mais je ne suis pas vraiment d’accord avec le point n°1 de la réponse, on peut très bien faire d’abord le design HTML d'une page web, pour y ajouter ensuite les directives AngularJS.

Persévérez !

Voilà pour ces quelques conseils sur la façon d’aborder AngularJS. C’est un framework qui apporte toute l’architecture nécessaire pour développer la partie cliente d’une application web de façon très efficace. Mais de part son ampleur, il nécessite un réel apprentissage pour dépasser le stade des exemples simples.

On peut rapidement commencer à écrire quelques lignes de jQuery, ou même faire le tour d’un framework minimal comme Backbone.js. Faire le tour d’AngularJS, c’est beaucoup plus long. Après des mois à l’utiliser, vous découvrirez encore de nouvelles possibilités. Ne soyez pas dissuadés par cet apprentissage, le gain de productivité qu’il apporte est tellement énorme que ça vaut vraiment le coup de s’y investir.

Le langage d'expressions d'AngularJS

2013-03-05T19:01:00.000+01:00

Voici un article qui tient du paradoxe, puisque je vais y décrire les possibilités du langage d'expressions d'AngularJS, tout en expliquant qu'il faut les utiliser au minimum.

Avec AngularJS, on utilise des expressions pour le binding, et avec de nombreuses directives. Elles ressemblent à des expressions JavaScript, mais n'en sont pas. Elles ne sont pas directement évaluées par l'interpréteur JavaScript, mais parsées et exécutées par AngularJS. Du coup on ne peut utiliser qu'un sous-ensemble des opérateurs et des mots-clefs de JavaScript, et elles divergent aussi de JavaScript sur quelques aspects.

Garder les expressions simples

La règle importante, c'est de ne pas mettre de code dans les vues. Le code mis dans les vues ne peut pas faire l'objet de tests unitaires, et est difficilement gérable.

Donc dans les expressions, il faut se limiter à du binding sur des propriétés des objets du scope, à des appels de fonctions du scope, à des comparaisons simples quand il s'agit d'expressions booléennes, à des choses basiques de ce genre, et ne jamais y mettre du code non trivial qui mérite d'être testé. Il vaut mieux remplacer les expressions complexes par des appels à des fonctions qu'un contrôleur publie dans son scope.

Les mots-clefs et opérateurs disponibles

La liste des mots-clefs utilisables est particulièrement courte, puisqu'ils sont au nombre de quatre, et leur rôle est le même qu'en JavaScript :

true
false
undefined
null

Celle des opérateurs disponibles est plus fournie, et là encore ils fonctionnent comme en JavaScript :

+ - * / %
( )
== != < > <= >=
!
&& ||
=== !== en version 1.1.2
= (affectation d'une variable)

Quand je dis que ces opérateurs fonctionnent comme en JavaScript, c'est tout simplement parce que l'évaluateur d'AngularJS appelle l'opérateur JavaScript correspondant sur les opérandes. Donc il y a très peu de chances pour que le résultat soit différent.

Du coup les opérateurs && et || vont comme en JavaScript court-circuiter l'évaluation dès que c'est possible, et renvoyer la valeur du dernier opérande évalué, donc potentiellement tout autre chose qu'une valeur booléenne.

Les opérateurs de comparaison stricte, c'est-à-dire sans conversion automatique de type, ont été ajouté en version 1.1.2, mais ils ne sont pas disponibles dans la branche 1.0.

L'opérateur d'affectation permet d'affecter une valeur à une propriété du scope. En règle générale, ce n'est pas une bonne idée de publier des choses dans le scope depuis une expression de la vue. Mais il y a quand même quelques cas où c'est tolérable, par exemple pour effacer la valeur d'un champ de filtrage en cliquant sur un lien, une petite croix à côté du champ. On peut préférer faire ça avec un ng-click="search = ''", sans avoir envie de créer une fonction dans le scope juste pour ça.

Il y a un opérateur classique qui manque à la liste, c'est l'opérateur conditionnel ternaire ... ? ... : ... qui n'est effectivement pas disponible dans le langage d'expressions d'AngularJS. Il y a eu des discussions sur le fait de le rajouter, ça n'a pas été fait du moins pour l'instant, l'idée étant que cet opérateur qui s'apparente à un if pourrait inciter les développeurs à mettre trop de logique dans les expressions. On peut contourner cette absence en utilisant une des deux constructions suivantes :

condition && valeurTrue || valeurFalse
{true: valeurTrue, false: valeurFalse}[condition]

Mais ce n'est pas forcément recommandé, le réflexe devrait être plutôt de créer une fonction dans le scope que d'utiliser une de ces deux syntaxes alambiquées.

Propriétés et méthodes

Tous les noms d'identifiants utilisés dans des expressions AngularJS sont recherchés comme des propriétés du scope. C'est la première chose qu'on utilise dans les bindings, je ne vous apprends rien. On peut utiliser le point ou les crochets pour accéder à une propriété d'une objet, ou les crochets uniquement pour accéder à un élément d'un tableau par son index, exactement comme en JavaScript.

La grosse différence, c'est que si dans une expression on essaie d'accéder à une propriété d'un objet nul ou non défini, ça ne provoque aucune erreur. Pareil pour un élément d'un tableau nul ou non défini. Et il est indispensable que ça fonctionne comme ça : une vue ne plante pas si des données ne sont pas encore chargées, simplement ces données apparaîtront lorsqu'elles seront disponibles.

La contrepartie du fait que ça ne provoque aucune erreur, c'est que si l'on a réellement fait une erreur, par exemple une faute de frappe, on ne verra rien. Raison de plus de ne pas mettre de code dans les expressions des vues, car le debug n'y est pas pratique.

On peut bien sûr accéder à n'importe quelle propriété d'un objet JavaScript, par exemple à la propriété length d'un tableau, ou appeler n'importe quelle méthode.

Filtres

Là évidemment c'est quelque chose qui n'existe pas dans des expression JavaScript. Les filtres sont propres à AngularJS. Si le symbole utilisé pour les filtres est la barre verticale, ce n'est pas sans rapport avec les “pipes” d'Unix : un filtre prend des données en entrée, et fournit des données en sortie. Il peut aussi recevoir des paramètres, indiqués à la suite du nom du filtre, séparées par le caractère ':'. Et on peut chaîner plusieurs filtres.

data | filterName:param1:param2 | otherFilter

Création d'objets et tableaux

Dans une expression AngularJS, on peut créer un objet ou un tableau comme on le ferait en JavaScript, avec {...} ou [...].

Là encore c'est à utiliser avec parcimonie, mais ça peut quand même être très utile pour alimenter les paramètres d'une fonction (ou d'un filtre) qui attend un objet ou un tableau.

list | paginate:{index: currentPage, size: pageSize}

Priorités

Les priorités des opérateurs ne sont pas déroutantes puisque ce sont les mêmes qu'en JavaScript. On peut juste se demander à quel niveau de priorité se classe le filtre.

Et bien voici un tableau des opérateurs triés par priorité, des plus prioritaires aux moins prioritaires, réalisé d'après le code du framework :

Opérateurs	Description
. [...] (...)	propriété d'un objet, élément d'un tableau, appel de méthode
(...) [...] {...}	parenthèses pour grouper des opérations, création d'un tableau ou d'un objet
! - +	opérateurs + et - unaires (ex : -5)
* / %
+ -	opérateurs + et - binaires (ex : 8 - 5)
< > <= >=
== != === !==	en version 1.1.2 pour === et !==
&&
\|\|
=	affectation d'une variable
\|	filtres
;	séparateur d'instructions

On voit donc que le filtre est quasiment ce qu'il y a de moins prioritaire, encore moins que l'opérateur d'affectation (mais je ne suis pas sûr que mélanger filtres et affectations soit une grande idée).

Quasiment, parce que le point-virgule séparant deux instructions est encore moins prioritaire que le filtre. Mais franchement je ne vois pas quel bon usage peut-être fait d'un séparateur d'instructions dans une expression AngularJS. D'ailleurs un commentaire dans le code laisse entendre qu'il pourrait être supprimé.

Et s'il manque quelque chose ?

Pour ajouter une fonctionnalité utilisable dans les expressions, vous avez deux possibilités :

publier une fonction dans un scope
créer un filtre

Si c'est pour un usage bien localisé, il vaut mieux publier une fonction dans le scope d'un contrôleur, et vous pourrez l'utiliser seulement dans ce scope-là.

Si le besoin est général, faites un filtre, ce n'est pas vraiment plus compliqué à créer qu'une simple fonction JavaScript, et il sera disponible dans toutes les expressions de toutes les vues.

Compiler une expression

Le service $parse intégré au framework permet de compiler une expression AngularJS, ça la transforme en une fonction qui peut être exécutée en lui passant le scope. C'est quelque chose qui peut être utile lors de l'écriture de directives.

Mais attention à ne pas réinventer la roue. Quand il est pertinent de créer un scope isolé pour une directive, alors c'est plus simple de définir des propriétés dans ce scope isolé en utilisant les opérateurs préfixes @, = et & pour référencer des attributs de l'élément HTML. Dans un tel cas on n'aura pas besoin de compiler manuellement les attributs contenant des expressions, le framework s'en charge.

Je crois que le paragraphe précédent doit ressembler à du chinois pour ceux qui n'ont jamais écrit de directives. Il faudra que j'écrive quelques articles là-dessus, mais le sujet est vaste, et ça sera pour une autre fois.

En tout cas j'espère que celui-ci aura permis de clarifier les idées sur le langage d'expressions d'AngularJS.

AngularJS, ce n'est pas pour jouer

2013-02-28T12:13:00.002+01:00

De nombreux messages ont circulé hier sur Twitter annonçant un jeu en ligne, Bombermine, réalisé avec AngularJS. Étonnant... mais erroné. J’ai moi-même rediffusé un de ces messages, avant de regarder de plus près et de voir qu’AngularJS n’est utilisé que pour l’interface utilisateur, mais que le jeu lui-même est écrit avec GWT.

AngularJS est particulièrement efficace pour la réalisation d’application web, mais pas du tout adapté à la création de jeux.

CRUD... au sens large

Les développeurs d’AngularJS le présentent comme un framework destiné à la réalisation d’applications de type “CRUD” (Create - Read - Update - Delete), c’est-à-dire des applications web affichant des données, et permettant de les saisir ou de les modifier.

C’est effectivement le cas, si l’on ne prend pas le terme CRUD dans un sens trop restrictif, voire péjoratif. Il ne faut pas imaginer des applications réduites à l’affichage de trois pauvres formulaires, bien au contraire.

Le cœur d’AngularJS, c’est son système de vues dynamiques rafraîchies automatiquement, et fonctionnant par du data-binding à double sens. Les vues d’AngularJS constituent la représentation d’un état des données du modèle, et c’est le critère qui permet de voir quand ce framework est adapté. Il est pertinent pour toutes les applications dont l’interface est essentiellement une représentation de données facilement modélisables sous la forme d’objets JavaScript.

Mais ce n’est pas forcément un simple affichage de texte ou de formulaires, la représentation peut être bien plus sophistiquée que ça, on peut avoir des graphiques, des cartes géographiques, des schémas en SVG, comme dans ces quelques exemples :

Ces exemples présentent des utilisations d’AngularJS très pertinentes, car il s’agit bien de représentation de données, où le principe de binding dans les vues dynamiques facilite largement la tâche du développeur. En fait le type d'application CRUD où AngularJS est très efficace couvre la quasi-totalité des applications de gestion.

Quand AngularJS n’est pas approprié

Là où AngularJS est déconseillé, c’est quand l’application web ne représente pas directement des données, quand on ne peut pas créer la vue par des bindings simples sur un ensemble d’objets JavaScript.

L’exemple que cite généralement Miško Hevery, c’est Google Documents. L’interface de traitement de texte de Google Documents est beaucoup plus complexe qu’une simple vue HTML représentant l’état d’un modèle de données. C’est vraiment un cas où AngularJS n’apporterait rien au développeur, et serait même totalement inapproprié.

L’autre cas typique, c’est la création de jeux. Bon évidemment, il y a quelques jeux où ce qui s’affiche est une représentation assez simple d’un état des données. Un jeu d’échecs par exemple : l’échiquier affichant la position des pièces, c’est juste la représentation d’un tableau à deux dimensions en JavaScript ; pour la partie IA, c’est une toute autre histoire... Mais sur des jeux un peu plus animés, la part de binding sur les données devient minime par rapport à la complexité du dessin et des animations, et essayer d’utiliser AngularJS serait une erreur.

Pour des adaptations de jeux de plateau, jeux de cartes ou wargames, AngularJS peut être pertinent, et on peut imaginer un système du type de Vassal basé sur AngularJS. Etant un fervent adepte de ce genre de jeux, je creuserai peut-être cette idée un de ces jours.

More fun ?

Bon d’accord, AngularJS n’est pas fait pour créer des jeux, mais ça peut quand même être amusant à utiliser. Le premier slogan qui était imprimé sur les tee-shirts à l’époque où AngularJS était en beta et que son logo de super-héros n’avait pas encore été créé, c’était “10x less code, 10x more fun”. Certes le dix fois moins de code était un peu exagéré, mais pas tant que ça, et l’aspect amusant voire ludique mis en avant est bien réel.

Le haut niveau d’abstraction d’AngularJS fait qu’on écrit vraiment la logique de présentation de son application web, au lieu d'accumuler la frustration en passant son temps à bricoler le DOM pour essayer d’arriver à faire marcher quelque chose. Le côté gratifiant pour les développeurs, c’est un aspect très important à prendre en compte quand on choisit une plate-forme, car c’est ce qui les motive les plus.

Qui sait, peut-être qu’un jour on verra dans l’informatique des syndicats qui revendiqueront de travailler avec AngularJS.

Les fonctionnalités de Twig avec AngularJS: angular-twig-pack

2013-02-19T08:00:00.000+01:00

Depuis que je travaille avec AngularJS, j'ai entendu beaucoup de gens comparer le Framework avec divers moteurs de template... Et il en existe! La liste (non-exhaustive) de wikipedia: Template_engine_(web) en est la preuve. Malheureusement, Wikipedia ne nous numérote pas ce tableau, heureusement que la console est là:

> document.querySelectorAll('.wikitable tbody tr').length

Bon ... Trêve de plaisanterie, passons aux choses sérieuses. Je me suis dit pourquoi ne pas prendre un moteur de template existant et créer un pack de directives, filters et services pour ne pas trop dépayser les puristes.

Kezako

Pour cet exercice, j'ai choisi le Framework Twig (uniquement car je l'ai déjà utilisé et surtout car j'adore les couleurs du site: http://twig.sensiolabs.org/).

Du coup, j'ai créé un projet GitHub : angular-twig-pack. J'ai également fait une démo disponible sur le repo pour tester les différentes fonctionnalités. Le projet n'a rien d'extraordinaire niveau programmation, c'est uniquement un pack qui montre qu'AngularJS peut facilement être adopté par tous les développeurs ... avec un peu de bonne volonté :-D

Les modules

Pour regrouper et organiser les différentes fonctionnalités de ce pack, j'ai utiliser les modules d'AngularJS. La notion de module est vraiment très intéressante pour notre cas. Elle permet de regrouper plusieurs modules en un seul twig ce qui rend modulaire notre développement.

Je me suis largement inspiré des différents packs disponible pour AngularJS : AngularUI et AngularUI Bootstrap entre autres.

Je vous invite à lire ce bref article qui résume assez bien les modules AngularJS, leurs fonctionnements et leurs rôles: I.T. Aware.

angular-twig-pack implémente des filters, des directives et un service. Ces différentes entités contiennent et mettent à disposition les fonctionnalités du Moteur de Template Twig que j'ai trouvées intéressantes d'intégrer.

La directive for

Cette directive est assez sympathique car elle intègre quelques contraintes.

La première est celle d'être à l'écoute des différentes variables passées en paramètre. Il faut pour cela utiliser la méthode $watch disponible dans l'API d'AngularJS. Cette méthode permet d'écouter tous changements sur une variable afin d'exécuter une méthode. Dans notre cas, de recalculer les conditions et les variables du for.

La seconde vient du fait que l'on peut dans l'expression de la directive définir à la fois des variables du scope, une expression qui se traduit par un range et l'utilisation possible de filter dans cette expression. Pour fonctionner, j'ai utilisé les expressions régulières (un petit outil en ligne pour tester les regex: http://www.pagecolumn.com/tool/regtest.htm) ainsi que la méthode $compile d'AngularJS, qui permet d'utiliser pleinement le moteur de template.

La démo! La démo!

Dernière petite chose avant la démo, la liste des fonctionnalités de ce pack.

Filters:

url_encode
json_decode
title
capitalize
upper
striptags
join
reverse
length
sort
default
keys
escape
abs
nl2br
number_format
slice
trim
divisibleby
even
odd

Directives:

for
if (if/elseif/else)
macro (macroSet et macroGet)

Service:

twig.random
twig.divisibleby
twig.even
twig.odd

Enfin la démo! Bon alors pour les gens qui ne veulent pas cloner le projet et le lancer en local, voici le lien de la démo: FRAngular_angular-twig-pack

GitHub: http://firehist.github.com/angular-twig-pack/

J'attends vos retours, remarques, suggestions, etc. :-D

Bon dév'

Un outil de présentation en AngularJS

2013-02-13T10:37:00.000+01:00

Pour une fois je ne vais pas vous détailler un aspect technique du framework, mais présenter une petite application qui peut être utile. Mais si je la présente ici, c'est bien sûr parce qu'elle est écrite avec AngularJS, et qu'il y a quelques exemples dans le code qui peuvent vous intéresser.

J'avais besoin d'un outil pour présenter des slides sur AngularJS en début de semaine prochaine : lundi 18 février à LyonJS, et mardi 19 février au Marseille JUG. Bien sûr il existe maintenant des outils pour faire des présentations en HTML avec plein d'effets spéciaux impressionnants. Mais je dois être de la vieille école, parce que j'ai toujours l'impression que ces effets qui en mettent plein la vue détournent l'attention du contenu. En fait je ne mets jamais d'animations dans mes présentations ; sans pousser aussi loin le minimalisme, je penche plus vers la “méthode Lessig”. Donc tout ce dont j'avais besoin c'était d'un outil comme ShowOff, permettant d'écrire rapidement les styles dans une syntaxe markdown.

Mais ShowOff c'est une application serveur, en Ruby, avec une liste de dépendances presque aussi longue que le bras. Du coup j'ai écrit ce week-end une version simplifiée avec AngularJS, une simple application cliente sans côté serveur. Je l'ai mise sur GitHub : angular-showoff. Il y a un lien vers la démo dans le descriptif.

Utilisation d'un $watch

Je peux vous montrer quelques trucs intéressants dans le code. D'abord comme c'est une application AngularJS, on peut modifier le code source markdown des slides (appuyez sur 's' dans la démo), et l'affichage est rafraîchi automatiquement. Ça ne sert à rien à l'usage, sauf éventuellement pour rectifier une erreur à la volée pendant la présentation, mais c'est toujours impressionnant !

Ça marche grâce à un $watch, qui permet de parser le code source à chaque fois qu'il est modifié :

    $rootScope.$watch('source.markdown', function () {
        $rootScope.slides = Presentation.parseSource($rootScope.source.markdown);
    });

Il aurait été possible de faire le binding sur une fonction qui parse le code markdown, mais ça n'aurait pas été une bonne idée, car AngularJS l'aurait exécutée sur chaque évènement, comme un changement de slide. Alors qu'avec un $watch et en stockant le résultat dans le scope, ça permet de parser seulement lorsque c'est nécessaire.

Compilation d'un template depuis une propriété

Comme j'avais besoin de cet outil pour présenter des slides sur AngularJS, je voulais pouvoir montrer des exemples fonctionnels directement à l'intérieur des slides, au moins pour des exemples simples. Il y a un “Hello Word” sur la dernière slide de la démo, si vous voulez voir.

Pour ça, il fallait qu'AngularJS compile le contenu des slides, comme avec un <ng-include>. Mais la directive ngInclude ne permet pas de charger le code du template à inclure depuis une propriété du scope. Du coup j'ai utilisé une directive includeContent qui est une copie légèrement modifiée de ngInclude.

J'ai une autre idée pour faire ça, qui pourrait être plus simple, mais il faudra que je fasse quelques essais parce que je ne sais pas si c'est réalisable ; ça sera pour plus tard.

Directive correspondant à un vrai élément HTML

Il restait juste un problème à régler. Je voulais mettre de la coloration syntaxique sur les blocs de code, en utilisant google-code-prettify, lequel a besoin d'une classe “prettyprint” sur les éléments <pre> à colorer, qui n'est évidement pas présente dans le HTML généré par le parser markdown utilisé. Et il faut aussi déclencher une méthode prettyPrint() s'il y a de tels blocs à décorer.

J'ai utilisé une solution toute simple, à laquelle on ne pense pas forcément. Quand on pense aux directives AngularJS, on imagine ajouter de nouveaux attributs ou éléments au HTML. Mais on peut aussi créer une directive qui s'applique à des éléments standards du HTML. Il me suffisait donc de faire une directive nommée “pre”, pour qu'elle soit déclenchée sur tous les éléments <pre> générés par le parser dans les slides, puisque le code HTML des slides est compilé par AngularJS.

Voici le code de cette directive :

module.directive('pre', ['$rootScope', '$timeout', function($rootScope, $timeout) {
    var prettyPrintTriggered = false;
    return {
        restrict: 'E',
        terminal: true,  // Prevent AngularJS compiling code blocks
        compile: function(element, attrs) {
            if (!attrs['class']) {
                attrs.$set('class', 'prettyprint');
            } else if (attrs['class'] && attrs['class'].split(' ')
                                                .indexOf('prettyprint') == -1) {
                attrs.$set('class', attrs['class'] + ' prettyprint');
            }
            return function(scope, element, attrs) {
                if (!prettyPrintTriggered) {
                    prettyPrintTriggered = true;
                    $timeout(function () {
                        prettyPrintTriggered = false;
                        prettyPrint();
                    });
                }
            };
        }

    };
}]);

Elle rajoute systématiquement la classe CSS “prettyprint”, et elle programme avec un $timeout le déclenchement de google-code-prettify, s'il n'a pas déjà été programmé, car s'il y a plusieurs blocs de code dans une slide, il ne faut l'exécuter qu'une fois.

Pouvoir ajouter ainsi un comportement à n'importe quel tag HTML, ce n'est pas forcément d'un usage très classique, mais je suis sûr que dans certains cas ça peut être très utile, dans des cas comme celui-ci où l'on n'a pas la main sur le code HTML.

Dans le fichier des directives, vous trouverez aussi celle qui sert aux évènements clavier, pour changer de slide, afficher l'aide, le footer, etc. Elle n'a rien de très mystérieux.

***

Et pour les lecteurs de Lyon et Marseille, rendez-vous en début de semaine prochaine pour une soirée complète sur AngularJS !

Solution simple pour des formulaires avec données différées

2013-02-08T14:48:00.000+01:00

Je ne suis pas sûr d'avoir trouvé un titre très vendeur pour cet article, mais vous y trouverez un exemple qui peut être très utile. C'est une solution hybride entre les $resource et les promises du service $q d'AngularJS. Elle est très simple à mettre en oeuvre, pour utiliser avec des formulaires travaillant sur des données chargées en asynchrone, un besoin somme toute très fréquent.

AngularJS fournit en standard le service $resource, qui permet de gérer facilement des entités chargées en asynchrone, mais il est prévu pour fonctionner avec une API serveur de type REST. Il n'est pas nécessaire que ce soit une API strictement RESTful, mais il ne faut pas qu'elle s'en éloigne trop pour que l'utilisation du service $resource soit pertinente.

L'autre inconvénient, avec $resource, c'est que les objets ressources contiennent uniquement les données, une fois que celles-ci sont arrivées. On n'a pas accès à la promise du service $http utilisé en sous-main. Donc pas moyen par exemple d'afficher un message “Chargement en cours...” à la place d'un formulaire tant que l'objet ressource correspondant n'est pas chargé. On ne peut pas non plus enchaîner des chargements de ressources, par exemple pour charger via plusieurs requêtes des entités liées entre elles, puisqu'on ne peut pas déclencher les requêtes suivantes lorsque la première entité est alimentée.

Si l'on n'utilise pas de $resource, il ne reste dans AngularJS pas d'autre option que le service $http de base, qui renvoie une promise. Avec des promises, les enchaînements de requêtes sont possibles. Mais à la fin de l'article sur l'API Promise d'AngularJS, j'expliquais que si les promises s'utilisent très bien dans les vues tant que c'est pour faire de l'affichage, ça pose problème dans les formulaires. En effet si les champs d'un formulaire sont associés aux données d'une promise, on retrouve les propriétés modifiées à un endroit et les propriétés non modifiées à un autre (voir la fin de l'article indiqué pour l'explication détaillée). Ce n'est pas vraiment pratique lors de la sauvegarde. Ce problème n'existe pas avec une $resource, qu'on peut utiliser sans aucun problème dans un formulaire.

Alors comment faire pour avoir le côté pratique d'une $resource qu'on peut associer directement aux champs d'un formulaire, mais sans les à-côtés inutiles quand on travaille avec un serveur qui n'a manifestement jamais entendu parler de l'architecture REST, et tout en gardant la possibilité d'accéder à la promise de la requête $http ?

Voici la solution à laquelle je suis arrivé, un service “DeferredData” simple à utiliser, avec un exemple complet ici sur Plunker.

Le service est défini dans le fichier deferreddata.js :

angular.module('deferreddata', [])
       .factory('DeferredData', ['$q', function ($q) {

  function deferredDataBuilder(isArray) {
    var deferredData = isArray ? [] : {};
    var defer = $q.defer();
    var waiting = true;
    deferredData.$isWaiting = function() {
      return waiting;
    };
    deferredData.$getPromise = function() {
      return defer.promise;
    };
    deferredData.$resolve = function(data) {
      if (waiting) {
        waiting = false;
        // ... ici le code qui copie les données dans l'objet deferredData...
      }
      return defer.resolve(deferredData);
    };
    return deferredData;
  }
    
  return {
    typeArray: function () {
      return deferredDataBuilder(true);
    },
    typeObject: function () {
      return deferredDataBuilder(false);
    }
  };
}]);

Pour créer un objet avec des données différées, il suffit alors d'appeler DeferredData.typeArray() si les données sont dans un tableau JavaScript, ou DeferredData.typeObject() si elles sont dans les propriétés d'un objet JS. L'objet (ou le tableau) ainsi créé possède trois méthodes spéciales, en plus des données différées qu'il va recevoir :

$resolve(data) : pour charger l'objet ou le tableau avec les données, quand elles sont arrivées
$getPromise() : qui renvoie la promise associée
$isWaiting() : qui indique si l'objet ou le tableau est toujours en attente de ses données

Dans l'absolu la méthode $isWaiting() n'est pas indispensable, mais c'est un raccourci plus pratique que d'appeler à chaque fois then() sur la promise pour faire basculer un témoin, surtout si on veut l'utiliser dans une expression de la vue.

Voyons comment ce service est utilisé dans l'exemple sur Plunker. Dans le fichier app.js, on a un service User, avec une méthode load(id) pour charger un utilisateur, et save(user) pour enregistrer l'utilisateur modifié. L'exemple est bidon car il n'y a pas de serveur, en fait l'utilisateur est un objet en dur renvoyé au bout de 3 secondes, pour simuler une requête suffisamment lente pour qu'on puisse voir ce qui se passe, et l'enregistrement affiche juste une alerte avec les données. Mais ça serait la même chose avec de vraies requêtes $http.

    load: function (id) {
      var deferredData = DeferredData.typeObject();
      $timeout(function () {
        deferredData.$resolve({firstname: 'Thierry', lastname: 'Chatel'});
      }, 3000);
      return deferredData;
    },

Dans la fonction load(id) ci-dessus, on crée un objet de données différées en appelant DeferredData.typeObject(), et il est renvoyé immédiatement, à ce moment-là il ne contient aucune donnée. Son chargement est fait dans un $timeout au bout de 3000 millisecondes, en passant les données à charger à sa méthode resolve().

Et dans le contrôleur, on publie cet objet dans le scope :

app.controller('Ctrl', function($scope, User) {
  $scope.user = User.load(42);

  $scope.user.$getPromise().then(function (data) {
    $scope.message = "User loaded";
  });
  
  $scope.save = function () {
    User.save($scope.user);
  };
});

L'appel de la méthode then() de sa promise (renvoyée par $getPromise()) est un exemple de message publié dans le scope lorsque les données sont reçues.

Dans la vue, les champs du formulaire sont associés directement aux propriétés de cet objet aux données différées :

    <h1>User: <span ng-show="user.$isWaiting()">[loading...]</span></h1>
    <p class="message">{{message}}</p>
    <form ng-hide="user.$isWaiting()">
      <p>
        Firstname:<br/>
        <input ng-model="user.firstname">
      </p>
      
      <p>
        Lastname:<br/>
        <input ng-model="user.lastname">
      </p>
      
      <p>
        <button ng-click="save()">Save</button>
      </p>
    </form>

J'ai mis dans l'élément <h1> un <span> qui n'est visible que tant que les données ne sont pas arrivées. Et le formulaire au contraire est caché tant qu'on n'a pas reçu les données.

C'est très pratique à l'usage, et bien sûr tout ce qui est saisi dans les champs du formulaire impacte directement les propriétés de l'objet, donc il n'y a pas de précaution particulière à prendre lors de la sauvegarde, on peut envoyer l'objet tel quel au serveur.

La seule chose qu'il ne faut bien sûr pas faire, car ça reste quand même un objet dont les données sont différées, c'est d'utiliser la valeur d'une de ses propriétés directement dans le code du contrôleur, pour la copier ailleurs, ou pour conditionner du code. Parce que lorsque le contrôleur est initialisé, les données ne sont pas encore là. Donc il ne faut jamais écrire quelque chose comme ça dans le contrôleur, parce qu'on copierait une donnée encore vide :

$scope.userFirstname = $scope.user.firstname

Mais par contre on peut le faire sans risque dans un callback passé à la méthode then() de la promise :

$scope.user.$getPromise().then(function (data) {
  $scope.userFirstname = $scope.user.firstname;
});

Voilà pour les explications sur ce petit exemple qui peut vous rendre de grand services en vous simplifiant la gestion de l'asynchronisme. Bien sûr ce n'est certainement pas la seule solution possible, aussi n'hésitez pas à suggérer d'autres approches dans les commentaires ou sur le forum.

Drag & Drop avec AngularJS

2013-02-04T15:02:00.000+01:00

Le drag & drop est revenu à la mode avec l'arrivée des tablettes et des smartphones. Un temps boudé par les développeurs web, il est de bon ton d'offrir de tels mécanismes dans nos applications web. A l'image de Trello et de ses fameuses colonnes, nous allons voir comment rendre des éléments html draggable et droppable.

Pour ceux qui veulent voir, directement, le code complet et une démo, un jsFiddle est disponible tout en bas.

AngularJS est très fort lorsqu'il s'agit d'afficher un modèle. Mais qu'en est-il de mettre à jour le modèle en fonction d'actions dans la vue ? Et bien une fois de plus AngularJS nous surprend en nous permettant de rajouter des comportements au HTML. Pour ce faire il suffit de créer des directives.

Nous allons donc créer deux directives, une pour le drag et une autre pour le drop. La première directive se chargera de rendre l'élément HTML draggable et gérera les événements dragStart et dragEnd. Tandis que la directive du drop permettra à l'élément HTML d'afficher un feedback lors du survol et appellera un callback lors du drop.

Ecouter un événement du DOM

Pour pouvoir placer un écouteur sur un événement d'un élément HTML, AngularJS nous offre la fonction bind (tout droit issu de la petite partie de JQuery embarquée) :


link: function(scope, element, attrs) {
    element.bind('dragenter', function(evt) {
        ...
    });
}

Un peu de code : les directives

Nous pouvons donc écire la directive drag :


app.directive("drag", ["$rootScope", function($rootScope) {
  
  function dragStart(evt, element, dragStyle) {
    element.addClass(dragStyle);
    evt.dataTransfer.setData("id", evt.target.id);
    evt.dataTransfer.effectAllowed = 'move';
  };
  function dragEnd(evt, element, dragStyle) {
    element.removeClass(dragStyle);
  };
  
  return {
    restrict: 'A',
    link: function(scope, element, attrs)  {
      attrs.$set('draggable', 'true');
      scope.dragData = scope[attrs["drag"]];
      scope.dragStyle = attrs["dragstyle"];
      element.bind('dragstart', function(evt) {
        $rootScope.draggedElement = scope.dragData;
        dragStart(evt, element, scope.dragStyle);
      });
      element.bind('dragend', function(evt) {
        dragEnd(evt, element, scope.dragStyle);
      });
    }
  }
}]);

Cette directive rajoute l'attribut "draggable" sur l'élément HTML et écoute les événements du DOM qui nous intéressent. Nous pouvons également remarquer que les attributs de la directive sont récupérés grâce au paramètre attrs (attributs). Il est préférable, dans ce cas, de ne pas créer de scope isolé afin de pouvoir utiliser la directive de drag avec d'autres directives (ng-repeat par exemple).

De plus, le $rootScope est utilisé pour stocker l'objet (du modèle) qui sera transféré lors du drop. En effet, comme nous découplons la directive du drag et la directive du drop, lors du drop nous voudrons connaitre l'objet du drag. Pour ce faire le plus simple est d'utiliser le scope racine de tous les scopes. Mais vous pouvez très bien le stocker dans le scope parent si les directives sont sur des éléments HTML frères.

La directive pour le drop :


app.directive("drop", ['$rootScope', function($rootScope) {
  
  function dragEnter(evt, element, dropStyle) {
    evt.preventDefault();
    element.addClass(dropStyle);
  };
  function dragLeave(evt, element, dropStyle) {
    element.removeClass(dropStyle);
  };
  function dragOver(evt) {
    evt.preventDefault();
  };
  function drop(evt, element, dropStyle) {
    evt.preventDefault();
    element.removeClass(dropStyle);
  };
  
  return {
    restrict: 'A',
    link: function(scope, element, attrs)  {
      scope.dropData = scope[attrs["drop"]];
      scope.dropStyle = attrs["dropstyle"];
      element.bind('dragenter', function(evt) {
        dragEnter(evt, element, scope.dropStyle);
      });
      element.bind('dragleave', function(evt) {
        dragLeave(evt, element, scope.dropStyle);
      });
      element.bind('dragover', dragOver);
      element.bind('drop', function(evt) {
        drop(evt, element, scope.dropStyle);
        $rootScope.$broadcast('dropEvent', $rootScope.draggedElement, scope.dropData);
      });
    }
  }
}]);

Outre la gestion des styles qui est triviale, nous remarquons le broadcast de l’événement dropEvent, qui permet de prévenir les écouteurs qu'un drop a eu lieu. Comme pour la directive de drag, il est plus simple d'émettre l'événement à partir du rootScope, mais il pourrait très bien être émit avec un scope parent.

Si vous n'êtes pas à l'aise avec les scopes et les événements, n'hésitez pas à lire (ou à relire) l'article : AngularJS : Scopes et évènements.

Utilisons nos directives

Il ne nous reste plus qu'à créer le HTML :


    <div ng-repeat="c in columns" class="column"
      drag="c" dragStyle="columnDrag"
      drop="c" dropStyle="columnDrop">
      {{c.title}}
    </div>

Et notre contrôleur :


app.controller('ColumnController', ["$scope", "$rootScope", 
  function($scope, $rootScope) {

    $scope.columns = [{title:"1"}, {title:"2"}, {title:"3"}, {title:"4"}];
    
    $rootScope.$on('dropEvent', function(evt, dragged, dropped) {
        var i, oldIndex1, oldIndex2;
        for(i=0; i<$scope.columns.length; i++) {
            var c = $scope.columns[i];
            if(dragged.title === c.title) {
                oldIndex1 = i;
            }
            if(dropped.title === c.title) {
                oldIndex2 = i;
            }
        }
        var temp = $scope.columns[oldIndex1];
        $scope.columns[oldIndex1] = $scope.columns[oldIndex2];
        $scope.columns[oldIndex2] = temp;
        $scope.$apply();
    });
    
}]);

Dans ce contrôleur, nous écoutons l'événement dropEvent afin d'inverser les colonnes dans le modèle. Ainsi, lors du $scope.apply(), angularJs rafraîchira la vue, et le drag&drop sera effectif.

Le jsFiddle complet.

En vrai ça donne quoi ?

Vous pouvez voir cette technique appliquée sur le projet skimbo. La seule différence est qu'il y a un écouteur supplémentaire, il s'agit du service de communication avec le serveur. Ainsi le nouvel ordre des colonnes est envoyé au serveur pour être sauvegardé. Si ça vous intéresse vous trouverez tout le code du projet sur github.

J'espère que cet article vous sera utile. N'hésitez pas à commenter, améliorer et débattre dans les commentaires ou sur le forum !

Google Chart Tools avec AngularJS

2013-01-25T11:13:00.000+01:00

Pouvoir inclure un graphique dans une application AngularJS par la simple utilisation d'une directive, l'idée est séduisante. Et bien sûr, pour respecter la philosophie du framework, le graphique doit se mettre à jour quand les données changent.

Voici un exemple de directive qui permet exactement ça, pour un graphique de type camembert, en l'occurrence le “Pie Chart” de Google Chart Tools. L'utilisation est toute simple :

<pie-chart data="chartData" title="My Daily Activities" 
           width="500" height="350"
           select="selectRow(selectedRowIndex)"></pie-chart>

Dans les attributs, on fournit simplement les données (ici "chartData", c'est le nom d'une propriété du scope, comme avec ng-bind), le titre du graphique, ses dimensions, et éventuellement une expression qui est exécutée lorsque l'utilisateur sélectionne une portion du camembert.

Cliquez ici pour ouvrir ce premier exemple sur Plunker. Contrairement aux articles précédents, je n'ai pas mis cet exemple sur jsFiddle, car celui-ci entrait en conflit avec les scripts de Google Chart Tools. Sur Plunker (qui d'ailleurs est écrit avec AngularJS), il n'y a pas de problème ; en local non plus bien sûr.

Voyons d'un peu plus près comment ça marche. Dans le fichier app.js, on initialise AngularJS manuellement, en appelant angular.bootstrap(), pour que l'initialisation ait lieu seulement lorsque le chargement de la bibliothèque Google Chart Tools est terminé :

google.setOnLoadCallback(function() {
  angular.bootstrap(document.body, ['app']);
});
google.load('visualization', '1', {packages: ['corechart']});

Le scope isolé de la directive

Mais passons à la directive pieChart elle-même. Elle définit un scope isolé, contenant des propriétés qui correspondent aux cinq attributs possibles de l'élément HTML :

    scope: {
      title:    '@title',
      width:    '@width',
      height:   '@height',
      data:     '=data',
      selectFn: '&select'
    },

C'est un exemple intéressant, car on y trouve les 3 façons de publier des propriétés dans le scope isolé d'une directive en fonction des valeurs des attributs de l'éléments HTML. Les propriétés title, width et heigth, sont spécifiées par '@', ce qui crée une propriété égale à la valeur de l'attribut html associé (on peut d'ailleurs omettre le nom de l'attribut s'il correspond au nom de la propriété). La valeur de cet attribut peut être une chaîne de caractères en dur, comme c'est le cas dans ce premier exemple. Mais elle peut aussi être partiellement ou totalement évaluée par AngularJS si elle contient une expression encadrée par {{...}}, et dans ce cas la propriété est recalculée lorsque l'expression incluse dans l'attribut change de valeur. Vous l'aurez deviné, c'est en fait un binding automatique géré par AngularJS.

Vous pouvez ouvrir ici un second exemple sur Plunker, avec exactement la même directive, mais où les attributs title, width et height sont alimentés par des propriétés du scope (pas le scope isolé de la directive, le scope parent, c'est-à-dire le scope dans lequel est placé le graphique), ce qui permet d'en changer la valeur dans la page web :

<pie-chart data="chartData" title="{{chartTitle}}" 
           width="{{chartWidth}}" height="{{chartHeight}}"
           select="selectRow(selectedRowIndex)"></pie-chart>

La propriété data est publiée dans le scope isolé de la directive en la spécifiant avec un '=' suivi du nom de l'attribut HTML, ce qui publie simplement la propriété du scope parent dont le nom est passé dans l'attribut. Dans l'exemple, avec data="chartData", ça publie dans le scope isolé une propriété data égale à la propriété chartData du scope parent. Donc c'est un attribut qui s'utilise sans doubles accolades, comme ng-bind ou ng-model.

La dernière propriété du scope isolé, selectFn, est spécifiée avec un '&' suivi du nom de l'attribut. AngularJS publie comme propriété une fonction qui évalue l'expression passée dans l'attribut en question. Donc notre propriété selectFn sera une fonction générée par Angular qui évaluera l'expression fournie, ou qui n'évaluera rien si l'attribut select n'est pas présent. L'attribut select peut ainsi contenir n'importe quelle expression valide du langage d'expression d'AngularJS, comme dans un ng-click. Ça peut être un appel de fonction comme dans l'exemple, ou encore l'affectation d'une propriété du scope parent du style "selectedRow = selectedRowIndex".

Mais d'où sort ce selectedRowIndex ? Il est fournit lors de l'exécution de cette fonction selectFn générée par AngularJS :

$scope.selectFn({selectedRowIndex: selectedItem.row});

Ça signifie que l'attribut select peut contenir n'importe quelle expression portant sur des propriétés ou fonctions du scope parent, et dans cette expression, selectRowIndex sera alimenté avec l'index sélectionné.

La fonction de dessin du graphique

A la fin de la directive, on définit une fonction draw() chargée de dessiner le graphique, en lui fournissant les données, et des options comme le titre et les dimensions.

Cette fonction est appelée une première fois systématiquement. Mais il y a aussi une série de quatre $watch qui la rappellent en cas de modification détectée par AngularJS sur les données du graphique, la valeur du titre, la largeur ou la hauteur. C'est ce qui permet de voir le graphique se modifier si on change certaines données dans le premier exemple, ou également le titre ou les dimensions dans le second exemple.

Le $watch correspondant aux données a une particularité, le troisième paramètre égal à true dit à AngularJS de ne pas simplement surveiller la référence à l'objet, mais toutes ses propriétés, c'est un $watch en profondeur :

      $scope.$watch('data', function() {
        draw();
      }, true); // true is for deep object equality checking

Si l'on écrivait juste une fonction dessinant le graphique, déclenchée sur ces quatre $watch, ça marcherait bien sûr, mais ça ne serait pas optimal. Chaque $watch est surveillé par AngularJS en conservant l'ancienne valeur, et en lui comparant la nouvelle. Mais la première fois, il n'y a pas d'ancienne valeur connue, et du coup chaque $watch est déclenché lors du premier $digest (la phase où AngularJS vérifie tous les $watch). Du coup, on aurait systématiquement un premier dessin du graphique déclenché par l'appel en dur de la fonction draw(), immédiatement suivi de quatre autres déclenchés par les quatre $watch. Dessiner cinq fois le même graphique alors que rien n'a été modifié, ce n'est pas très satisfaisant, même si ça va trop vite pour qu'on puisse le voir.

C'est pour ça que j'ai différé tout le contenu de la fonction draw() en utilisant le service $timeout pour qu'il s'exécute après la fin de la phase $digest, et surtout en le conditionnant sur une propriété draw.triggered. Cette propriété est ajoutée à l'objet JavaScript qui n'est autre que la fonction draw elle-même, et elle est alimentée à true lorsque le traitement différé par $timeout a été déclenché. Du coup si cette propriété est déjà égale à true, on évite de le déclencher une seconde fois, ce qui fait que le dessin proprement dit du graphique ne se fera qu'une fois pour une même phase $digest. Bien sûr on remet la propriété à false lorsque s'effectue le traitement différé, pour en permettre à nouveau le déclenchement lors d'une phase $digest ultérieure, si l'une des valeurs surveillées par les $watch a été modifiée.

Gestion de la sélection sur le graphique

L'utilisateur de la page web peut sélectionner une des portions du camembert, et Google Chart Tools permet d'enregistrer un listener qui sera déclenché lors de cette sélection :

      // Chart selection handler
      google.visualization.events.addListener(chart, 'select', function () {
        var selectedItem = chart.getSelection()[0];
        if (selectedItem) {
          $scope.$apply(function () {
            $scope.selectFn({selectedRowIndex: selectedItem.row});
          });
        }
      });

Ce que fait notre directive dans ce code, c'est qu'elle appelle la fameuse fonction selectFn générée dans le contexte isolé par AngularJS, et dont l'exécution évalue l'expression passée dans l'attribut select. C'est ainsi que dans les deux exemples ça appelle la fonction selectRow(selectedRowIndex) publiée dans son scope par le contrôleur, où selectedRowIndex est alimenté par l'index de la sélection. Visuellement ça met un fond rouge à la ligne correspondante dans le tableau des données, simplement en renvoyant une classe CSS différente pour la ligne sélectionnée via une fonction du scope.

On pourrait de la même façon traiter d'autres évènements susceptibles d'être déclenchés par ce graphique en camembert, comme onmouseover et onmouseout qui correspondent au fait de passer la souris au-dessus des portions du camembert.

Voilà pour cet exemple de directive intégrant un graphique de la bibliothèque Google Chart Tools à AngularJS, qui devient ainsi très pratique à utiliser. On peut bien sûr créer des directives similaires pour les autres graphiques de Google Chart Tools. Il y aura parfois de petites différences correspondant aux particularités de chaque graphique, par exemple le “Line Chart” prend plusieurs séries de valeurs, et la sélection ne correspond plus simplement à un index, mais à un index à l'intérieur d'une série.

De JSF à AngularJS

2013-01-22T15:10:00.000+01:00

Ce matin j’ai partagé sur Twitter cet article en anglais qui fait une comparaison entre AngularJS et JSF. D’autres que moi l’ont partagé aussi, mais il y a eu quelques réactions étonnées, du genre : “c’est une blague ?”.

Pour moi la comparaison n’a rien d’absurde, et mérite de plus amples explications que ce qu’on peut écrire dans un tweet de 140 caractères.

Tout comme l’auteur de l’article, je viens du monde Java et j’ai travaillé avec JSF pendant 5 ans, certes surtout comme architecte et en support à mes collègues qui l’utilisaient au quotidien, mais j’ai aussi fait ma part de développements. Et moi aussi en découvrant AngularJS, j’ai forcément constaté des ressemblances entre les deux frameworks.

Des templates déclaratifs avec data-binding...

Tout d’abord, quand je parle de JSF, ce n’était pas le JSF des origines avec des templates en JSP et des tonnes de fichiers de configuration en XML, une horreur que je n’aurais jamais accepté d’utiliser. Il s’agissait d’une combinaison de JSF, de Facelets pour les templates (qui est la technologie de templates utilisée dans JSF 2.0), et du framework Seam (devenu Weld) pour l’injection de dépendances des services, et leur publication dans les différents contextes afin qu’ils soient directement utilisables pour le data-binding des composants JSF. N’allez pas raconter que j’ai dit qu’AngularJS ressemblait aux immondes pages JSP, je démentirai formellement !

Avec cette combinaison JSF + Facelets + Seam (ou Spring si vous voulez), on a des templates déclaratifs basés sur HTML avec du data-binding et un langage d'expression, qui ressemblent beaucoup à ceux d’AngularJS comme l'a très bien montré l'auteur de l'article cité. Je suis un grand partisan des templates déclaratifs. Je trouve l’approche déclarative beaucoup plus efficace que l’approche procédurale pour la création d’une interface utilisateur. Avant JSF, j’ai fait plusieurs années de Swing, et j’avais pu constater à quel point c’était lourd ; puissant certes, mais avec une lourdeur toujours présente pour une puissance rarement nécessaire. Quand on doit écrire un éditeur “rich text”, on apprécie la puissance de Swing, mais pour des usages plus classiques on passe son temps à maudire sa lourdeur. JavaFX était une très bonne idée, celle de rajouter des templates déclaratifs à la puissance de Swing, dommage qu’elle soit arrivée trop tard.

Mais revenons-en à nos templates JSF/Facelets. Aussi similaires soient-ils, il y a quand même des différences avec ceux d’AngularJS. Déjà, les composants JSF sont forcéments des éléments du pseudo XHTML, alors que les directives d’AngularJS peuvent être aussi des attributs. Du coup avec AngularJS, on peut avoir plusieurs directives sur un même élément : une directive est généralement un comportement applicable à un élément plutôt que l’élément lui-même. Avec Facelets, il faut imbriquer plusieurs composants JSF pour combiner leurs comportements.

... mais traités côté serveur

Une différence bien plus fondamentale, c’est que le template AngularJS est du HTML qui est analysé par le navigateur web avant qu’AngularJS n’intervienne dessus, tandis qu’avec JSF, c’est le moteur de Facelets qui convertit côté serveur le template en HTML pur. Avantage pour JSF, comme le traitement est fait côté serveur, on a un accès direct aux objets Java du serveur, notamment aux entités persistantes. Il n’y a pas besoin d’une couche intermédiaire de web services pour échanger les données avec le client, c’est nettement plus simple, surtout lorsqu’il y a une gestion assez pointue des droits sur les données de ces objets. Par contre AngularJS est plus proche du HTML, travaille en manipulant le DOM dans le navigateur web plutôt qu’en générant du HTML souvent trop verbeux comme le font les composants JSF. On aura d’une façon générale avec AngularJS des pages HTML plus propres et moins lourdes.

L’autre gros problème de JSF, c’est le stockage de l’état des composants, qui peut se faire côté serveur ou côté client. Encore qu’il est difficile d’envisager sérieusement le stockage de l’état côté serveur : comme JSF ne sait pas vraiment ce qu’il se passe dans le navigateur, il faut conserver l’état de plein de pages pour espérer qu’un utilisateur ayant ouvert plusieurs onglets ne soumette pas un formulaire d’une page dont l’état a été perdu ; inutile de préciser que dans ce mode la consommation de mémoire par utilisateur connecté est tout simplement colossale. Le mode qui fonctionne mieux, c’est celui consistant à stocker l’état des composants JSF sérialisé dans un champ caché de la page web. Plus de problème de consommation de mémoire côté serveur, ni de pages dont l’état a été perdu puisqu’il est conservé dans la page elle-même, mais ça implique de gros échanges pour passer dans un sens et dans l’autre cet état sérialisé, pour la moindre requête Ajax. Alors on en vient à faire un peu de jQuery pour éviter ces lourds échanges serveurs dès qu’on veut mettre un peu d’interaction dans une page web. Le résultat, c'est qu'on mélange du code client dans le template serveur, et ce qui était plutôt élégant devient horrible à maintenir.

Du web “terminal passif” au web “client-serveur”

C’est là qu’on touche aux limites du fait de gérer côté serveur une interface client. JSF, du moins une combinaison JSF + Facelets + Seam, est très efficace pour créer des applications web classiques, pour ne pas dire à l’ancienne, avec des pages web distinctes et peu d’Ajax. C’est le web façon terminal passif. Pour ce genre d’applications, gérer l’interface utilisateur côté client, même avec un framework aussi pratique qu’AngularJS, suppose de créer toute une API en web services REST échangeant du JSON, ce dont on est dispensé avec JSF.

Mais dès qu’on veut faire une application web plus réactive, éventuellement mono-page, c’est-à-dire quand on veut passer du web terminal passif au web client-serveur, alors JSF n’est plus du tout pertinent, et AngularJS s’avère un bien meilleur choix. JavaScript est de nos jours largement assez puissant pour gérer dans le navigateur web toute la couche de présentation d’une application, et c’est une approche beaucoup plus logique et plus cohérence, pour avoir de l’interaction sans échange avec le serveur, pour gérer correctement l’historique du navigateur dans une application mono-page.. En bref, on peut maintenant abandonner les solutions trop complexes et d’un autre âge, qui découlaient de la nécessité de gérer la présentation dans une technologie complètement déconnectée du langage natif du navigateur web, et même souvent exécutée côté serveur. Pour moi les JSF, GWT ou autre Vaadin apparaissent aujourd'hui comme des impasses de l’évolution du développement web, des espèces condamnées à l’extinction à plus ou moins court terme.

Et si un client JavaScript suppose une API en web services pour l’échange des données, c’est de toute façon une architecture qui se généralise car elle permet aussi de communiquer avec des applications mobiles, ou des services externes. Donc oui, on peut encore trouver des cas où une application web pourra être développée plus rapidement avec JSF qu’avec AngularJS, si ce n’est pas une application mono-page, qu’elle comporte peu d’interactions côté client, qu’il n’y aura pas de version mobile, etc. Ça n’empêche pas que malgré leurs similitudes, l’approche de JSF est du passé, et c’est celle d’AngularJS qui prévaudra pour ces prochaines années. Les ressemblances permettront une transition plus facile pour les anciens de JSF, et c'est une bonne chose.

AngularJS: Service de gestion de raccourcis clavier

2013-01-15T08:00:00.000+01:00

A l'image des applications Google, Twitter et autres grosses applications Web du moment, il est très "user-friendly" (convivial pour les franglophobes !) de mettre en place une série de raccourcis clavier pour utiliser de manière optimisée l'application.

Les raccourcis clavier sont une touche ou une combinaison de deux ou plusieurs touches à presser simultanément afin d'éviter une action de pointage par la souris. Le fait de ne pas déplacer en permanence la main entre le clavier et la souris fait déjà gagner un temps précieux pour les gens qui travaillent toute la journée sur une application. De plus, à chaque action de la souris, il faut un temps de pointage pour déplacer le curseur sur l'endroit voulu.

Comment centraliser la gestion de ces raccourcis dans une application AngularJS ?

Nous allons voir comment utiliser un service AngularJS pour rendre cette gestion de raccourcis clavier générale.

Les services dans AngularJS

Je vous invite à prendre connaissance de cet article concernant la création et la déclaration des services dans AngularJS: http://www.frangular.com/2012/12/differentes-facons-de-creer-un-service-angularjs.html

Cet article vous décrira ce qu'est un service pour AngularJS, et vous expliquera comment les créer, quel pattern utiliser, etc... Bonne lecture!

Création du service

Pour créer ce service, je me suis inspiré très fortement d'une librairie disponible sous licence BSD (cf. définition) disponible à cette adresse: http://www.openjs.com/scripts/events/keyboard_shortcuts/

J'ai effectué la conversion de la librairie pour qu'elle s'intègre correctement avec l'environnement que nous met à disposition AngularJS.

Vous trouverez ci-dessous un code de démonstration sous jsFiddle.

Voilà un cas simple d'utilisation des services avec AngularJS. La force de ces singletons, c'est qu'ils assurent une unicité très forte dans toute notre application. Cette assurance nous permet de gérer les raccourcis facilement de n'importe quel contrôleur ou service de notre application, à la seule condition d'avoir injecté correctement ce service.

Intégrer les modifications dans le cycle de vie d'AngularJS

Lors de l'utilisation d'un raccourci, le callback est exécuté en utilisant le service $timeout fourni par AngularJS, ce qui permet de placer son exécution au sein du cycle de vie d'AngularJS.
Il est également possible d'utiliser directement la méthode $apply ou $digest sur le $rootScope (cf article sur les Scopes et évènements), mais ayant eu quelques fois l'erreur suivante : Error: $digest already in progress, j'ai décidé d'opter pour le $timeout qui s'occupe seul de synchroniser les données tout en évitant les erreurs.
PS: Il existe un moyen de prévenir cette erreur à cette adresse https://coderwall.com/p/ngisma, mais je trouve personnellement cette implémentation plus lourde qu'un bon $timeout!
J'attends vos avis sur la question.

Aller plus loin

Il est bien évidemment possible d'améliorer cette librairie en permettant d'effectuer une suite de combinaisons de touches (à la façon de la librairie jQuery MouseTrap).

On peut également penser à lever des évènements afin de rendre le service totalement autonome. Je vous conseille de lire un article de FrAngular qui vous aidera à bien appréhender le fonctionnement des évènements dans AngularJS.

L'idée de cette amélioration est de rendre indépendant ce service. Toutes les combinaisons (ou suites de combinaisons si vous en avez le temps :D) seraient alors initialisées dans une méthode init() de notre service.

Chaque raccourci clavier initialisé se verrait attribuer une étiquette unique qui sera diffusée à travers tous les scopes de notre application grâce à la méthode $broadcast sur le service AngularJS $rootScope (cf article sur les évènements).

On est maintenant libre de prendre en compte ou non ces raccourcis dans le contrôleur, et d'effectuer les actions appropriées au contrôleur courant.

Merci de votre lecture. N'hésitez pas à nous faire part de vos remarques ou interrogations si vous en avez... :-)

Bon dév'

Tableaux complexes avec AngularJS : ng-repeat et tbody

2013-01-11T11:21:00.000+01:00

[Ajout du 12/01/2013] J'ai modifié la solution proposée à la fin de l'article pour utiliser une directive ng-switch plutôt que ng-show, ce qui est beaucoup plus pertinent.

On m'a demandé plusieurs fois ce qui peut être compliqué à faire avec AngularJS. Il y a une chose qui parfois s'avère contraignante, surtout pour présenter des tableaux complexes, c'est le fait que les templates d'AngularJS doivent être du HTML, sinon forcément valide, du moins compris par le navigateur.

AngularJS compile le template à partir du DOM chargé par le navigateur. Il ne travaille pas sur le fichier source HTML, mais sur le DOM construit par le navigateur à partir du source, et ça fait une grosse différence. Ce fonctionnement est un des principaux atouts d'AngularJS, mais dans quelques rares cas, il peut s'avérer contraignant.

C'est le cas avec les tableaux HTML. Quand on a un tableau simple, avec un modèle de ligne répété en fonction des éléments d'une liste, il n'y a pas de difficulté. Mais imaginons un tableau un peu plus compliqué comme celui-ci, qui présente les navigateurs web utilisés par les visiteurs sur les premières semaines d'existence de FrAngular :

Browser	%
Chrome	68.83 %
Chrome 23.0.1271.97	46.68 %
Chrome 18.0.1025.166	10.97 %
Chrome 23.0.1271.101	10.66 %
Firefox	17.87 %
Firefox 17.0	70.24 %
Firefox 16.0	12.50 %
Safari	4.36 %
Safari 536.26.17	36.59 %
Safari 8536.25	36.59 %
Safari 7534.48.3	19.51 %

On a dans ce tableau deux niveaux de répétition :

un premier niveau sur le navigateur : Chrome, Firefox, Safari (je n'ai mis que les premiers de la liste, et IE était à 0.34%)
un second niveau sur les versions de ces navigateurs

La seconde répétition, sur la version, porte sur une seule ligne du tableau, il suffit de mettre un attribut ng-repeat sur le <tr> servant de template. Mais la première répétition, sur le navigateur, doit porter sur deux <tr> : le template de ligne concernant le navigateur, et le template de ligne indiquant la version qui est lui-même répété.

On pourrait avoir même avec un seul niveau de répétition des cas où l'on veut répéter plusieurs lignes ensemble. L'attribut ng-repeat doit être positionné sur un élément HTML, donc impossible de le mettre sur un <tr> dans ce cas, car une seule ligne serait répétée. On ne peut pas non plus intercaler un <div> dans la balise <table> pour regrouper les deux <tr>, ce n'est pas valide en HTML, et un tel <div> intermédiaire est ignoré par les navigateurs, ce qui fait qu'il n'existe pas dans le DOM du template que compile AngularJS. C'est là qu'on voit la différence entre un traitement fait sur le source du template, et un traitement fait sur le DOM que le navigateur a construit à partir du code source.

<tbody> à la rescousse

Heureusement il existe une balise HTML permettant de regrouper des <tr>, c'est la balise <tbody>, et par chance on a le droit de mettre plusieurs <tbody> dans une même table. Du coup c'est ce qu'on va utiliser avec AngularJS pour répéter plusieurs <tr> ensemble : on les regroupe dans un <tbody>, et on met l'attribut ng-repeat sur le <tbody>.

Vous avez un exemple ici sur jsFiddle, qui construit ce tableau des navigateurs, avec un premier niveau de répétition sur le <tbody>, et un second niveau de répétition sur un <tr> à l'intérieur de ce <tbody>.

<tbody ng-repeat="browser in browsers">
  <tr class="total">
    <td class="browser">{{browser.name}}</td>
    <td class="pct">{{browser.total}} %</td>
  </tr>
  <tr ng-repeat="version in browser.versions" class="detail">
    <td class="browser">{{browser.name}} {{version.name}}</td>
    <td class="pct">{{version.value}} %</td>
  </tr>
<tbody>

Cette solution simple fonctionne très bien si l'on a un seul niveau de répétition. Elle convient encore avec deux niveaux de répétition, à condition que le second niveau porte sur une seule ligne. Pour les cas rarissimes avec trois niveaux de répétitions ou plus, ou seulement deux niveaux mais où il faut répéter plusieurs lignes au second niveau, ça ne convient plus. Il n'est pas possible d'imbriquer des balises <tbody>, c'est interdit en HTML et ignoré par le navigateur, et donc un second <tbody> imbriqué dans notre fichier source n'existerait pas dans le DOM compilé par AngularJS.

Transformer les données

Il y a une solution plus générique, qui fonctionne dans tous les cas. C'est de transformer les données, pour en faire une liste correspondant exactement au tableau à afficher, avec un élément pour chaque <tr>.

En général on fait le data-binding d'une vue sur les données telles qu'elles ont été reçues du serveur. Mais dans des cas complexes où la structure des données n'est pas bien adaptée, il peut être plus pratique de transformer ces données dans le code du contrôleur (ou dans une fonction du scope si ce sont des données qui peuvent être modifiées), pour en faire un modèle plus simple à afficher.

Dans notre cas d'un tableau particulièrement exotique, il suffit de mettre à plat les différents niveaux de répétition, pour n'en avoir plus qu'un seul correspondant aux <tr> de la table HTML. La répétition se fait sur un unique <tbody> contenant plusieurs templates de <tr>.

[Ajout du 12/01/2013] J'avais proposé initialement d'utiliser des attributs ng-show pour conditionner l'affichage du template adéquat pour chaque occurrence (voir le jsFiddle ici). Mais l'attribut ng-show, tout comme son pendant ng-hide, masque simplement l'élément s'il ne doit pas être visible, via une propriété css display: none. L'élément est tout de même présent, même s'il est caché, ce qui signifie que chaque occurrence de <tbody> contient tous les templates de <tr>. Merci à ceux qui ont fait remarquer ce problème dans les commentaires. Si ça n'est pas prohibitif pour un petit tableau, avec un gros volume de données ça peut être un vrai problème, car du coup le DOM HTML est plus volumineux, et surtout ça multiplie le nombre de bindings à vérifier pour AngularJS.

Je pensais qu'il n'y avait pas de directive standard dans AngularJS permettant d'avoir réellement qu'un <tr> présent. Mais la nuit porte conseil, et ça m'a conduit à une solution bien meilleure, à laquelle je n'avais pas pensé sur le moment : il suffit d'utiliser les directives ng-switch et ng-switch-when, qui finalement sont faites exactement pour ça.

Dont voici la bonne solution (jsFiddle ici), où les templates de <tr> sont conditionnés selon la valeur de la propriété line.type. Avec un ng-switch sur l'élément <tbody> et un ng-switch-when sur chacun des <tr>, on obtient bien le résultat voulu, et sans <tr> cachés. Seul le <tr> correspondant à la valeur du ng-switch-when est présent dans chaque <tbody> :

<tbody ng-repeat="line in lines" ng-switch="line.type">
  <tr ng-switch-when="total" class="total">
    <td class="browser">{{line.name}}</td>
    <td class="pct">{{line.value}} %</td>
  </tr>
  <tr ng-switch-when="detail" class="detail">
    <td class="browser">{{line.name}}</td>
    <td class="pct">{{line.value}} %</td>
  </tr>
<tbody>

Sur ce principe on peut afficher n'importe quel tableau, aussi complexe soit-il.

Donc ce qu'il faut retenir, c'est que la balise <tbody> est très pratique pour regrouper des <tr> qui doivent être répétés ensemble, mais que dans les cas les plus complexes il ne faut pas hésiter à transformer les données pour se simplifier la vie.

AngularJS : Scopes et évènements

2013-01-07T18:00:00.000+01:00

Le scope d'AngularJS n'est pas très différent de la notion de scope du langage JavaScript, ce contexte qui pose parfois problème, lorsque le mot clé this ne pointe plus vers le bon contexte dans un callback. On utilise $scope ou $rootScope, en les injectant dans un contrôleur, pour faire référence respectivement au contexte local du contrôleur ou au contexte global de l'application.

Si les scopes d'AngularJS peuvent être créés manuellement, ils vont surtout être créés automatiquement par le framework lors de l'utilisation de certaines directives ou la déclaration d'un nouveau contrôleur. Ils sont reliés sous la forme d'un arbre hiérarchique avec héritage par prototype. Cette organisation en arbre peut être gênante lorsque l'on veut effectuer une communication directe entre des scopes qui ne sont pas reliés par une relation père/fils.

Comment faire passer des informations d'un scope à un autre quand il n'existe pas de relation directe entre eux?

Nous allons voir comment utiliser l'API des scopes fournie par AngularJS pour envoyer et intercepter des évènements personnalisés.

Le scope : KEZAKO!

Le scope est un objet JavaScript correspondant au contexte d’exécution d'une portion de la vue. Il référence à la fois des objets du modèle de données et des méthodes contextuelles.

Dans le cas d'un scope directement relié à un contrôleur (avec l'utilisation de la directive ngController), ce dernier permet d'assurer une persistance des données par son unicité et son partage entre le contrôleur et la portion de vue associée.

Les scopes sont comme je vous l'ai dit plus haut reliés de manière hiérarchique. AngularJS ayant pour vocation d'étendre et de renforcer le langage HTML, la structure d'organisation de ces scopes sous forme d'arbre ressemble très sensiblement à la structure HTML des vues de notre application.

Au sommet de l'arbre, il y a ce que l'on appelle le rootScope. AngularJS met à notre disposition un service $rootScope qui nous permet d'accéder d'injecter dans n'importe quel contrôleur de notre application le scope racine de notre arbre. Ce service $rootScope est un objet qui regroupe directement ou indirectement sous la forme d'un arbre tous les objets scopes initialisés dans notre application.

Une application va posséder plusieurs scopes. Ces derniers sont créés par l'utilisation de certaines directives (ngController, ngRepeat, etc...). A chaque création d'un scope, AngularJS utilise la méthode $new, ce qui a pour effet de créer un scope et de l'ajouter à la liste des enfants du scope père. La création de ce scope met en place la technique de l'héritage par prototype connu en Javascript. Il sera donc possible d'appeler une méthode du parent depuis le scope enfant.

Passons maintenant aux choses sérieuses!

Les évènements

Par ce système hiérarchisé de scopes, AngularJS nous donne la possibilité d'envoyer et d'intercepter des évènements personnalisés. Ces évènements sont caractérisés par deux choses.

Une étiquette qui devra être unique dans notre application pour éviter toute interférence,
Une liste d'arguments (cette liste peut être null ou compter un nombre indéfini d'argument).

AngularJS utilise par exemple ce système d'évènement pour la gestion des routes et de l'url (location) et utilise les étiquettes suivantes (liste non exhaustive) :

$routeChangeStart
$routeChangeSuccess
$routeChangeError
$routeUpdate
$locationChangeStart
$locationChangeSuccess

Je vais maintenant vous présenter les méthodes disponibles dans l'API que nous fournit l'objet scope d'AngularJS.

Emettre un évènement

Comme je vous l'ai dit précédemment, AngularJS nous donne la possibilité d'envoyer des messages à travers les différents scopes de notre application.

Nous avons deux méthodes qui nous permettent d'émettre un évènement: $emit (cf spec angularjs.org) et $broadcast (cf spec angularjs.org).

Méthode $emit

Cette méthode $emit disponible sur les objets de type scope, permet d'envoyer un message à toute la chaîne parente du scope émetteur. La propagation de cet évènement se fait donc de façon ascendante uniquement entre les scopes qui sont directement reliés entre eux.
La propagation de cet évènement peut être stoppée dès lors qu'il est intercepté en utilisant une des méthodes de l'API Event : stopPropagation() (nous verrons plus tard dans cet article comment écouter un évènement et accéder à l'objet Event associé).

Le schéma ci-dessous montre la propagation de l'évènement via la méthode $emit.

Méthode $broadcast

Cette méthode $broadcast est également disponible sur les objects de type scope. Elle permet, comme la méthode précédente, d'envoyer un évènement, mais cette fois, cet évènement ne peut être stoppé et est envoyé à travers tous l'arbre descendant des scopes instanciés dans notre application en partant du scope émetteur.

Le schéma ci-dessous montre la propagation de l'évènement via la méthode $broadcast.

L'envoi de l'évènement

Comme expliqué précédemment, les évènements dans AngularJS possèdent une étiquette ainsi qu'une liste optionnelle de paramètres.

Si par exemple vous voulez lever un évènement lorsque des données sont arrivées après un appel AJAX, il est possible de passer le résultat de l'appel en paramètre. On sera alors capable dans l'interception de cet évènement de manipuler le résultat de la requête.

Intercepter un évènement

L'interception d'un évènement sous AngularJS se fait via la méthode $on (cf spec angularjs.org). Cette méthode prend deux paramètres: une étiquette et une fonction qui sera exécutée.

La fonction permet de récupérer l'event courant (qui permet notamment de stopper la propagation, de récupérer les scopes sources, etc.) et les arguments passés lors de l'émission de l'évènement.

Un exemple concret

Pour illustrer un peu le fonctionnement de ces évènements, je vous propose un exemple sous jsFiddle. Il est également possible pour les développeurs un peu aventuriers et curieux de se glisser dans le code d'AngularJS et d'observer comment sont utilisés les évènements que j'ai cités dans le préambule du paragraphe "évènement".

Pour notre exemple, je vais créer un loader.
Le contrôleur et la vue s'occupent uniquement d'afficher la barre de chargement.
Le service Loader s'occupe du chargement et de l'envoi des évènements.

Voilà, j'espère avoir correctement expliqué le fonctionnement des évènements dans AngularJS.
N'hésitez pas à réagir de façon constructive pour faire avancer cet article et ce blog!

Bon dév'

Initialisations avant le routage avec la propriété resolve

2012-12-21T15:34:00.001+01:00

On peut avoir besoin dans une application AngularJS de faire des initialisations avant de charger une vue, et surtout avant que le framework instancie son contrôleur. Par exemple si on fait appel à une API nécessitant une authentification, et renvoyant un token pour les requêtes suivantes, on peut vouloir s'authentifier avant tout chargement de vue, pour être sûr d'avoir récupéré le token au préalable.

Comment faire en sorte que le routage d'AngularJS attende la récupération du token d'authentification, qui est bien sûr une opération asynchrone ? C'est ce que permet la propriété resolve du second paramètre de la méthode $routeProvider.when().

La syntaxe de $routeProvider.when() est la suivante :

$routeProvider.when('/view1', {
    controller:'View1Ctrl', 
    templateUrl:'view1.html', 
    resolve: {key1: 'Service1', key2: function2}
});

Cette propriété resolve doit être un objet JavaScript, donc une map clef/valeur, dont chaque propriété est soit une chaîne de caractères, soit une fonction. Dans le cas d'une chaîne de caractères, la valeur de la propriété est remplacée par le service publié sous ce nom-là. Si c'est une fonction, alors la fonction est exécutée, et la valeur de la propriété est remplacée par la valeur de retour de la fonction.

On obtient donc une map d'objets, après récupération des services ou exécution des fonctions indiquées. Parmi ces objets, il peut y avoir des promises. Vous trouverez toutes les explications sur les promises dans le précédent article : l'API Promise d'AngularJS.

S'il y a une ou plusieurs promises, alors AngularJS va attendre que toutes les promises soient résolues avant d'instancier le contrôleur et de changer la route. C'est donc ainsi qu'on va pouvoir attendre la fin d'une ou plusieurs opérations asynchrones, il suffit de passer les promises correspondant à ces opérations, et AngularJS fera le reste.

Faisons un premier exemple avec un service qui est une promise. Le jsFiddle complet est ici. Pour faire simple puisqu'il ne s'agit que d'un exemple, la factory du service utilise $timeout pour créer une promise qui sera résolue au bout de 3 secondes, et renvoie cette promise. C'est-à-dire que l'objet publié sous le nom de service 'WaitInit' est directement la promise renvoyée par $timeout :

app.factory('WaitInit', ['$timeout', function ($timeout) {
    return $timeout(function () {}, 3000);
}]);

Du coup dans la propriété resolve, on peut mettre directement le nom de ce service, et comme c'est une promise, AngularJS va attendre qu'elle soit résolue pour instancier le contrôleur et charger la vue :

$routeProvider.
    when('/', {
        controller:'View1Ctrl', 
        templateUrl:'view1.html', 
        resolve: { wait: 'WaitInit'}
    }).
    when('/view2', {
        controller:'View2Ctrl', 
        templateUrl:'view2.html', 
        resolve: { wait: 'WaitInit'}
    }).
    otherwise({redirectTo:'/'});

C'est ce qu'on constate à l'exécution, il y a un délai de 3 secondes avant que la première vue apparaisse. Ensuite lors des changements de vue il n'y a plus de délai, car le service est toujours la même promise, qui est déjà résolue. On peut donc ainsi, à la place du $timeout de l'exemple, faire les initialisations nécessaires à l'application et attendre qu'elles soient terminées avant d'afficher la première vue.

Voyons comme utiliser l'option des fonctions plutôt que des services, qui est plus générale. Voici un second jsFiddle avec des fonctions anonymes, dont le code est directement dans la propriété resolve, et qui renvoient simplement le service précédent :

        resolve: { func: ['WaitInit', function (WaitInit) {
            return WaitInit;
        }]}

Rien n'oblige bien sûr à utiliser une fonction anonyme, surtout si c'est la même fonction qui sert à toutes les vues, il est beaucoup plus logique de la définir une seule fois et de l'utiliser dans tous les resolve. Il faut juste faire attention à l'injection des dépendances, si la fonction a besoin d'utiliser des services. L'injection doit se faire dans la fonction elle-même. Il n'est pas possible d'injecter des services à la fonction passée comme paramètre de la méthode config(), qui n'accepte que des injections de providers.

Mais si on injecte directement les services à la fonction qu'on passe au resolve, il n'y a aucun problème, comme on peut le voir dans ce troisième jsFiddle :

app.config(function($routeProvider) {
    
  function wait(WaitInit) {
      return WaitInit;
  }
  wait.$inject = ['WaitInit'];
    
  $routeProvider.
    when('/', {
        controller:'View1Ctrl', 
        templateUrl:'view1.html', 
        resolve: { func: wait}
    }).
    when('/view2', {
        controller:'View2Ctrl', 
        templateUrl:'view2.html', 
        resolve: { func: wait}
    }).
    otherwise({redirectTo:'/'});
    
});

Voilà pour les différentes façons d'utiliser cette propriété resolve avec des promises, fournies comme des services ou des fonctions. Mais son usage ne s'arrête pas là, et on n'a pas vu à quoi servent les clefs de cette map clef/valeur.

Une fois que les objets de la map ont été récupérés soit depuis les services correspondants, soit en exécutant les fonctions, AngularJS attend que toutes les promises soient résolues, mais il remplace également chaque promise lorsqu'elle est résolue par son résultat, sa valeur de résolution. A ce stade-là, il ne reste plus aucune promise dans la map, et les valeurs de cette map sont disponibles pour l'injection dans le contrôleur de la vue, comme on injecte n'importe quel service, en utilisant la clef associée à chaque valeur.

On peut donc ainsi avoir un même contrôleur qui sert à plusieurs vues, mais avec des valeurs injectées différentes selon la vue. Rappelez-vous quand même que ce qu'on associe à chaque clef du resolve, c'est soit le nom d'un service, soit une fonction renvoyant une valeur ; on ne peut pas y mettre directement la valeur souhaitée, mais il suffit de faire une fonction renvoyant la valeur.

C'est ce qui est fait dans ce dernier jsFiddle, où il n'y a plus de promise, mais où l'on passe au même contrôleur une fonction renvoyant une valeur différente selon la vue :

$routeProvider.
    when('/', {
        controller:'ViewCtrl', 
        templateUrl:'view1.html', 
        resolve: { viewName: function () {
            return "V1";
        }}
    }).
    when('/view2', {
        controller:'ViewCtrl', 
        templateUrl:'view2.html', 
        resolve: { viewName: function () {
            return "V2";
        }}
    }).
    otherwise({redirectTo:'/'});

Et l'injection de viewName dans le contrôleur se fait de façon classique :

app.controller('ViewCtrl', ['$scope', 'viewName', function ($scope, viewName) {
    $scope.view = viewName;
}]);

J'ai utilisé une fonction dans l'exemple, mais pour implémenter quelque chose ressemblant au design pattern Strategy, où l'on passerait du code différent au même contrôleur en fonction de la vue, il est beaucoup plus propre d'écrire chaque stratégie sous la forme d'un service, et d'utiliser resolve avec le nom du service à injecter au contrôleur pour chacune des vues.

L'API Promise d'AngularJS

2012-12-15T19:47:00.001+01:00

Les services standards d'AngularJS $timeout et surtout $http renvoient tous deux des promises, qui sont très pratiques pour gérer des opérations asynchrones. Cette notion de promise existe dans d'autres frameworks, comme jQuery, et AngularJS intègre une implémentation de cette API. Elle peut être utilisée par les développeurs dans l'écriture des leurs propres services pour simplifier la gestion des actions asynchrones. C'est très important de bien comprendre comment fonctionne cette API, qui est probablement la partie la plus ardue d'AngularJS, pour tirer profit de toute la puissance du service $http, et pour gérer facilement les enchaînements d'opérations asynchrones dans une application.

Décrire en français le fonctionnement de l'API de promises ne va pas être simple, car il est difficile de traduire de façon élégante les notions qu'elle recouvre sans s'éloigner des termes anglais utilisés comme noms de méthodes. Donc tant pis pour l'élégance, je vais m'en tenir aux termes anglais ou à des traductions mot-à-mot, pour coller au plus près aux noms des méthodes disponibles.

Qu'est-ce qu'une promise ?

Une promise (une “promesse” en anglais) est un objet JavaScript correspondant au résultat différé d'une opération asynchrone.

Imaginons une fonction qui doit déclencher une opération prenant un certain temps, et qui pourra soit réussir et fournir un résultat, soit échouer et balancer une exception. Ça peut être une fonction synchrone, mais elle va devoir bloquer l'exécution jusqu'à ce que l'opération soit terminée, pour selon le cas renvoyer la valeur de retour ou balancer l'exception.

Dans un langage multi-thread on peut envisager éventuellement de bloquer ainsi l'exécution, pas en JavaScript. Du coup on va préférer un fonctionnement asynchrone : la fonction va juste démarre l'opération, et renvoyer immédiatement une promise, une promesse de résultat différé, qui sera résolue ultérieurement comme une valeur de retour ou comme une cause d'erreur, l'équivalent d'une exception.

Les promises ont une méthode then(), c'est même à ça qu'on les reconnaît. L'API spécifie, et c'est ce qui est fait dans AngularJS, qu'un objet est considéré comme une promise si et seulement si il a une méthode then(). Cette méthode then() prend deux fonctions comme paramètres, un successCallback et un errorCallback, et l'un ou l'autre sera appelé selon si la promise est résolue avec succès ou en erreur :

promise.then(function(greeting) {
    alert('Success: ' + greeting);
}, function(reason) {
    alert('Failed: ' + reason);
});

L'API des promises garantit que :

la méthode then() d'une promise prend deux callbacks en paramètres, tous deux optionnels ; le premier sera appelé si la promise est résolue avec succès, le second en cas d'erreur.
on peut enregistrer plusieurs paires de callbacks (succès et erreur), en appelant plusieurs fois la méthode then() d'une promise
si plusieurs paires de callbacks ont été enregistrées sur une même promise, la résolution de cette promise déclenchera une seule fois le callback adéquat de chacune des paires, et forcément dans l'ordre où les paires de callbacks ont été enregistrées
on peut appeler la méthode then() d'une promise déjà résolue, dans ce cas le callback adéquat sera appelé immédiatement - mais jamais avant la fin de la méthode then()
une promise ne peut être résolue qu'une seule fois, donc tous les callbacks verront le même résultat, ou la même erreur
la méthode then() renvoie une nouvelle promise, qui représente le résultat différé du callback appelé
les promises peuvent être utilisées dans les vues AngularJS comme des données différées, qui seront automatiquement prises en compte dans les bindings lors de la résolution de chaque promise

Tous les points sont importants dans cette liste. Mais un premier aspect fondamental de l'API des promises est indiqué dans le point 4 : on peut enregistrer un callback n'importe quand, sans se préoccuper de savoir si la promise est déjà résolue, autrement dit si l'opération asynchrone s'est déjà terminée ou est encore en cours d'exécution. Peu importe, on enregistre une paire de callbacks sur la promise, et on est sûr que le callback approprié sera appelé dès que possible.

Les points 6 et 7 ont de grosses conséquences, et nous allons les détailler.

Enchaînement de promises

Commençons par le point 6 : c'est ce qui permet de chaîner des promises. La méthode then() renvoie une seconde promise, dont l'opération asynchrone est le callback de la première promise. Si ce callback renvoie une valeur quelconque, la promise retournée par then() sera résolue dès la fin du callback. Mais, et là accrochez-vous au pinceau j'enlève l'échelle, le callback peut lui-même renvoyer une autre promise. Nous voilà avec trois promises dans l'histoire, on va prendre un exemple avec des noms de variables pour que ce soit compréhensible :

var promise2 = promise1.then(function () {
    ...
    return callbackPromise;
});

Dans cette exemple où la fonction callback renvoie une promise callbackPromise, la promise promise2 retournée par then() sera chaînée à callbackPromise, et résolue lorsque callbackPromise sera résolue. En pratique dans le code d'AngularJS, la promise retournée par then() est toujours chaînée à la valeur retour du callback, qui si ce n'est pas une promise est encapsulée dans une promise résolue en succès avec cette valeur-là.

Donc si le callback déclenche une opération asynchrone, il faut absolument qu'il renvoie une promise qui ne sera résolue que lorsque l'opération asynchrone sera complètement terminée. Si le callback ne renvoie rien, ou une valeur qui n'est pas une promise, l'enchaînement se fera trop tôt, sans attendre la fin de l'opération asynchrone. Il vaut mieux gérer correctement le retour du callback même s'il n'y a rien à enchaîner derrière, comme ça le jour où l'on aura besoin d'ajouter un enchaînement ça marchera directement. On évite ainsi de créer une cause d'erreur potentielle, sur laquelle on butera certainement un jour.

Revenons-en à cette seconde promise retournée par then(). On peut évidemment lui enregistrer un nouveau callback, ou une paire de callbacks, en appelant then() qui renvoie alors une troisième promise. Et ainsi de suite. On peut ainsi enchaîner très facilement sous la forme d'un code linéaire des opérations asynchrones, dont chacune ne démarrera qu'à la fin de la précédente, et seulement s'il n'y a eu aucune erreur dans toutes les opérations précédentes :

promise.then(step1)
       .then(step2)
       .then(step3)
       .then(step4)
       .then(null, function (error) {
           // Handle any error from step1 through step4
       });

Les quatre premiers appels à then() ne passent que le premier paramètre, le callback à appeler en cas de succès. Les deux paramètres de then() sont optionnels. Pour une promise qui sera résolue en erreur, si l'on appelle sa méthode then() sans second paramètre, alors ça ne déclenchera pas le callback d'erreur puisqu'il est absent, mais la nouvelle promise qui a été renvoyée par then() sera elle aussi résolue en erreur, avec la même cause d'erreur. Il faut voir ça comme une exception qui remonte dans la pile d'appel des fonctions, et voir le callback d'erreur comme un catch. Dans un tel enchaînement de promises sans traitement d'erreur, si une erreur survient, toutes les promises suivante vont zapper le callback de succès. Ici s'il y a une erreur dans la fonction step2, alors les fonctions step3 et step4 ne seront pas appelées, et seul le callback d'erreur qui est dans le dernier then() sera exécuté. Bien sûr s'il y avait eu un callback d'erreur avec la fonction step3, c'est celui-là qui aurait été exécuté, mais il est souvent pertinent de ne faire la gestion des erreurs que de façon globale à la fin de l'enchaînement.

Sans promises, si l'on veut faire la même chose directement avec des callbacks, pour un tel exemple on se retrouve avec 4 niveaux de callbacks imbriqués, et la gestion des erreurs à faire dans les 4 niveaux. Et si le nombre d'étapes est variable, il faudrait faire appel à de la récursivité, alors qu'avec des promises une simple boucle suffit. L'utilisation des promises permet de mettre le code à plat, presque comme s'il était synchrone, avec en plus la propagation des erreurs. C'est une très grosse simplification.

Car ce besoin d'enchaîner des opérations asynchrones, c'est quelque chose de très courant dans une application cliente JavaScript. Typiquement, quand on accède à une API web de type REST, on va régulièrement devoir enchaîner des requêtes HTTP, parce qu'une requête aura besoin d'une valeur retournée par une ou plusieurs requêtes précédentes. Autant dire que si l'on veut utiliser des API de type REST avec AngularJS, mieux vaut maîtriser les promises, pour ne pas se noyer dans de multiples niveaux de callbacks imbriqués.

Je disais que le callback d'erreur est l'équivalent d'un catch. L'analogie va plus loin, car le callback d'erreur s'il est au milieu d'un enchaînement, peut soit arriver à corriger l'erreur et permettre l'exécution normale des étapes suivantes, soit ne pas arriver à la corriger et balancer une nouvelle erreur, comme un throw ou rethrow. Car la promise renvoyée par la méthode then() sera chaînée de la même façon à la promise retournée par le callback, que ce soit le callback de succès ou le callback d'erreur qui ait été appelé. Si le callback d'erreur renvoie une promise résolue en erreur, ça veut dire que l'erreur persiste et n'a pas pu être corrigée, mais s'il renvoie autre chose, une valeur qui n'est pas une promise, ou une promise qui sera résolue en succès, ou même s'il ne renvoie rien, alors il n'y a plus d'erreur et la promise suivante de l'enchaînement sera résolue en succès. Et s'il survient une exception dans le callback et qu'elle n'est pas interceptée, alors la méthode then() l'intercepte et l'encapsule dans une promise résolue en erreur pour la suite de l'enchaînement.

Le promise manager : $q.defer()

J'ai parlé jusque là des promises et de la façon de les enchaîner, sans expliquer comment on peut créer une promise correspondant à une opération asynchrone.

C'est là qu'intervient le promise manager. On crée un promise manager en appelant la méthode defer() du service $q d'AngularJS. Ce service tire son nom de la “Q Library” de Kris Kowal, dont est directement inspirée l'implémentation des promises dans AngularJS.

$q.defer() crée un promise manager, selon le terme employé dans la spécification de Kris Kowal. C'est un objet qui a une propriété promise contenant logiquement la promise associée, ainsi que deux méthodes :

resolve(value) qui sert à résoudre la promise associée, en lui fournissant la valeur de retour (le résultat de l'opération)
reject(reason) qui sert à résoudre en erreur la promise, en fournissant la raison de l'erreur

L'appel de la méthode reject() entraîne forcément un rejet de la promise, c'est-à-dire sa résolution en erreur.

Pour la méthode resolve() c'est plus compliqué. Si la valeur passée n'est pas une promise, alors la promise associée au promise manager est résolue en succès, avec cette valeur comme résultat. Mais si on passe une autre promise, appelons-là promise0, à la méthode resolve(), alors c'est seulement quand promise0 sera résolue que la promise associée au promise manager sera elle-aussi résolue de la même façon, en succès avec la même valeur si promise0 est résolue en succès, ou en erreur avec la même cause si promise0 est résolue en erreur. On retrouve ici le mécanisme qui sert à chaîner les promises.

En fait la méthode reject() n'est qu'un cas particulier de resolve() puisque ça revient à appeler resolve() en encapsulant la cause d'erreur dans une promise rejetée en erreur, c'est exactement ce qui est fait dans le code d'AngularJS (méthode reject() de l'objet renvoyé par $q.defer()) :

    reject: function(reason) {
        deferred.resolve(reject(reason));
    },

Une telle promise rejetée en erreur peut être créée directement grâce au service $q :

$q.reject(reason);

Prenons un exemple tout simple avec une opération différée via un setTimeout(). Il a l'avantage d'être simple, mais en pratique c'est quelque chose qu'on n'écrira jamais ainsi, car AngularJS fournit le service $timeout pour ça. Peu importe, c'est un exemple pour montrer le mécanisme, et pas un exemple de ce qu'il faut faire (le jsFiddle est ici) :

var AppCtrl = function($scope, $q) {
    var deferred = $q.defer();
    setTimeout(function() {
        $scope.$apply(function() {
            deferred.resolve("terminé !");
        });
    }, 3000);
    var promise = deferred.promise;

    promise.then(function(result) {
        $scope.result = result;
    });
}

Le contenu de la fonction différée par setTimeout() est encapsulé dans un $scope.$apply(), pour que le code soit exécuté dans le contexte d'AngularJS. C'est justement pour ne pas avoir à faire ça qu'on utilisera en pratique plutôt le service $timeout. Donc dans cet exemple, on crée un objet deferred, un manager de promise, et on attache un callback à la promise grâce à sa méthode then(). Quand le timeout de 3 secondes s'achève, le manager résout la promise, en succès avec comme valeur la chaîne "terminé !". Ce qui déclenche le callback enregistré avec then(), la valeur est mise dans le scope, et s'affiche dans la vue.

Le service $q fournit deux autres méthodes intéressantes. $q.when(value) encapsule la valeur passée en paramètre dans une promise. Ca permet de créer une promise déjà résolue en succès avec une certaine valeur, par exemple pour servir de point de départ pour l'enchaînement de plusieurs étapes :

var startPromise = $q.when(value);
startPromise.then(step1)
            .then(step2)
            .then(step3)
            .then(step4)
            .then(null, function (error) {
                // Handle any error from step1 through step4
            });

Si on passe à la méthode $q.when() un objet qui est déjà une promise, elle renvoie non pas la promise telle quelle, mais une nouvelle promise équivalente car elle est chaînée à celle passée en paramètre, donc qui sera résolue en même temps et de la même façon.

La dernière méthode, $q.all([promise1, promise2, promise3]), sert à créer une promise qui sera résolue lorsque toutes les promises du tableau passé en paramètre seront elles-mêmes résolues. S'il y a dans le tableau des valeurs qui ne sont pas des promises, chacune est encapsulée dans une promise déjà résolue en succès avec la valeur en question, comme le ferait la méthode $q.when(). Si toutes les promises du tableau sont résolues en succès, alors la promise renvoyé par $q.all() est résolue en succès, avec comme valeur résultat un tableau contenant les résultats de chacune des promises, dans le même ordre bien sûr. Si une promise du tableau passé à $q.all() est rejetée en échec, alors la promise renvoyée est elle aussi rejetée en échec, avec la même cause.

A quoi ça sert ? Tout simplement à créer un point de synchronisation, dans un enchaînement qui n'est plus simplement linéaire. On peut avoir une opération qui dépend du résultat de plusieurs autres opérations, lesquelles peuvent être simultanées. Avec $q.all(), on crée une promise qui sera résolue quand toutes les opérations simultanées seront terminées, et on y attache l'opération suivante, qui sera alors exécutée dès que possible mais forcément après tous ses prérequis. Ça peut être typiquement une requête HTTP à un service web, qui a besoin d'informations fournies par plusieurs requêtes préalables.

Les promises du service $http

Une requête HTTP étant clairement une opération asynchrone, c'est donc en toute logique que le service $http d'AngularJS renvoie une promise. Qu'on utilise directement la fonction $http() en lui passant des paramètres, où l'une des méthodes simplifiées $http.get(), $http.post(), etc., toutes renvoient une promise.

Il s'agit d'une vraie promise, donc avec une méthode then(), mais qui dispose aussi de deux méthodes supplémentaires, success() et error() :

$http({method: 'GET', url: '/someUrl'}).
    success(function(data, status, headers, config) {
        // this callback will be called asynchronously
        // when the response is available
    }).
    error(function(data, status, headers, config) {
        // called asynchronously if an error occurs
        // or server returns response with status
        // code outside of the [200,300[ interval
    });

On pourrait utiliser la méthode then() pour enregistrer les callbacks traitant le retour de la requête HTTP, suivant si c'est un succès ou une erreur. Mais les méthodes success() et error() sont un peu plus pratiques, car le callback qu'on leur passe reçoit directement quatre paramètres qui décomposent le contenu de la réponse HTTP, parsé si c'était du JSON, le statut HTTP, les headers et la configuration.

Tandis que si on utilise la méthode then(), le callback appelé recevra en paramètre un objet avec quatre propriétés : data, status, headers et config. Donc ce n'est qu'un petit raccourci, qui évite d'aller chercher dans les propriétés d'un unique objet paramètre.

Par contre là où ça diffère davantage, c'est au niveau des valeurs renvoyées. Alors que la méthode then() crée et renvoie une nouvelle promise chaînée au retour du callback, les méthodes success() et error() ne créent pas de nouvelle promise, et renvoient l'objet this sur lequel elles sont appelées, c'est-à-dire la promise créée par $http() ou $http.get() ou la forme utilisée quelle qu'elle soit.

C'est pour ça qu'on peut faire suivre les appels à success() et error(), dans l'ordre qu'on veut d'ailleurs. Mais c'est aussi pour ça que les méthodes success() et error(), contrairement à la méthode then(), ne permettent pas d'enchaîner des requêtes HTTP sous la forme d'un chaînage de promises.

Rien n'empêche de combiner ces deux types de méthodes, d'utiliser success() et éventuellement error() pour traiter le résultat de la requête, et la méthode then() de la même promise pour l'enchaînement de la requête suivante. Voyons ça au travers d'un exemple, qui consiste à enchaîner deux requêtes à l'API de Twitter - l'ancienne API en réalité, qui ne demandait pas d'être authentifié, c'est plus simple et pour l'instant elle marche encore. La première requête va cherche les derniers tweets contenant la chaîne de caractères "AngularJS". On ne garde que le tweet le plus récent, c'est-à-dire l'élément 0 du tableau reçu car ils sont triés par date décroissante, pour trouver son auteur. Et on fait une seconde requête qui récupère les derniers tweets de cet auteur-là. L'intérêt n'est pas flagrant, mais c'est juste pour montrer un enchaînement de requêtes, la seconde utilisant des données récupérées par la première.

On peut faire la première requête, puis la seconde à l'intérieur du callbalk passé à la méthode success() de la première. C'est ce qui est fait dans ce premier jsFiddle :

var deferred = $q.defer();

var url = 'http://search.twitter.com/search.json'
        + '?q=angularjs&rpp=100&include_entities=true&result_type=mixed'
        + '&callback=JSON_CALLBACK';
$http.jsonp(url).
    success(function(data, status) {
        var lastTweet = data.results[0];
        var user = {
            screenName: lastTweet.from_user,
            name: lastTweet.from_user_name,
            image: lastTweet.profile_image_url
        };
        var url = 'https://api.twitter.com/1/statuses/user_timeline.json'
                + '?screen_name='
                + encodeURIComponent(lastTweet.from_user)
                + '&callback=JSON_CALLBACK';
        $http.jsonp(url).
            success(function(data, status) {
                deferred.resolve({user: user, lastTweets: data});
            }).error(function(data, status) {
                deferred.reject(data);
            });
    }).
    error(function(data, status) {
        deferred.reject(data);
    });

return deferred.promise;

L'ensemble est dans un service qui renvoie une promise, créée en appelant $q.defer(). Ça marche, mais on voit bien qu'on a dans le code un niveau d'imbrication supplémentaire pour chaque nouvelle requête à enchaîner, et que la gestion des erreurs doit se faire à chaque requête. Si ce n'est pas critique ici parce qu'il y a seulement deux requêtes, il est difficilement envisageable d'écrire des enchaînements plus complexes de cette façon.

Mais si le code de ce premier exemple est imbriqué, c'est parce qu'on n'a pas utilisé les possibilités d'enchaînement des promises. L'objet renvoyé par $http.jsonp() est une promise, profitons-en.

Voici un second jsFiddle, où l'enchaînement se fait en appelant la méthode then() de la promise :

var url, user, lastTweets;
var promiseStart = $q.when('start');

var promise1 = promiseStart.then(function (value) {
    url = 'http://search.twitter.com/search.json'
        + '?q=angularjs&rpp=100&include_entities=true&result_type=mixed'
        + '&callback=JSON_CALLBACK';
    return $http.jsonp(url).
        success(function(data, status) {
            var lastTweet = data.results[0];
            user = {
                screenName: lastTweet.from_user,
                name: lastTweet.from_user_name,
                image: lastTweet.profile_image_url
            };
        });
});
    
var promise2 = promise1.then(function (value) {
    url = 'https://api.twitter.com/1/statuses/user_timeline.json'
        + '?screen_name='
        + encodeURIComponent(user.screenName)
        + '&callback=JSON_CALLBACK';
    return $http.jsonp(url).
        success(function(data, status) {
            lastTweets = data;
        });
});

var promiseEnd = promise2.then(function (value) {
    // Success of all the chained requests
    return {user: user, lastTweets: lastTweets};
}, function (reason) {
    // Error in any request
    return $q.reject(reason);
});

return promiseEnd;

Cette fois on a un code à plat, on pourrait enchaîner ainsi autant de requêtes qu'on veut sans aucune imbrication. On n'a pas besoin non plus de créer de promise manager avec $q.defer(). Il y a une première promise déjà résolue, promiseStart, qui est créé en appelant $q.when(). Ça n'est pas indispensable, c'est juste pour des raisons de symétrie du code, pour que toutes les étapes aient la même structure que je préfère mettre aussi la première étape dans un then(). Et chaque callback passé à then(), qui contient le code d'une étape, avec donc une requête HTTP, renvoie directement la promise de la requête HTTP. Ce qui fait que then() construit une promise suivante chaînée à celle de la requête HTTP, et qui sera donc résolue quand la réponse HTTP aura été reçue. Mais elle ne sera résolue qu'après exécution du callback enregistré par la méthode success(), car l'API des promises garantit que les callbacks seront appelés dans leur ordre d'enregistrement. Ici on voit bien que l'ordre est important, si le callback du then() suivant était appelé avant celui de success(), ça ne pourrait pas fonctionner. J'ai mis des logs dans le jsFiddle, pour que vous puissiez voir dans la console l'enchaînement des appels.

Tout à la fin, on construit une promise finale, promiseEnd, en appelant encore then() sur la promise de la dernière étape, avec un callback de succès qui renvoie la valeur à passer à promiseEnd s'il n'y a pas eu d'erreur, et un callback d'erreur qui peut traiter une erreur survenue sur n'importe laquelle des requêtes HTTP successives. Et c'est cette promiseEnd qui est renvoyée par le service, immédiatement et bien sûr non résolue, la résolution de ces différentes promises chaînées se fera en cascade à mesure de l'arrivée des réponses aux requêtes HTTP.

Utilisation des promises dans les vues AngularJS

En regardant ces deux exemples, vous avez peut-être remarqué que ce que le contrôleur met dans le scope de la vue, c'est directement la promise renvoyée par le service. Mais qu'elle est utilisée dans la vue comme s'il s'agissait des vraies données. Nous voilà à ce que j'ai indiqué dans la liste tout au début, en point 7 : on peut utiliser les promises comme des données différées dans les vues d'AngularJS.

Le moteur de template d'AngularJS reconnaît les promises, au travers du code suivant du framework :

if (v && v.then) {
    p = v;
    if (!('$$v' in v)) {
        p.$$v = undefined;
        p.then(function(val) { p.$$v = val; });
    }
    v = v.$$v;
}

Si l'objet concerné par un binding a une méthode then(), ce qui veut dire que c'est une promise, AngularJS appelle sa méthode then() pour lui attacher un callback qui, lorsque la promise sera résolue en succès, va lui attacher le résultat dans une propriété $$v. Et le binding se fait en réalité sur cette propriété $$v. C'est ce mécanisme tout simple qui fait qu'on peut utiliser une promise dans la vue pour n'importe quel binding, pour faire une répétition comme sur l'exemple précédent des tweets, avec des bindings eux-mêmes sur les éléments répétés. Ainsi on ne voit rien dans la vue tant que la promise n'est pas résolue, puisque la propriété $$v n'existe pas, et tout apparaît comme par magie lors de la résolution de la promise, puisque d'un coup $$v existe, avec toutes les données à afficher.

Ça marche très bien, et il n'y a même pas besoin de connaître le fonctionnement interne, tant qu'il s'agit de données à afficher dans une vue. Pour faire des modifications, ça marche beaucoup moins bien, la magie a ses limites. Si on met des champs de formulaire avec des directives ng-model pointant sur les données différées d'une promise, les valeurs saisies par l'utilisateur vont être enregistrées dans l'objet promise lui-même, et non dans le résultat $$v attaché par AngularJS. A la soumission du formulaire, on aura les valeurs initiales reçues par la promise dans $$v, et seulement les propriétés modifiées qui auront été recopiées dans la promise. Difficile de faire une mise à jour vers le serveur à partir ce ça. Du coup pour alimenter un formulaire, je déconseille de mettre directement la promise dans le scope. Mais pour de l'affichage ça ne pose aucun problème.

Voilà pour ce tour d'horizon assez complet des possibilités offertes par l'API de promises d'AngularJS, qu'il vaut mieux avoir bien comprises, en particulier si l'on veut écrire un client faisant de nombreux accès à des services HTTP. Ça demande un peu d'habitude pour penser en promises plutôt qu'en imbrications de callbacks, mais à l'usage ça permet de résoudre assez facilement des enchaînements complexes d'opérations asynchrones.

Pagination côté client avec une directive AngularJS

2012-12-12T11:53:00.003+01:00

Dans une application AngularJS, on peut avoir parfois une liste assez importante de données entièrement chargée côté client, et qu'on veut afficher de façon paginée. C'est facile à faire au moyen d'une directive, qui peut être réutilisée pour paginer n'importe quelle liste.

Ça ne veut pas dire qu'il faut systématiquement charger toutes les données et faire la pagination côté client, bien au contraire. Pour de gros volumes notamment, il est beaucoup plus logique de filtrer directement sur le serveur, dans la requête à la base de données, la partie de la liste qui doit être affichée sur la page. Donc n'allez pas répéter que je vous ai dit de toujours faire la pagination côté client. Mais pour les cas où c'est pertinent, voici comment on peut créer une directive réalisant la pagination.

Pour afficher une liste, on utilise la directive ngRepeat standard du framework ; on l'applique en ajoutant un attribut ng-repeat à une ligne de table, ou un élément <li> d'une liste.

Le paginateur qu'on va créer aura plusieurs rôles :

afficher la page courante, les boutons de navigation entre les pages
fournir dans le scope courant une fonction renvoyant les éléments de la page à afficher, à utiliser à la place de la liste complète dans l'attribut ng-repeat
permettre le choix entre plusieurs tailles de page

La directive 'paginator'

En voici le code source :

var paginator = angular.module('paginator', []);
paginator.directive('paginator', function () {
  var pageSizeLabel = "Page size";
  return {
    priority: 0,
    restrict: 'A',
    scope: {items: '&'},
    template: 
       '<button ng-disabled="isFirstPage()" ng-click="decPage()">&lt;</button>'
     + '{{paginator.currentPage+1}}/{{numberOfPages()}}'
     + '<button ng-disabled="isLastPage()" ng-click="incPage()">&gt;</button>'
     + '<span>' + pageSizeLabel + '</span>'
     + '<select ng-model="paginator.pageSize" ng-options="size for size in pageSizeList"></select>',
    replace: false,
    compile: function compile(tElement, tAttrs, transclude) {
      return {
        pre: function preLink(scope, iElement, iAttrs, controller) {
          scope.pageSizeList = [10, 20, 50, 100];
          scope.paginator = {
            pageSize: 10,
            currentPage: 0
          };

          scope.isFirstPage = function () {
            return scope.paginator.currentPage == 0;
          };
          scope.isLastPage = function () {
            return scope.paginator.currentPage 
                >= scope.items().length / scope.paginator.pageSize - 1;
          };
          scope.incPage = function () {
            if (!scope.isLastPage()) {
              scope.paginator.currentPage++;
            }
          };
          scope.decPage = function () {
            if (!scope.isFirstPage()) {
              scope.paginator.currentPage--;
            }
          };
          scope.firstPage = function () {
            scope.paginator.currentPage = 0;
          };
          scope.numberOfPages = function () {
            return Math.ceil(scope.items().length / scope.paginator.pageSize);
          };
          scope.$watch('paginator.pageSize', function(newValue, oldValue) { 
            if (newValue != oldValue) {
              scope.firstPage();
            } 
          });

          // ---- Functions available in parent scope -----

          scope.$parent.firstPage = function () {
            scope.firstPage();
          };
          // Function that returns the reduced items list, to use in ng-repeat
          scope.$parent.pageItems = function () {
            var start = scope.paginator.currentPage * scope.paginator.pageSize;
            var limit = scope.paginator.pageSize;
            return scope.items().slice(start, start + limit); 
          };
        },
        post: function postLink(scope, iElement, iAttrs, controller) {}
      };
    }
  };
});

Le template qui est en dur dans la directive peut être mis dans un fichier HTML séparé pour un peu plus de lisibilité, et chargé grâce à la propriété templateUrl, au prix d'une portabilité un peu moins pratique puisqu'on se retrouve avec deux fichiers au lieu d'un seul. Là ce n'est pas vraiment critique puisqu'il se limite à 5 lignes assez simples.

Comment on l'utilise

Vous avez ici un jsFiddle complet montrant l'utilisation de cette directive. Le principe est simple, il suffit d'ajouter la directive sous la forme d'un attribut paginator à l'élément HTML dans lequel doivent être générés les contrôles de navigation, comme ceci :

<span paginator items="numbers | filter:search"></span>

Le second attribut, items, correspond à la liste complète avant pagination, telle qu'on l'aurait spécifiée dans un ng-repeat, et elle peut être filtrée ou ordonnée sans problème. C'est cette liste fournie dans l'attribut items qui est la source pour le paginateur. En fait c'est exactement l'expression qui était utilisée comme liste dans l'attribut ng-repeat qui est déplacée ici.

Et le paginateur fournit dans le scope une fonction pageItems() renvoyant uniquement les éléments de la page courante. Du coup dans l'attribut ng-repeat, on boucle sur pageItems() directement, sans faire ici ni filtrage ni tri :

<tr ng-repeat="number in pageItems()">

Il n'y a rien de plus à faire pour mettre en place avec cette directive la pagination côté client. Enfin presque rien. Quand l'utilisateur tape quelque chose dans la zone de recherche, la liste d'origine filtrée n'est plus la même, du coup la page courante n'a plus de sens. Pour revenir à la première page dès qu'on modifie la recherche, on ajoute un $watch dans le contrôleur, qui utilise la fonction firstPage() publiée par la directive dans le scope :

$scope.$watch('search', function(newValue, oldValue) { 
    if (newValue != oldValue) {
        $scope.firstPage();
    } 
});

On pourrait bien sûr préférer que ce soit géré automatiquement dans la directive, ça serait plus simple. Mais il n'est pas possible de faire un $watch sur un tableau, ni sur un objet complexe. Un $watch n'est possible que sur un type simple, chaîne de caractères, nombre ou booléen. Du coup si l'on voulait dans la directive savoir quand la liste d'origine est modifiée, pour revenir à la première page, il faudrait faire un $watch sur un hashage du tableau, lequel hashage devrait être recalculé par AngularJS à chaque modification. C'est théoriquement possible, mais potentiellement très coûteux si le tableau est un peu gros. Donc il vaut mieux en terme de performances déclencher manuellement dans le contrôleur le retour à la première page si l'utilisateur change le filtrage, ou l'ordre de tri. D'une façon générale, faire un calcul complexe dans un $watch n'est jamais une bonne idée.

Comment ça marche

Regardons de plus près le code de la directive. C'est une directive qui ne peut être appliquée que comme un attribut HTML (restrict: 'A'). Le template fourni sert à générer toute une portion de HTML à l'intérieur de l'élément sur lequel est placé l'attribut paginator, c'est ce qu'indique le replace: false. Avec replace: true, l'élément lui-même aurait été remplacé par le template.

La propriété scope est la plus complexe. Le fait de mettre comme valeur un objet entre accolades crée un scope isolé pour la directive, pour que les propriétés et fonctions publiées dans le scope par la directive n'aient pas d'impact sur le scope extérieur lié à l'emplacement de l'élément HTML dans la vue. Le scope est dit isolé car il n'a pas pour prototype JavaScript son scope parent, ce qui évite les effets de bord indésirables. Mais son scope parent est tout de même accessible, en utilisant explicitement sa propriété $parent. C'est ce qui est utilisé à la fin du code de la directive, pour publier les deux fonctions firstPage() et pageItems() dans le scope parent, puisqu'elles sont destinées à être utilisées dans la vue et le contrôleur, donc en dehors de la directive :

scope.$parent.firstPage = function () {
    scope.firstPage();
};
// Function that returns the reduced items list, to use in ng-repeat
scope.$parent.pageItems = function () {
    var start = scope.paginator.currentPage * scope.paginator.pageSize;
    var limit = scope.paginator.pageSize;
    return scope.items().slice(start, start + limit); 
};

La propriété scope de la directive est égale à {items: '&'}. Ça a pour effet de publier dans le scope isolé une propriété items, et le signe & indique que sa valeur est obtenue en exécutant l'expression contenue dans l'attribut de même nom de l'élément HTML. On pourrait expliciter le nom de l'attribut si on voulait avoir un nom de propriété publié dans le scope isolé qui diffère de celui de l'attribut, par exemple {listItems: '&items'}, mais si rien n'est indiqué ça prend l'attribut de même nom. C'est donc cette seule indication scope: {items: '&'} qui crée un scope isolé et qui y publie la liste d'objets correspondant à l'expression qu'on a mise dans l'attribut items de l'élément HTML.

Il n'y a pas vraiment de subtilités dans le reste du code, c'est le même code qu'on écrirait dans un contrôleur correspondant à la portion de vue qui se trouve dans le template. On publie dans le scope diverses méthodes pour calculer le nombre de pages, passer à la page précédente ou suivante, savoir si on est sur la première ou la dernière page, etc. Le watch sert à revenir automatiquement à la première page lorsque l'utilisateur change la taille de la page.

Mise en cache de l'état de la pagination

La directive marche bien ainsi, mais on peut vouloir la perfectionner un peu. Car si l'on change de vue, puis on revient sur la vue contenant la liste paginée, on perd la taille de page ainsi que la page courante. Essayez dans le jsFiddle, j'ai mis une seconde vue vide juste pour montrer cet effet. Bon c'est normal, la page courante et la taille de page sont juste des propriétés du scope de la directive, qui est recréé à chaque fois qu'on revient sur la vue. Mais ce n'est pas très pratique : imaginons qu'on ouvre une vue de détails à partir d'un élément de la liste paginée, ça serait quand même mieux si en revenant sur la liste paginée on la retrouvait dans le même état.

On peut conserver l'état de la pagination dans un cache, en utilisant le service standard $cacheFactory d'AngularJS. En fait comme son nom l'indique ce service est une factory destinée à créer un service de cache en mémoire. Donc on peut ajouter un service à notre module contenant déjà la directive :

paginator.factory('PageStateCache', ['$cacheFactory', function ($cacheFactory) {
    return $cacheFactory('PageStateCache');
}]);

Ce service PageStateCache est alors utilisé dans la directive pour conserver en cache l'état de la pagination, et pour le retrouver dans le cache s'il y a été sauvegardé.

Voici ce que ça donne (avec un nouveau jsFiddle complet ici) :

compile: function compile(tElement, tAttrs, transclude) {
  var cacheId = tAttrs.cache ? tAttrs.cache + '.paginator' : '';
  return {
    pre: function preLink(scope, iElement, iAttrs, controller) {
      scope.pageSizeList = [10, 20, 50, 100];
      var defaultSettings = {
        pageSize: 10,
        currentPage: 0
      };
      scope.paginator = cacheId 
          ? PageStateCache.get(cacheId) || defaultSettings 
          : defaultSettings;
      if (cacheId) {
        PageStateCache.put(cacheId, scope.paginator)
      }

Un identifiant est construit à partir d'une chaîne de caractères spécifiée dans l'attribut cache du même élément HTML, afin qu'il n'y ait pas de collisions entre les caches de différentes listes paginées. Cet identifiant est utilisé pour stocker dans le cache l'objet scope.paginator, et pour le retrouver dans le cache quand on arrive sur la page. Du coup les valeurs par défaut en dur ne sont plus utilisées que lorsqu'on ne trouve rien dans le cache, c'est-à-dire lors du premier affichage de la liste paginée.

Et dans la vue, il y a simplement cet attribut cache supplémentaire pour former un identifiant unique pour cette liste paginée :

<span paginator items="numbers | filter:search" cache="numbers"></span>

Vous pouvez essayer maintenant dans le jsFiddle de changer de vue, cette fois quand on revient sur la vue contenant la liste paginée, on la retrouve bien dans l'état où elle était.

Voilà, vous savez maintenant comment faire facilement de la pagination côté client avec AngularJS.

Décoration de services AngularJS

2012-12-11T20:35:00.000+01:00

C'est bientôt Noël, mais il ne s'agit pas d'accrocher des guirlandes aux services d'une application AngularJS. Cherchez plutôt du côté du design pattern Decorator.

Pour compléter l'article précédent sur les différentes façons de créer un service, il existe aussi une technique dans AngularJS pour modifier un service existant lors de son instanciation, ou pour substituer à l'instance du service un objet différent mais similaire.

Cette fois ce n'est pas via une méthode de l'objet module. La méthode decorator() à utiliser se trouve dans le service standard $provide, qu'il faut bien sûr injecter. On peut appeler cette méthode dans la méthode config du module principal de l'application, ou d'un autre module.

Elle ne crée pas un nouveau service, elle permet de modifier ou remplacer un service déjà référencé. Il faut donc pour pouvoir appeler cette méthode $provide.decorator(name, decorator), avoir créé avant un service qui a précisément ce nom-là. Plus précisément, AngularJS va modifier la méthode $get du provider enregistré sous le nom passé comme premier paramètre suffixé par 'Provider', comme on le voit dans le code du framework :

function decorator(serviceName, decorFn) {
    var origProvider = providerInjector.get(serviceName + providerSuffix),
        orig$get = origProvider.$get;

    origProvider.$get = function() {
        var origInstance = instanceInjector.invoke(orig$get, origProvider);
        return instanceInjector.invoke(decorFn, null, {$delegate: origInstance});
    };
}

Ca veut dire que decorator() ne peut être appelé que si un service de ce nom là a déjà été créé dans un module par l'une de ses méthodes provider(), factory(), service() ou value(). Mais pas par la méthode constant() ! Si vous avez lu attentivement le post précédent, vous aurez retenu que la méthode constant() est la seule qui ne crée pas un vrai provider, car il n'a pas de méthode $get. La conséquence est que les services créés avec la méthode constant() ne peuvent pas être décorés.

Lors du premier accès au service, la fonction passée à decorator() se voit injecter comme un paramètre $delegate l'instance du service d'origine fraîchement créé par son provider d'origine. Elle peut soit la modifier, soit créer une nouvelle instance qui s'appuie sur l'ancienne. Et elle renvoie l'objet qui sera réellement publié comme instance du service, qu'il s'agisse de la même instance modifiée ou d'un nouvel objet.

Bien, mais à quoi ça sert ? Car on pourrait directement créer le service correspondant à ce qu'on veut... sauf si on n'a pas la main sur le service à modifier. Ça peut être un service standard du framework AngularJS, ou encore un service utilisé dans d'autres applications et dont on ne veut pas modifier le code source. L'usage est celui du design pattern Decorator, on va pouvoir dans la configuration d'une application faire un tour de passe-passe consistant à modifier le comportement d'un service sans que les autres services qui l'utilisent ne s'en rendent compte, et sans aucune modification du code source du service d'origine.

Voici un exemple de code - parfaitement inutile mais c'est juste pour montrer la syntaxe - où le service standard $log est remplacé par un log décoré (jsFiddle ici) :

var app = angular.module('app', []);
app.config(['$provide', function($provide) {
    $provide.decorator('$log', ['$delegate', function ($delegate) {
        return {
            error: function (text) { $delegate.error("***" + text + "***"); },
            info: function (text) { $delegate.info("***" + text + "***"); },
            log: function (text) { $delegate.info("***" + text + "***"); },
            warn: function (text) { $delegate.info("***" + text + "***"); },
        };
    }]);
}]);

function Ctrl($scope, $log) {
    $log.info('ok');
}