SPIP - Documentation technique : construction des pages

Rappel

Nous avons construis une page ?exec=vins_doc qui affichera sous forme de tableau notre documentation. La page peut être longue, très longue.
Les chaînes de langue étant construites (n’est ce pas ?), nous allons améliorer un peu l’affichage.

Amélioration

Il serait intéressant de mettre une table des matières sur cette page.

Pour cela, nous allons utiliser le zoning que nous offre les squelettes du back office de SPIP 3. Pour notre page ?exec=vins_doc, nous avons créé prive/squelettes/contenu/vins_doc.html ce qui sous-entend que nous nous sommes occupé de la zone de contenu de notre page. La structure du BO de SPIP fournit une zone d’extra et une autre de navigation.
La table des matières est un "extra" alors créons le fichier adéquate : prive/squelettes/extra/vins_doc.html
On reste sur le nom "vins_doc.html" selon la règle de SPIP.
Voici le code à y insérer :

#SET{tables, #LISTE{'vin','vins_producteur'}}
<B_tables>
[(#BOITE_OUVRIR{<:vins:sommaire:>})]
<BOUCLE_tables(DATA) {source table, #GET{tables}} {si #SESSION{webmestre}|=={oui}}>
#SET{spip_table,#VAL{'spip_'}|concat{#VALEUR,'s'}}
<B_info_table>
<BOUCLE_info_table(DATA) {source table, #EVAL{$GLOBALS['tables_principales'][#GET{spip_table}]}}{cle==field}>
<ul class="menu-liste menu-items">
<li class="menu-entree item"><a href="[#(#_tables:GET{spip_table}|attribut_html)]">[(#_tables:GET{spip_table}|replace{'spip_',''}|ucfirst)]</a>
	<B_label>
	<ul class="menu-liste menu-items">
	<BOUCLE_label(DATA) {source table, #VALEUR} {par cle}>
	<li class="menu-entree item"><a class="spip" href="[#(#_tables:GET{spip_table}|attribut_html)][_(#CLE|attribut_html)]">#CLE</a></li>
	</BOUCLE_label>
	</ul>
	</B_label>
</li>
</ul>
</BOUCLE_info_table>
</B_info_table>
</BOUCLE_tables>
[(#BOITE_FERMER)]
</B_tables>

Bien, une liste est construite mais elle ne servira à rien si nous ne nous occupons pas des identifiants du contenu.

Allons dans prive/squelettes/contenu/vins_doc.html
Recherchons <tr> et remplaçons le par <tr id="[(#_tables:VALEUR|attribut_html)][_(#CLE|attribut_html)]">
Nous aurons ainsi quelques choses comme <tr id="spip_vins_id_vin">
Ça, c’est cool. Mais il faut aussi faire la même chose pour le nom de la table.
Recherchons <caption> et remplaçons le par <caption id="[(#_tables:VALEUR|attribut_html)]">

Voilà ! C’est nettement mieux.

Et une version texte ?

Cette page en tableau est très pratique à la lecture mais on peut avoir le besoin de créer un fichier word avec du texte au kilomètre.
Nous avons la structure de code qu’il faut pour cela. On ne va pas réinventer la roue. Il suffit de renommer la structure html.

Nous n’allons pas perdre le code que nous avons déjà réalisé. Transformons-le en inclure et affichons conditionnellement le type d’affichage désiré.

Coupons-collons le code suivant de notre page contenu/vins_doc.html dans prive/squelettes/inclure/vins_doc_tableau.html

<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>

Transformons les #GET{prefixe} en #ENV{prefixe} et le #GET{tables} en #ENV{tables}
Dans contenu/vins_doc.html, faisons l’appel à l’inclure vins_doc_tableau.html :
<INCLURE{fond=prive/squelettes/inclure/vins_doc_tableau,tables=#GET{tables},prefixe=vins} />
Simple, non ?

Nous avions parlé d’un texte au kilomètre, alors créons sur le même modèle le fichier inclure/vins_doc_texte.html en dupliquant inclure/vins_doc_tableau.html et apportons-y quelques modifications.

Remplaçons <table> par <div class="table">
Remplaçons <caption> par un <h1> en gardant le id.
Le premier <td> devient un <h2> et nous lui appliquons aussi le id issu de <tr>
Supprimons les <tr> maintenant.
Le <td> de la définition mysql devient un <div class="mysql">
Le <td> de l’aide de saisie et de la documentation devient un <div class="texte">.
Devant #CLE de la boucle info_table, mettons [<strong>(#VAL{#ENV{prefixe}}|concat{':nom_du_champ'}|_T) :</strong> ].
Devant #VALEUR de la boucle info_table, mettons [<strong>(#VAL{#ENV{prefixe}}|concat{':definition_mysql'}|_T) :</strong> ].

Tout cela fait, on peut supprimer les lignes <thead>...</thead> qui ne sont plus nécessaires.
Normalement, nous ne rencontrons pas de difficultés particulières ici. Ce n’est que du code html. Notre inclure est prêt.

Revenons sur la page contenu/vins_doc.html pour y apporter quelques améliorations. Nous pourrions ajouter un autre inclure pour notre texte pour l’avoir sur la même page. Mais avoir la même information en doublon ne sert à rien. Alors nous allons faire un petit formulaire qui indiquera quel type d’affichage prendre en compte.
Voici le code :

	<form action="#SELF" method="GET">
	[(#SELF|parametre_url{affichage,''}|form_hidden)]
	<div class="groupe">
	<label for="champ_affichage"><:vins:affichage:></label>
	<select name="affichage" id="champ_affichage">
	<option value="tableau"[ (#ENV{affichage}|=={tableau}|oui)selected="selected"]>tableau</option>
	<option value="texte"[ (#ENV{affichage}|=={texte}|oui)selected="selected"]>texte</option>
	</select>
	</div>
	<input type="submit" value="OK" />
	</form>
 

A partir de là, nous modifions l’inclure dans contenu/vins_doc.html :
<INCLURE{fond=prive/squelettes/inclure/vins_doc_[(#ENV{affichage,tableau})],tables=#GET{tables},prefixe=vins} />

Avec ce code, SPIP ira chercher l’inclure « tableau » si nous n’avons pas dans l’url le paramètre affichage.

Et voilà, on peut changer l’affichage de notre documentation en 2 coups de cuillère à pot.

Conclusion

Avec cette méthode, il est simple de faire une documentation. Cela ne nous dispense pas de son écriture bien entendu. Mais cela permet d’avoir la documentation directement dans le plugin. Ces différents squelettes et chaînes de langue ne sont que du texte, ce qui ne va pas alourdir à outrance le poids des fichiers du plugin.
On peut même étoffer la documentation annexe avec des inclure pour des éléments qui ne sont pas issus des tables en elles-mêmes mais de fonctions, d’interface, etc.
Je n’ai plus qu’une dernière à vous dire : Bonne documentation ! :-P