Présentation

Cette macro permet de parcourir une séquence d'objets Hash qui a été au préalable ordonnée par application d'un ou de plusieurs ordonnancements. Un ordonnancement est un processus qui consiste à transformer une séquence d'objets en séquence de groupes d'objets. Un groupe est un regroupement virtuel d'objets : le processus d'ordonnancement ne modifie pas la structure de la séquence ni la valeur des objets qui constituent cette séquence ; seul l'ordre des objets est modifié. A chaque groupe est associé une valeur (déduite des valeurs des objets le constituant), qui peut être utilisée comme étiquette lors de l'affichage de la séquence dans le document résultat.

Chaque groupe peut contenir un ou plusieurs objets de la séquence initiale, mais deux groupes distincts ne peuvent pas contenir le même objet. Après un ordonnancement, tous les objets appartiennent à un groupe.

L'ordonnancement peut se réaliser :

• en créant des groupes triés,
• en créant des groupes nommés définis par l'utilisateur (l'ordre des groupes entre eux n'est pas défini par un tri mais par l'utilisateur).

L'ordonnancement se base sur une clé (un nom d'attribut d'objet commun à tous les objets Hash de la séquence) et s'applique sur les valeurs de cet attribut. Il est possible d'exécuter sur une même séquence plusieurs ordonnancements différents (sur plusieurs attributs différents). Dans ce cas, chaque ordonnancement est appliqué dans l'ordre défini par l'utilisateur et est appliqué sur la séquence résultat de l'ordonnancement qui le précède.

La syntaxe d'appel de cette macro est la suivante :

<@hardisAdv.groupList seqToOrder orderingCriteria; aHashObjInSeq>
... ${ aHashObjInSeq.fooAttribute } ...
</@hardisAdv.groupList>

Avec :

• seqToOrder : séquence d'objets Hash à ordonner et à parcourir,
• orderingCriteria : objet Sequence définissant les ordonnancements à appliquer sur la séquence seqToOrder,
• aHashObjInSeq : variable de boucle dont le nom est défini par l'utilisateur et qui est mis à jour par la macro groupList à chaque itération de lecture des éléments de la séquence résultat. La valeur de cette variable est l'objet Hash lu,
• un contenu imbriqué (... ${ aHashObjInSeq.fooAttribute } ...). Une fois que la séquence est ordonnée, elle est parcourue du premier élément au dernier élément. Lors de ce parcours, la valeur de l'élément lu est stockée dans la variable de boucle aHashObjInSeq, et le contenu imbriqué de la macro (le texte compris entre la balise de début et de fin de macro) est exécuté. Lors de cette exécution, il est possible de savoir dans quel groupe appartient l'élément lu. Le contenu imbriqué est donc exécuté autant de fois qu'il y a d'éléments dans la séquence ordonnée. La macro ne produira aucun résultat dans le document de sortie si la séquence est vide.

Chaque ordonnancement se base sur la comparaison de valeurs : la macro groupList supporte les comparaisons de type Boolean, Number, String, Date, Time et Date-time.

↑ Haut de page

Clé d'ordonnancement

La clé correspond à un nom d'attribut d'objet Hash appartenant à la séquence. Il est possible (à l'instar de la fonction built-in Freemarker ?sort_by) d'adresser un attribut d'objet de premier niveau ou de Nième niveau :

Une clé doit représenter un attribut ayant un type supporté. Une clé de Nième niveau est définie en utilisant la notation "point", et représente le chemin d'accès à l'attribut depuis le premier niveau. Chaque niveau intermédiaire fait référence à un attribut qui doit être de type Hash.

↑ Haut de page

Groupes triés

Le processus de création des groupes triés se base sur :

• Le type de la clé. Il faut distinguer deux cas :
  • une clé de type String / Number ou
  • une clé de type Boolean / Date / Time / Date-time.
• L'ordre de tri. Il existe plusieurs ordres de tri possible :
  • ordre ascendant (ordre croissant),
  • ordre descendant (ordre décroissant),
  • ordre d'origine (ordre inchangé).
• Un critère d'appartenance. Pour chaque élément du groupe, ce critère doit être vérifié.

Clé de type String / Number

Le processus de création de groupes est le suivant :

1. Tri de la séquence suivant la clé et l'ordre de tri,
2. Parcours de la séquence pour assigner à chaque élément un groupe ayant le critère d'appartenance imposé "Tous les éléments ont la même valeur". La valeur d'un groupe est la valeur du (des) élément(s) le constituant.

Par exemple

Clé de type Boolean / Date / Time / Date-time

Le processus de création de groupes est le suivant :

1. Parcours de la séquence pour assigner à chaque élément un groupe ayant un critère d'appartenance choisi par l'utilisateur. La valeur du groupe dépend du critère.
2. Tri des groupes suivant la valeur de chaque groupe et l'ordre de tri. Le nouvel ordre des groupes définit la séquence résultat.

La nature du critère dépend du type de la clé. Chaque critère est décrit dans le tableau suivant :

Groupe nommé

Un groupe nommé permet de regrouper des valeurs suivant un ou plusieurs critères d'appartenance (multicritères). Contrairement à un groupe typé :

• Le groupe nommé peut être utilisé pour tous les types simples de la clé (Boolean / Date / Time / Date-time / Number / String).
• Le groupe nommé a un nom unique défini par l'utilisateur.
• Le groupe nommé a une valeur associée qui est un label défini par l'utilisateur (chaîne alphanumérique) : ce texte peut servir de "titre" lors de l'affichage de la séquence ordonnée.
• Le groupe nommé a un ordre qui est défini par l'utilisateur : l'ordonnancement d'une séquence par groupes nommés implique généralement la création de plusieurs groupes, et l'ordre des groupes entre eux est à la charge de l'utilisateur (pas de "tri" des groupes comme avec les groupes typés).
• Suivant la nature des critères définis par l'utilisateur, un élément peut n'appartenir à aucun groupe nommé. Dans ce cas, l'utilisateur peut choisir pour cet élément :
  • de ne pas le traiter : cet élément ne sera pas présent dans la séquence ordonnée et ne sera pas traité lors du parcours de cette séquence dans la macro groupList (donc non affiché),
  • de le placer dans un groupe nommé spécial, de nom "other". Ce groupe est toujours le dernier groupe des groupes nommés. L'élément sera traité comme les autres éléments lors du parcours de cette séquence dans la macro groupList,
  • de le placer dans un nouveau groupe qui contiendra seulement cet élément. Ce nouveau groupe est inséré en fin de liste des groupes nommés. L'élément sera traité comme les autres éléments lors du parcours de cette séquence dans la macro groupList.

La création des groupes nommés se fait en parcourant la séquence (utilisation de l'ordre naturel de parcours). Lors du parcours, chaque élément est testé pour savoir à quel groupe nommé il appartient : le premier groupe nommé (dans la liste des groupes nommés) ayant un critère de regroupement valide est choisi s'il existe. Sinon l'élément est traité comme spécifié par l'utilisateur (voir plus haut).

↑ Haut de page

Critère d'appartenance

Il dépend du type de la clé. Plusieurs critères peuvent être associés pour la définition d'un groupe nommé. Dans ce cas, pour qu'un élément appartienne à un groupe nommé, il suffit qu'un critère soit vérifié. Suivant la nature du critère, l'utilisateur doit fournir une ou plusieurs valeurs littérales du même type que la clé pour compléter la description du critère. Chaque critère est décrit dans le tableau suivant :

Information d'ordonnancements

Dans la macro groupList, l'information sur le ou les ordonnancements à appliquer est portée par le paramètre orderingCriteria. Il doit être de type Hash ou Sequence de Hash. Chaque objet Hash décrit un ordonnancement. Il doit avoir les attributs suivants :

• name : nom du groupe (chaîne alphanumérique). Il doit être unique et sert à référencer un groupe dans les macros groupHeader et groupFooter. Cet attribut est obligatoire,
• colName : nom de la clé en notation "point" (chaîne alphanumérique). Cet attribut est obligatoire,
• order : ordre de tri (chaîne alphanumérique). Les valeurs possibles sont :
  • "a" : ordre ascendant (ordre croissant),
  • "d" : ordre descendant (ordre décroissant),
  • "o" : ordre d'origine (ordre inchangé).
  • "s" : ordre spécifié.
    
    Les valeurs "a", "d" et "s" définissent un ordonnancement de type "groupes triés". La dernière valeur définit un ordonnancement de type "groupes nommés". Cet attribut est optionnel : sa valeur par défaut est "a".

• groupCriteria : (chaîne alphanumérique) définit le critère d'appartenance pour un ordonnancement de type "groupes triés" lorsque le type de colName est Boolean / Date / Time / Date-time. Sert aussi de critère lorsque l'ordonnancement est de type "groupes nommé"s et que le groupe nommé "other" a la propriété grouping à "ownGroups". Cet attribut est optionnel : sa valeur par défaut est "week" lorsque le type de colName est Date / Date-time; "second" lorsque le type de colName est Time et "everyChange" lorsque le type de colName est Boolean,
• namedGroups : groupe nommé ou séquence de groupes nommés (Hash ou Sequence de Hash). Cet attribut n'est pris en compte que si l'attribut "order" vaut "s". Chaque groupe nommé est un objet Hash ayant les attributs suivants :
  • name (chaîne alphanumérique) : nom du groupe nommé. Il doit être unique et sert à référencer un groupe nommé dans les macros groupHeader et groupFooter. Cet attribut est optionnel.
  • label : titre du groupe nommé (chaîne alphanumérique). Il peut être affiché dans les macros groupHeader et groupFooter. Cet attribut est optionnel.
  • criteria : critère(s) d'appartenance au groupe nommé (Hash ou Sequence de Hash). Cet attribut est obligatoire (un groupe nommé doit avoir au moins un critère d'appartenance). Chaque critère est un objet Hash ayant les attributs suivants :
    • name : nom du critère (chaîne alphanumérique). Cet attribut est obligatoire.
    • values : valeurs associées au critère pour calculer sa validité (Type de colName ou Sequence de type de ColName). Cet attribut est optionnel.
• otherGroup : définition des propriétés du groupe nommé "other" (Hash). Cet attribut est obligatoire si "order" vaut "s". Ce groupe nommé est un objet Hash ayant les attributs suivants :
  • grouping : type de regroupement (chaîne alphanumérique). Cet attribut est obligatoire. Les valeurs possibles sont :
    • "ignore" : les éléments de ce groupe ne sont pas traités par la macro,
    • "oneGroup" : les éléments font partie du même groupe "other",
    • "ownGroups" : chaque élément appartient à un groupe trié (ordre d'origine et critère d'appartenance par défaut en fonction du type de colName).
  • label : titre du groupe "other" (chaîne alphanumérique). Il peut être affiché dans les macros groupHeader et groupFooter. Cet attribut est optionnel.

<#macro groupList dataList sortingGroup>

Directive vide : Non

Paramètres

Par exemple

<#assign myData = [{"name": "Franck", "age": 19 },
	{"name": "Alice", "age": 22 },
	{"name": "Paul", "age": 15 } ] />
<#assign orderingCriteria = [{"name": "ascending_order_by_age", "colName": "age"},
	{"name": "descending_order_by_name", "colName": "name", "order": "d"} ] />
<@hardisAdv.groupList myData orderingCriteria ; aPerson>
	Hello ${aPerson.name}! You have ${aPerson.age} years old.
</@hardisAdv.groupList>

↑ Haut de page