SPIP - Documentation technique : construction des pages
Nous avons vu dans le précédent article la nomenclature pour constituer notre documentation technique. Dans le présent article, nous allons voir comment améliorer un peu les choses.
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
Derniers commentaires
# Le 25 septembre à 12:01, par Teddy Payet
En réponse à : Un Nouveau Chapitre : Mon Admission dans un MBA en Intelligence Artificielle et Data Innovation
# Le 25 septembre à 11:20, par vY
En réponse à : Un Nouveau Chapitre : Mon Admission dans un MBA en Intelligence Artificielle et Data Innovation
# Le 21 juin à 13:49, par Teddy Payet
En réponse à : Home Assistant : Routine le matin avant l’école
# Le 21 juin à 10:47, par Teddy Payet
En réponse à : Ma domotique open source
# Le 16 juin à 17:15, par Eric
En réponse à : Ma domotique open source
# Le 7 mars à 09:43, par Jacques Pyrat
En réponse à : Un Nouveau Chapitre : Mon Admission dans un MBA en Intelligence Artificielle et Data Innovation