Les overlays

L'idée de base, c'est qu'un article - blog, wiki, ou autre - a toujours un nombre fixe de champs de saisie associés. Dans YACS, c'est le titre, l'introduction, la description, et quelques champs annexes.
Or en pratique, on a souvent besoin de conserver cette structure de base, mais en la complétant avec quelques champs. C'est là que l'overlay intervient.
YACS fournit en standard un champ générique pour chaque article, dans lequel il peut ranger plusieurs informations si besoin.
Pour ranger les données additionnelles, ou pour les retrouver, il appelle des fonctions bien précises décrites dans le script overlays/overlay.php.
Par défaut, ce script ne fait pas grand-chose, mais il sert de structure de base pour d'autres scripts plus évolués.

[title]Ecrire un overlay[/title] Pour écrire un nouvel overlay, il faut créer un script qui surcharge les fonctions de overlays/overlay.php, en leur faisant faire quelque chose "pour de vrai".
Prenons un premier exemple classique, celui des recettes de cuisine, avec l'overlay overlays/recipe.php.
Ce script rajoute quelques champs à la saisie d'un article standard, pour noter séparément des informations importantes, comme le nombre de convives, la durée de cuisson, la liste des ingrédients.
Ces champs apparaissent lors de la saisie d'une nouvelle recette lorsque YACS appelle la fonction get_fields(), qui permet à l'overlay d'ajouter de nouveaux champs de saisie à la page. Après la saisie, lorsque l'usager clique sur le bouton d'envoi, les données sont transmises à YACS, qui appelle alors la fonction parse_fields() pour que l'overlay puisse extraire de ce flot les données qui l'intéresse.
La nouvelle version de la recette, y compris les données spécifiques de l'overlay, est ensuite rangée dans la base de données.
[title]Stockage des données[/title]

YACS "plie" ces données (les informaticiens parlent de "sérialisation") pour les faire entrer, toutes ensemble, dans le champ prévu à cet effet dans la table des articles : le champ "overlay"

A ce stade de l'exposé, et en écrivant deux fonctions simples, nous avons pu modifier le formulaire de saisie d'article et ranger les données "en plus" dans la base de données.
[title]Restitution[/title]

Pour restituer ces données à l'écran, YACS appelle la fonction de l'overlay get_text(), en précisant le contexte d'affichage des données. Par exemple, dans le panneau d'affichage principal d'un article, yacs appelera get_text('view'), alors que pour l'intégration dans une liste d'articles il appelera get_text('list'). Ainsi, l'overlay a le moyen de générer plus ou moins de texte, en fonction de la place dont il dispose à l'écran.
Dans la page d'affichage d'une recette, vous noterez que le champ de description habituel est intitulé 'Etapes de préparation'. C'est parce que yacs utilise la fonction get_label() pour permettre à l'overlay de personnaliser certains libellés de la page générée. Important dans certains cas, moins dans d'autres. Et puis il y a aussi la possibilité d'intervenir sur le titre d'une page dans une liste ou ailleurs, avec la fonction get_live_title(). C'est par ce biais que l'overlay overlays/issue.php ajoute une information d'état sur l'avancement des problèmes (en cours, résolu, etc.) sans modification du titre initial.
Avec ces trois fonctions supplémentaires on gère plus ou moins le rendu visuel des données spécifiques à l'overlay.

[title]lier l'overlay à une table séparée de la base de données.[/title]

Queques exemples fournis en standard sont overlays/day.php et overlays/contact.php. Le premier sert à construire des calendriers, et le deuxième à gérer un annuaire de contacts. Dans les deux cas, la mécanique est la même. Lorsque yacs intervient sur une page, il appelle la fonction de l'overlay remember() pour lui signaler l'opération en cours. Lors de la création de la page, c'est remember('insert') qui est utilisé. Lors d'une modification, l'appel est remember('update') et, très logiquement, remember('delete') lors d'une suppression de page. Pour synchroniser une ou plusieurs tables de la base de données avec un overlay, il faut lancer les directives "qui vont bien" dans la fonction remember(). Les commandes SQL typiques sont INSERT pour créer un enregistrement sur remember('insert'), UPDATE pour modifier un enregistrement sur remember('update'), et DELETE pour supprimer un enregistrement sur remember('delete'). Dans yacs, même le choix des noms est simple... Pour reprendre l'exemple de overlays/day.php, les mises à jour portent sur la table yacs_dates, qui contient un enregistrement par événement géré.
Et pour overlays/contact.php, c'est la table yacs_contacts qui contient les données spécifiques à l'annuaire des contacts. Notez que dans ce dernier cas, les informations rangées dans la table sont un mélange des données spécifiques à l'overlay, et de celles de l'article initial. En effet, le titre de page est le nom du contact, et il est inutile de prévoir un champ séparé pour le saisir.

Un problème classique de ce genre d'approche est la liaison entre les tables. Si je crée l'enregistrement numéro 123 dans la table des articles, comment retrouver l'identifiant de l'enregistrement dans la table des dates ? Et réciproquement, comment, à partir d'un enregistrement de la table des dates, retrouver l'article d'origine ?

La solution considérée avec YACS est simplissime, et s'appuie sur le fait qu'un article a un identifiant unique, et qu'un overlay est toujours lié à un seul article.
Donc, l'identifiant de la date associée à l'article numéro 123, c'est ... 123 aussi !

C'est un choix de programmation qui m'a sauvé pas mal de temps, mais bon, on peut faire plus compliqué aussi, s'il y a besoin. Par exemple, si un overlay est lié à plusieurs tables en même temps, ou à plusieurs enregistrements d'une même table.Une facture avec ses lignes de détail, typiquement...
[title]Maintenance[/title]

La création et la maintenance des tables additionnelles peuvent aussi être incluses dans l'overlay. Regarder la fonction setup() à la fin de overlays/contact.php pour la définition de la table.
Pour que yacs appelle la fonction setup() pour un overlay non-standard, il faut ajouter une extension ("hook" en anglais) à l'événement control/setup.php, sur le modèle fourni dans agents/browsers_hook.php par exemple. Le cas échéant, le script d'extension (dont le nom se termine par _hook.php) ne sera pas placé dans le répertoire overlays, mais dans un sous-répertoire portant le même nom que l'overlay associé.

Lors de la création ou de la modification d'une page, yacs appelle la fonction get_id() de l'overlay pour obtenir une chaîne de caractères. Voir un exemple dans overlays/day.php. Cette information est sauvée avec les autres attributs de la page dans la table des articles. Le champ correspondant est indexé, donc permet des recherches ou des tris par SQL. Ce champ est appelé overlay_id dans la table yacs_articles.

[title]Design[/title]

Sur le plan du rendu visuel, l'overlay est libre de générer le HTML qu'il souhaite à l'endroit qui lui a été assigné, et donc le web designer peut gérer le CSS associé comme il l'entend. Ou alors, ré-utiliser la librairie fournie avec YACS pour se simplifier la vie. En termes de design, pour gérer un document de type facture, il faut deux tables en plus dans la base de données, l'une pour les en-têtes de document, et l'autre pour les lignes de détail. La fonction get_fields() devra fournir une interface de saisie pour l'ensemble. La fonction parse_fields() sauvera tout ça en mémoire. Et la fonction remember() mettra les tables à jour en fonction des saisies effectuées.
Du lourd quoi, quelques centaines de lignes de code dans un seul overlay au bas mot...