SPIP - Documentation technique : nomenclature

Préambule

Malgré un titre "racoleur", cet article ne va pas traiter de la nomenclature d’écriture des fichiers de SPIP mais d’une nomenclature que j’ai mis en place personnellement.
Si vous désirez avoir des informations particulières sur la nomenclature de SPIP (ses API, etc.), je vous conseille quelques sites :
– Programmer avec SPIP ;
– Documentation du code de SPIP ;
– Autodoc de SPIP : une zone particulière de code.spip.net. Il est autoalimenté par le PHPDoc inséré dans le code source de SPIP.
– SPIP-Contrib ;
– L’annuaire des plugins de SPIP.

De plus, je ne traitera pas non plus de l’utilisation du plugin La Fabrique. Sa page de documentation est très complète.

Contexte

Pour l’expression de cette nomenclature, je prendrai pour ligne de conduite la création d’un objet "vins". Cela sera plus parlant. Je me réfèrerai, sauf mention contraire, toujours à cet objet éditorial.
Le but de cet article n’est pas la création d’un plugin mais la méthodologie pour une bonne nomination des fichiers et des chaines de langue associées.
De ce fait, nous partons de zéro pour arriver à la fin de ce cycle à la réalisation de l’affichage de la documentation technique.

Vif du sujet

La Fabrique crée les bons fichiers selon les API de SPIP. Au départ c’est un "clicodrome". Mais il ne nous dispense strictement pas de penser, au préalable, notre structure de données. On ne fonce pas tête baissée dans un projet.

Dans le formulaire "Ajouter un objet éditorial", nous pouvons rajouter tous les champs nécessaires :

• nom
• millésime
• id_producteur
• id_couleur
• id_appellation
• id_region
• etc.

Une des premières choses à laquelle je fais attention autant que possible est le respect de "id_objet". La Fabrique créera la table spip_vins (au pluriel) associé à mon objet "vin". De là, il crée un ID : id_vin (mon équivalent à "id_objet" cité en début de paragraphe.)
Surtout, ne modifions pas cela même si la Fabrique nous le permet. Vous comprendrez pourquoi un peu plus loin.

Ici, ce n’est pas tellement le nom et/ou le nombre de champs qui m’intéresse dans "ma" nomenclature. Le but de cette dernière est de générer semi-automatiquement une information technique sur la table et ses champs grâce aux fichiers de langue.

La Fabrique adopte donc la philosophie des API de SPIP. Lorsque nous respectons "id_vin" pour l’objet "vin", la Fabrique créera les fichiers :
– lang/vin_fr.php : toutes les langues liées à l’objet "vin" ;
– lang/vins_fr.php : toutes les chaînes liées au plugin ayant le préfixe "vins" ;
– lang/paquet-vins_fr.php : les chaînes de langues généralement utilisées dans paquet.xml.

Si nous n’avions pas utilisé "id_vin" mais par exemple "ref_vin", la Fabrique aurait créé le fichier lang/ref_vin_fr.php… ce qui ne nous aurait pas arrangé pour la suite. J’ai rencontré ce cas récemment.

Un objet, deux objets, etc.

Pour aller un peu plus loin, nous allons créer une table pour les producteurs de vins. Nous nommerons cette table spip_vins_producteurs, l’objet associé sera "vins_producteur". Laissez-le tel quel.
Lorsque nous serons dans l’espace privé de SPIP sur la fiche d’un producteur, nous aurons une URL de type ?exec=vins_producteur&id_vins_producteur=XX

Remarque

J’aurai pu créer la table spip_producteurs. Mais le soucis est que ce nom est trop générique et pourrait se télescoper avec une autre table qui n’a rien à voir avec notre plugin.

Vous aurez compris que l’ID du producteur est sous la forme "id_vins_producteur". La Fabrique a enlevé le "s" final à producteur.

Normalement, vous m’avez suivi sans trop de soucis jusqu’à maintenant sans pour autant savoir où je voulais en venir. Pas vrai ? ;-)
Alors, continuons :

Pour la chaîne de langue de l’objet "vins_producteur", la Fabrique va créer lang/vins_producteur_fr.php.
Ça ne vous rappelle rien ? Je vous aide un peu : lang/vin_fr.php… lang/objet_fr.php

C’est la règle d’écriture adoptée par la Fabrique.

Rappel

Dans mes précédents articles, je vous avez montré (grâce à b_b, denisb et kent1) comment reconstruire une chaîne de langue pour l’afficher sur notre page :
[(#VAL{#GET{prefixe}}|concat{':nom_du_champ'}|_T)]

On ne change pas une équipe qui gagne.

Créer les chaînes de langue

Nous allons utiliser cette même règle pour construire notre documentation technique. Une sorte de PHPdoc "linguistique" à la SPIP.

Remarque

Mon but dans cette nomenclature n’est pas de documenter des fonctions (au sens PHP) car il existe des méthodes robustes aujourd’hui. SPIP a adopté, sous l’impulsion de Marcimat, PHPDoc pour cette documentation.

Dans ma documentation technique, en fait, je désire afficher 4 choses dans un tableau :

• le nom du champ ;
• son label ;
• sa définition MySQL ;
• son aide à la saisie (explication) ;
• et sa documentation.

Pour cela, on va prendre l’habitude d’écrire nos chaînes de langue sous la forme :

• label_champ
• label_champ_explication
• label_champ_documentation
  La définition MySQL du champ est directement issu des variables globales de SPIP ce qui rend inutile de créer une chaîne de langue pour elle. Nous aurons alors 3 chaînes de langue par champ.

Donc, soit pour notre objet vin, nous aurons :

• label_id_vin
• label_id_vin_documentation
• label_id_vin_explication
• label_nom
• label_nom_documentation
• label_nom_explication
• label_millesime
• label_millesime_documentation
• label_millesime_explication
• etc.

Dans les fichiers de langues adéquates, nous devons y renseigner ce dont nous avons besoin.

Afficher le contenu sur la page de documentation

Bon, tout est prêt maintenant pour construire notre page, y compris le contenu. Nous devons maintenant créer un fichier "prive/squelettes/contenu/vins_doc.html". Voici le code à y insérer :

[(#SET{prefixe,'vins'})] <h1>[(#VAL{#GET{prefixe}}|concat{':documentation_technique'}|_T)]</h1> #SET{tables, #LISTE{'vin','vins_producteur'}} <B_tables> <BOUCLE_tables(DATA) {source table, #GET{tables}} {si #SESSION{webmestre}|=={oui}}> #SET{spip_table,#VAL{'spip_'}|concat{#VALEUR,'s'}} <B_info_table> <table> <BOUCLE_info_table(DATA) {source table, #EVAL{$GLOBALS['tables_principales'][#GET{spip_table}]}}{cle==field}> <caption>#_tables:GET{spip_table}</caption> <thead> <th>[(#VAL{#GET{prefixe}}|concat{':nom_du_champ'}|_T)]</th> <th>[(#VAL{#GET{prefixe}}|concat{':definition_mysql'}|_T)]</th> <th>[(#VAL{#GET{prefixe}}|concat{':label_label'}|_T)]</th> <th>[(#VAL{#GET{prefixe}}|concat{':documentation'}|_T)]</th> </thead> <B_label> <BOUCLE_label(DATA) {source table, #VALEUR}> <tr> <td><strong>#CLE</strong></td> <td><em>#VALEUR</em></td> <td>[(#VAL{#_tables:VALEUR}|concat{':label_',#CLE}|_T)]</td> <td>[<strong>[(#VAL{#GET{prefixe}}|concat{':aide_a_la_saisie'}|_T)]</strong><br/> (#VAL{#_tables:VALEUR}|concat{':label_',#CLE,'_explication'}|_T)<br/>] [<strong>[(#VAL{#GET{prefixe}}|concat{':documentation'}|_T)]</strong><br/> (#VAL{#_tables:VALEUR}|concat{':label_',#CLE,'_documentation''}|_T)]</td> </tr> </BOUCLE_label> </B_label> </BOUCLE_info_table> </table> </B_info_table> </BOUCLE_tables> </B_tables>

Ce code va construire le tableau comme prévu.
Sur cette page, on peut voir que parfois la chaîne de langue ne s’affiche pas. En tout cas, pas son contenu mais bel et bien la chaîne en elle même sans les underscores. Exemple : label id vin, label id vin documentation, label id vin explication.
La raison en est très simple : nous n’avons pas encore renseigné cette chaîne de langue.
Mais parfois, nous n’avons rien à dire de particulier sur un champ. Il parle de lui même. Alors l’astuce est de créer tout de même cette chaîne de langue dans le bon fichier et de mettre un espace blanc/vide, soit 'label_id_vin_documentation' => ' '.

Astuce

Pour ceux qui ont lu le code ci dessus, vous avez pu voir un [(#SET{prefixe,'vins'})]. En fait, ceci est pour nous simplifier la tâche si on désire mettre ce bout de code dans un autre plugin. Il nous suffira de mettre le préfixe de notre nouveau plugin ici pour que la chaîne de langue se construise.

Remarque

Denisb nous a rappelé l’existence depuis SPIP 3.0.13 d’une nouvelle écriture de construction d’une chaîne de langue. Vous pouvez voir son commentaire ici et ici.

La page étant construite, il nous faut maintenant compléter nos différentes chaînes de langue. Alors à vos claviers et rendez-vous dans mon prochain article.