5.1 - Tri des résultats

Attention : Ce tutoriel est ancien, incomplet, et n'est pas mis à jour. Il ne contient pas toutes les nouveautés du système de template de Gecko 1.9 / Firefox 3.0 qui est largement simplifié et permet d'utiliser sqlite ou xml comme source de données. Aussi est-il préférable d'aller consulter la version anglaise sur developer.mozilla.org.

Le constructeur de contenu des gabarits utilise un composant séparé pour l'insertion des noeuds générés à l'intérieur du contenu des arbres. Il sert pour l'insertion des noeuds qui sont créés initialement ou lorsqu'un résultat devient disponible. Ce composant supplémentaire est appelé le service de tri. Il est chargé de déterminer où les noeuds doivent être insérés dans le document XUL. Comme ce composant est appelé 'service de tri', il sert également à trier les résultats générés. Puisqu'un graphe RDF ne spécifie pas d'ordre pour les résultats -- à moins que les items ne soient dans un Seq RDF -- le constructeur de gabarits traitera les résultats dans n'importe quel ordre. Vous avez dû constater dans les exemples que les résultats qui ne sont pas dans un Seq sont affichés sans ordre particulier.

Le service de tri sert à trier les résultats dans un ordre particulier, généralement croissant ou décroissant en fonction de la valeur d'un prédicat pointant en dehors du noeud résultat. Il supporte également un troisième tri, le tri naturel qui est celui par défaut. Ce dernier fait que les items apparaissent sans ordre déterminé dans l'ordre où ils sont ajoutés. Toutefois, si les résultats sont des items d'un Seq, ils apparaîtront dans le même ordre que dans le Seq. Par exemple, les photos sont listées dans le même ordre dans cet exemple qu'elles apparaissent dans le Seq de la source de données.

Cette méthode de tri d'un Seq fonctionne bien pour les conditions d'une règle simplifiée puisqu'il est évident que la valeur de départ ref fait directement référence à tous les résultats membres (ils sont juste ses fils), ou pour les règles de la syntaxe étendue qui suivent une forme similaire. Pour des règles plus complexes, ce tri naturel ne fonctionnera pas parce que le service de tri suppose que la ressource ref de départ est le conteneur et que les résultats finaux sont les fils. Dans ce cas, l'ordre naturel des résultats sera simplement l'ordre dans lequel le constructeur de gabarits va générer les résultats.

Pour les tris par ordre croissant ou décroissant, ce n'est pas important puisqu'ils ignoreront le caractère de conteneurs des résultats et trieront simplement selon une valeur, alphabétiquement ou numériquement en fonction du type des données.

Le service de tri s'applique seulement aux constructeurs de contenu. Les constructeurs d'arbres utilisent une méthode différente et plus simple de tri puisqu'il n'y a pas de contenu à insérer. Ils supportent les même trois types de tri, naturel, croissant ou décroissant. Pour ces deux derniers types de tri, le constructeur d'arbres trie selon la valeur d'une colonne. Par exemple, si les photos étaient affichées dans un arbre à deux colonnes montrant le titre et la description, vous pourriez trier soit par le titre, soit par la description. L'utilisateur peut modifier le tri d'une colonne et sa direction en cliquant sur l'en-tête de la colonne, mais vous pouvez aussi modifier ce tri par la programmation.

Tri des résultats d'un arbres

Nous examinerons en premier le tri avec les arbres qui sont les éléments les plus courants utilisant le tri des items. Avec l'utilisation d'un constructeur d'arbres, vous pouvez trier les résultats d'un arbre en colonne. Pour cela, placez un attribut sort sur un élément treecol faisant référence à la variable servant au tri de cette colonne.

<treecol id="name" label="Nom" sort="?name" flex="1"/>
<treecol id="date" label="Date" sort="?date" flex="1"/>

Dans cet exemple, la première colonne sera triée par la variable ?name et la seconde colonne par la variable ?date. Lorsque le tri est croissant, les lignes de l'arbre seront triées par ordre alphabétique. Lorsque le tri est décroissant, les lignes de l'arbre seront triées en sens inverse. Pour l'ordre naturel, les lignes seront triées selon l'ordre naturel de la source de données RDF. Une seule colonne effectue un tri à la fois. Si l'arbre est trié par nom, et que l'utilisateur clique sur l'en-tête de la colonne date, le tri sera modifié et appliqué sur la colonne date.

Il existe deux attributs supplémentaires utilisés pour le tri, et vous permettant de définir le sens du tri initial sur une colonne. Ces attributs sont modifiés quand l'utilisateur change le tri. L'attribut sortDirection peut être utilisé pour spécifier le sens du tri initial d'une colonne. Une seule colonne doit avoir cet attribut, car un arbre ne peut être trié que sur une seule colonne à la fois. La valeur peut être soit ascending, descending ou natural. Cette dernière valeur est celle par défaut quand l'attribut n'est pas spécifié. L'attribut sortActive peut être défini à true ou false et il spécifie sur quelle colonne de l'arbre s'applique le tri. Une seule colonne ne peut contenir cet attribut sortActive défini à true. L'arbre modifiera ces deux attributs automatiquement si nécessaire lorsque les en-têtes de colonnes sont cliqués ou que l'arbre soit trié d'une autre manière.

Si vous ne voulez pas permettre un tri sur certaines colonnes, il vous suffit de ne pas ajouter d'attributs sort. Précisez uniquement ces attributs sur les colonnes que vous permettez à l'utilisateur de trier.

Voici un exemple complet de tri sur un arbre.

L'attribut sort doit être défini avec la variable qui contient les valeurs de tri. Habituellement, il s'agit de la même variable qui est utilisée pour générer les libellés des cellules de cette colonne, mais ce n'est pas une obligation. Dans l'exemple, la seconde colonne réalise un tri par date, mais si utilisiez une variable différente telle que ?description, et en supposant qu'un binding la définisse, l'arbre pourrait être trié par les valeurs de la variable ?description pour chaque ligne. Dans la plupart des cas toutefois, vous utiliserez la même variable de tri que les valeurs des libellés. Il existe cependant une situation où l'affichage des libellés ne permet pas de générer un tri correct représentatif de leurs valeurs. Par exemple, la date du 15 Mai va apparaître après le 15 Août avec un tri purement alphabétique, mais elle apparaîtra avant avec un tri chronologique.

Une autre méthode de tri par dates consiste à utiliser la construction avec parseType="Date" dans la source de données. Cette forme marque un littéral comme étant une valeur date plutôt qu'une chaîne de caractères. Le constructeur va le reconnaître et va alors réaliser un tri chronologique. L'avantage est que les dates seront affichées en fonction de la langue de l'utilisateur (ce qui signifie que la date est formatée correctement dans la langue de l'utilisateur). Voici un exemple comment spécifier cette forme dans la source de données RDF/XML :

<rdf:RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:r="http://www.xulplanet.com/rdf/"
     xmlns:nc="http://home.netscape.com/NC-rdf#">
  <rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/palace.jpg">
    <r:date nc:parseType="Date">1125966767295<r:date>
  </rdf:Description>
</rdf:RDF>

Vous pouvez également spécifier parseType="Integer" pour les nombres afin de permettre un tri numérique. En combinant ces différents types pour différentes valeurs, vous pouvez ainsi trier alphabétiquement, numériquement ou par date.

Si vous utilisez la syntaxe de règles simplifiées, il n'y a pas de variables, donc vous devrez spécifier le prédicat en entier en incluant le préfixe rdf: dans l'attribut sort. Par exemple :

<treecol id="name" label="Nom" sort="rdf:http://purl.org/dc/elements/1.1/title" flex="1"/>

Notez que toute cette discussion autour du tri ne s'applique qu'aux constructeurs d'arbres.

Pour les autres éléments ou les arbres à contenu, un mécanisme de tri différent doit être employé et sera discuté par la suite.

Tri de contenu

Pour les constructeurs de contenu (les gabarits qui n'utilisent pas flags="dont-build-content"), le tri est effectué de manière différente. Au lieu de trier selon une variable générée pendant la génération du gabarit, le tri pour des constructeurs de contenu ne peut être effectué qu'en utilisant un triplet pointant en dehors de la variable membre. Il n'y a pas de connexion entre les variables générées et la ressource utilisée pour le tri, donc cette ressource n'a pas forcément à être utilisée dans le gabarit.

Vous devez spécifier la ressource utilisée pour le tri avec l'attribut sortResource sur l'élément racine, comme ceci :

<hbox datasources="template-guide-photos5.rdf"
      sortResource="http://purl.org/dc/elements/1.1/title"
      sortDirection="ascending"
      ref="http://www.xulplanet.com/rdf/myphotos">
  <template>
    <vbox class="box-padded" uri="rdf:*">
      <image src="rdf:*"/>
      <label value="rdf:http://purl.org/dc/elements/1.1/title"/>
    </vbox>
  </template>
</hbox>

Dans cet exemple, les items générés seront triés par leurs titres. L'attribut sortDirection précise la direction du tri et peut être défini à descending pour inverser le tri. L'attribut sortDirection fonctionne de manière similaire à celui du constructeur d'arbres. Avec un constructeur d'arbres, chaque colonne dispose de son propre tri grâce à l'attribut sort, et l'attribut sortActive sert à indiquer la colonne actuellement triée. Pour les autres contenus, il n'y a pas de colonnes et un seul tri est applicable, donc l'attribut sortActive n'est pas nécessaire.

Lorsque le constructeur de gabarits génère un résultat, le service de tri utilise la valeur du prédicat sortResource afin de déterminer à quel endroit le contenu généré pour l'affichage devra être inséré. Lorsque la source de données RDF change, et qu'un nouveau résultat est disponible, le service de tri insère le nouveau contenu au bon emplacement.

Contrairement aux arbres, vous pouvez réaliser un tri en utilisant une ressource secondaire grâce à l'attribut sortResource2 qui est utilisé de la même manière que l'attribut sortResource. Si les valeurs pour le prédicat de sortResource sont les mêmes pour deux résultats, le prédicat de sortResource2 est utilisé pour clarifier le classement. Vous ne pouvez avoir qu'une ressource secondaire, il n'y a pas d'attribut sortResource3.

Pour modifier le tri du contenu généré par un gabarit, vous pouvez soit modifier les attributs relatifs au tri et reconstruire le gabarit, ou pour les boîtes de liste et les menus, vous pouvez appeler la méthode sort du service de tri :

var listbox = document.getElementById("aListBox");
var sortService = Components.classes["@mozilla.org/xul/xul-sort-service;1"].
                    getService(Components.interfaces.nsIXULSortService);
sortService.sort(listbox, "http://purl.org/dc/elements/1.1/title", "descending");

Ce code va trier un élément listbox par ordre décroissant de titre. Les arguments de la méthode sort sont le noeud racine (la listbox), la ressource pour le tri et la direction du tri.