Lien vers le tutoriel original : http://alignedleft.com/tutorials/d3/chaining-methods
Enchaîner les méthodes
Dernière mise à jour le 30 décembre 2012
D3 utilise une technique appelée syntaxe en chaîne, que vous avec peut-être déjà vu en jQuery. En “enchaînant” les méthodes avec des points, vous pouvez effectuer plusieurs actions en une seule ligne de code. Ça peut paraître simple et rapide, mais il est important de comprendre comment ça fonctionne, pour vous éviter, plus tard, des heures de maux de têtes à débugger.
Soit dit en passant, fonctions et méthodes sont justes deux mots différents qui expriment le même concept : un bout de code qui accepte un argument en entrée, effectue quelques actions, et retourne quelques données en sortie.
Retournons à notre première ligne de code en D3.
d3.select("body").append("p").text("New paragraph!");On diraît que c’est la pagaille, surtout si vous êtes nouveau en programmation. La première chose à savoir c’est que JavaScrîpt, comme HTML, ne s’intéresse pas aux espaces ni aux sauts de lignes, donc vous pouvez mettre chaque méthode sur sa propre ligne, pour plus de lisibilité :
d3.select("body")
.append("p")
.text("New paragraph!");Tout le monde à son propre style de programmation. Utilisez ce qui vous sied le mieux : indentations, sauts de ligne et espaces (tabulations ou espaces simples).
Un lien à la fois
Analysons chaque morceau de code.
d3 — Référence l’objet D3, pour que nous puissions accéder à ses méthodes.
.select(“body”) — Donnez à select() un sélecteur CSS en entrée, et elle (la méthode) vous retournera la référence du premier élément du DOM qui y correspond. (Utilisez selectAll() lorsque vous avez besoin de plus d’un élément.) Dans notre cas on veut juste l’élément body, donc une référence à cet élément est passée à la prochaine méthode dans notre chaîne.
.append(“p”) — append() crée l’élément DOM que vous indiquez et l’ajoute à la fin (mais bien à l’intérieur) de la sélection sur laquelle elle opère. Dans notre cas on veut créer un nouvel élément p dans notre élément body. On indique “p” en argument, mais cette méthode voit aussi la référence à l’élément body qui lui a été transmise par la chaîne depuis la méthode select(). Enfin, append(), à son tour, transmet la référence au nouvel élément qui vient juste d’être créé.
.text(“New paragraph!”) — text() prend une chaîne de caractères en argument et l’insère entre les balises ouvrantes et fermantes de la selection actuelle. Comme la méthode précédente a transmis une référence au nouvel élément p, ce code va juste insérer le nouveau texte entre <p> et </p>. (Dans le cas où il y aurait déjà du texte, il serait écrasé.)
; — L’indispensable (all-important) point-virgule indique la fin de cette ligne de code.
La transmission
Beaucoup de méthodes de D3, mais pas toutes, retournent une sélection (dans la réalité, une référence à une sélection), ce qui permet d’utiliser l’enchaînement bien pratique de méthodes. D’une manière générale, une méthode retourne la référence à l’élément sur lequel elle vient d’agir, mais ce n’est pas systématique.
Rappelez-vous : Lorque vous enchaînez des méthodes, l’ordre est important. Le type du retour d’une méthode doit coincider avec le type d’entrée de la prochaine méthode dans la chaîne. Si la sortie et l’entrée ne correspondent pas, la transmission ressemblera à un bâton, dans une course de relais, qui tombe lors de l’échange.
Lorsque vous vous demandez ce que chaque fonction attend en entrée et retourne en sortie, la référence de l’API (en) est votre amie. Elle contient des informations détaillées sur chaque méthode, notamment si la méthode retourne une sélection ou non.
Sans les chaînes
On pourrait réécrire notre code d’exemple sans la syntaxe de chaîne comme suit :
var body = d3.select("body");
var p = body.append("p");
p.text("New paragraph!");Beurk ! Quel désordre ! Et pourtant, il y aura des moments où vous serez obligés de casser la chaîne. Par exemple, lorsque vous appellerez tellement de fonctions à la suite que ça n’aura pas de sens de les lier. Ou simplement parceque vous voudrez organiser votre code de manière à ce qu’il soit plus lisible.