Le principe d'un fichier de ré-écriture est relativement simple. À partir d'une table de hash perl (clef/valeur) on va fabriquer un tableau à deux colonnes. Dans la colonne de gauche les clefs, dans la colonne de droite la valeur. Le fichier de ré-écriture dit comment on écrit les clefs et les valeurs. Il peut aussi être utilisé pour faire des tableaux en deux dimensions, dans ce cas les clefs donnent les titres des colonnes, et les valeurs indiquent comment on doit mettre en forme les différentes informations de chaque ligne.
{tableau:Titre du tableau}
Une ligne entre accolade indique le début de la description d'un tableau donné. Ce qui est à gauche des deux points (tableau) donne le nom symbolique du tableau. Ce qui est à droite (Titre du tableau) donne le titre du tableau. Ce titre est utilisé par les fonctions de FDN::Web::Array si aucun titre n'est précisé en argument de la fonction correspondante.
[CLEF:Nom de la clef]
Une ligne entre crochets indique une nouvelle clef. À gauche des deux points le nom de la clef tel qu'il est dans les données en entrée. À droite le nom tel qu'il apparaît à l'affichage.
Les différentes informations sont présentées dans l'ordre dans lequel sont les clefs dans le fichier de configuration. C'est-à-dire que pour une tableau à deux colonnes, l'ordre des lignes est fixé par l'ordre des clefs dans le fichier de description; et que pour un tableau a deux dimensions l'ordre des colonnes est fixé comme ça.
Pour chaque clefs on trouve une entrée actions qui indique ce qu'il faut faire pour mettre en forme la valeur, puis une description de l'actions en question. Par exemple:
actions = regexp, divclass regexp = s/xx/YY/ divclass = chose
Les actions sont appliquées dans l'ordre sur la valeur. L'ordre est donc important. Si plusieurs actions sont du même type, on suffix leur nom par une valeur au choix, par exemple regexp-1 et regexp-2.
L'action text est la plus simple: elle remplace purement et simplement la valeur par le texte qui lui est associé. Peu intéressant.
L'action regexp applique une expression régulière à la valeur. Si l'expression régulière ne match pas (en particulier si elle est invalide) la valeur n'est pas modifée.
L'action regwrap est un raccourcis pour une expression régulière qui ne servirait qu'à ajouter quelque chose autour de la valeur. Par exemple regwrap = XX$1YY est équivalent à regexp = s/^(.*)$/XX$1YY/. Très pratique par exemple pour mettre en gras (regwrap = <b>$1</b>).
L'action linkto est un raccourcis pour faire un lien HTML. Par exemple avec linkto = machin.cgi?xxx=$1 ça affichera la valeur sans la modifier en en faisant un lien vers machin.cgi?xxxx=[LA_VALEUR]. C'est utilisé intensivement pour faire les liens à l'intérieur de l'application web.
L'action divclass ajoute une balise div d'une classe donnée autour de la valeur. Très pratique pour indiquer la mise en forme via des CSS.
L'action spanclass est similaire mais ajoute une balise span.
L'action enum permet de mettre en forme un type énuméré. On peut avoir plusieurs types enumérés pour une même énumération, mais ça relève de la perversion. Un exemple vaut mieux qu'une explication:
[PRIX_TVA:TVA] actions = enum enum = 196 => 19,60 % enum = 55 => 5,50 % enum = 0 => 0 % enum-default = N/A enum-null = N/A
L'entrée -default est prise si la valeur n'est aucune des valeurs prévues. L'entrée -null est prise si la valeur n'est pas définie (c'est le cas qu'on obtient pour une entrée NULL en base de données).
L'action code est la plus complexe du lot. C'est en particulier la seule qui permette d'utiliser plusieurs valeurs pour les combiner en une seule. Elle contient du code perl. Dans cette ligne de code, chacune des clefs sera remplacée par sa valeur, puis le code sera exécuté. Ce qu'il retourne sera utilisé comme valeur à afficher (ou à faire modifier par l'action suivante). On peut tout faire avec, mais il faut que le code soit sur une seule ligne. Il ne faut pas en abuser, c'est rarement lisible.
Un petit exemple qui ré-écrit la clef CLIENT_ID d'une table avec la clef CLIENT_NOM prise dans la table CLIENT:
[CLIENT_ID:Client]
actions = code
code = { my $cl = FDN::Adsl::Basic::client_par_id(CLIENT_ID); return '<a href="view-client.cgi?cid=CLIENT_ID&do=yes">'.$cl->{'CLIENT_NOM'}.'(CLIENT_ID) </a>'; }