Vocabulaire et Concepts
L’aide en ligne est composée d’entrées d’aide. Chaque entrée d’aide possède un titre, un texte ainsi qu’un identifiant (textuel), utilisé en particulier avec la balise #AIDER. Les entrées sont structurées en rubriques d’aide - sur un seul niveau - qui disposera également d’un identifiant textuel.
L’aide en ligne est décomposée en modules d’aide. Le core de SPIP ainsi que chaque plugin ou extension pourra ainsi déclarer le module d’aide lui correspondant. L’aide en ligne affichée sur un site SPIP correspondra donc à la fusion de ces différents modules d’aide.
Chaque module aura un identifiant textuel. Par commodité, cet identifiant sera le plus souvent équivalent au préfixe du plugin qui fournit ce module d’aide. L’identifiant du module d’aide du core de SPIP sera spip. Par ailleurs, les modules d’aide seront versionnés. Par simplicité, le numéro de version sera obligatoirement un nombre entier.
Les caractères autorisés pour les identifiants de modules, d’entrées et de rubriques seront, comme pour les préfixes de plugin, les lettres minuscules ou majuscules, les chiffres et le tiret bas.
Les différents modules d’aide seront fournis par des serveurs d’aide en ligne. Ces serveurs permettront de rédiger les modules d’aide et fourniront une interface pour la traduction de ces modules d’aide. Un serveur principal sera mis en place à l’adresse http://aide.spip.net, ce qui n’empêchera pas d’installer d’autres serveurs en ligne. Un plugin dédié nommé SAEL (Serveur d’Aide En Ligne) sera développé pour transformer facilement un site SPIP en serveur d’aide.
Du côté de SPIP, l’aide en ligne sera extraite du core pour devenir une extension. Cette extension fonctionnera donc comme un client vis-à-vis des serveurs d’aide. À partir de la liste des modules d’aide en ligne déclarés par les différents plugins et extensions installés sur un SPIP, elle téléchargera les modules d’aide en question à partir des serveurs d’aide correspondant, procédera à la fusion des modules d’aide et gérera l’affichage local de l’aide en ligne.
Les fichiers échangés entre le serveur et le client sont appelés fichiers d’aide.
Afin d’assurer l’unicité des identifiants des entrées d’aide, l’identifiant complet d’une entrée d’aide sera composé de l’identifiant de son module suivi d’une barre oblique et de l’identifiant de l’entrée d’aide (module/entree).
Déclaration des modules d’aide dans paquet.xml
La déclaration d’un module d’aide par un plugin/extension se fera dans le fichier paquet.xml via une nouvelle balise <aide /> qui accepte les attributs suivants :
- module (obligatoire) : identifiant du module d’aide à ajouter à l’aide en ligne
- version (facultatif) : numéro de version du module d’aide (1 si non précisée)
- serveur (facultatif) : serveur hébergeant le module d’aide (http://aide.spip.net si non précisé)
Format d’échange entre le serveur et le client
Mécanisme des requêtes
Le client a besoin que le serveur lui transmette, dans une langue donnée, deux types d’information :
- la structure de l’ensemble des modules hébergés par ce serveur d’aide,
- le contenu d’un module d’aide.
Lorsqu’un utilisateur demande à voir une entrée d’aide donnée, la structure résultant de l’ensemble des modules d’aide est nécessaires pour construire le menu de l’aide en ligne affichée dans la colonne de gauche, alors que seul le contenu du module concerné est nécessaire pour la colonne centrale. Ce découpage de l’information en deux fichiers (structure et contenu) vise donc à éviter de devoir télécharger d’un coup l’ensemble des contenus pour afficher une simple entrée.
L’URL de la structure des modules d’aide sera obtenue en ajoutant spip.php?page=sael-structure&lang=en à l’URL du serveur d’aide fournie dans paquet.xml. On pourra optionnellement passer la langue de référence du site dans l’URL via le paramètre lang_ref (voir la section Multilinguisme). La liste des modules sera transmise sous forme de tableau avec la paramètre module, par exemple &module[]=machin-1&module[]=truc-2 pour le module machin en version 1 et le module truc en version 2.
L’URL du contenu d’un module d’aide sera quant à elle de la forme http://url.serveur.aide/spip.php?page=sael-contenu&module=IdentifiantDuModule&version=1&lang=fr.
L’URL http://url.serveur.aide/spip.php?page=aide sera réservée quant à elle à l’affichage en ligne par le serveur d’aide des modules d’aide (ce lien pourra être utilisé par exemple par http://plugins.spip.net pour permettre une consultation de l’aide en ligne d’un plugin avant son installation).
Format d’échange
YAML, JSON ou XML ?
- JSON impose une compatibilité minimum PHP >= 5.2 pour la fonction json_decode (selon inc_version, SPIP 3 demande PHP>= 5.1).
- XML est plus verbeux, mais intégré à SPIP 3 et demande PHP >= 5.1 pour les itérateurs qui ont recours à SimpleXMLIterator.
Structure de l’aide
Ce fichier permet de transmettre au client la structure des entrées d’aide des modules gérés par le serveur. Plus précisément, il s’agit de la liste ordonnées des rubriques et des entrées d’aide, ainsi que leur titre dans la langue demandée.
Exemple en JSON :
Contenu d’un module
Ce fichier contiendra l’ensemble des entrées (identifiant, titre et texte) du module dans la langue demandée.
Multilinguisme
Il faut prendre en compte le fait que la traduction des différents modules d’aide en ligne suivra son propre rythme. Autrement dit, à un moment donné, il est possible que l’aide demandée par un utilisateur dans une langue donnée ne soit pas forcément disponible dans la langue désirée.
Si un utilisateur demande à voir une entrée d’aide dans une langue non disponible, le plus simple est de lui afficher un message du genre : Cette entrée d’aide n’est pas disponible en
Plus problématique est la gestion de la liste des entrées d’aides disponibles (colonne de gauche lorsque l’on consulte l’aide en ligne). Pour les entrées d’aide non traduites, on affichera alors leur nom préférentiellement dans la langue principale du site (transmise au serveur d’aide avec le paramètre lang_ref) et, à défaut, dans la langue de référence du module d’aide considéré.
Cette gestion du multilinguisme sera effectuée en amont par le serveur d’aide.
Extension Aide en ligne (client)
Appeler une entrée avec la balise #AIDER
L’affichage d’une icône d’aide sera comme actuellement réalisé par l’icône #AIDER à la différence que l’on renseignera l’identifiant complet de l’entrée d’aide, par exemple #AIDER{breves/brevesstatut}.
Pour faciliter la transition, si le nom du module n’est pas précisé, le module utilisé par défaut sera spip, c’est-à-dire l’aide du core.
Générer la liste des entrées
Lorsque l’on demande à afficher une entrée d’aide, le client va tout d’abord télécharger la structure des entrées, dans la langue demandée, d’aide à partir de chaque serveur d’aide afin de produire un tableau ordonné des rubriques et des entrées d’aide. Si les modules d’aide proviennent de plusieurs serveurs d’aide, le client complétera la structure téléchargée à partir du serveur principal (celui déclaré par le core) avec la structure renvoyée par les autres serveurs.
Le tableau final obtenu sera mis en cache dans un fichier PHP tmp/cache/aide-structure.php. Il ne sera recalculé qu’en cas de vidage du cache ou si le paramètre var_mode=recalcul est transmis dans l’URL.
Nota Bene : ce fichier de cache devrait également être supprimé en cas d’activation / désactivation / mise à jour de la liste des plugins. Il faut voir si dans SPIP 3 le cache est désactivé dans ce cas ou si un pipeline peut permettre d’intervenir à la mise à jour de la liste des plugins. Par ailleurs, on peut aussi prévoir un effacement et/ou un rechargement de ce fichier à intervalle régulier (une fois par semaine par exemple) par tâche CRON.
Afficher l’entrée d’aide
Pour le contenu de l’entrée d’aide demandée, le client téléchargera le fichier de contenu. Plus précisément, ce fichier pourra être traité directement avec les itérateurs et mis en cache avec le filtre |copie_locale ce qui évite d’avoir à développer un système de cache spécifique. La même fonction pourra aussi être utilisée pour mettre en cache les images incluses dans le texte des entrées d’aide.
Nota Bene : la fonction copie_locale permet de spécifier le nom du fichier local où stocker l’information. Dès lors, on peut donc utiliser copie_locale tout en stockant les fichiers téléchargés dans tmp/cache/aide.
Nota Bene : normalement avec le paramètre modif de copie_locale, il devrait être possible d’optimiser le cache en ne re-téléchargeant le contenu que s’il a été modifié sur le serveur. A vérifier s’il cela fonctionne correctement et si c’est optimal. On peut également envisager de supprimer le contenu de tmp/cache/aide de manière périodique par tâche CRON.
Plugin SAEL (serveur d’aide en ligne)
Le serveur va déclarer à SPIP trois nouveaux objets : les modules d’aide, les rubriques d’aide et les entrées d’aide.
Il offrira une interface pour la création / rédaction / traduction de ces nouveaux objets.
Il implémentera les squelettes aide.html, sael-contenu.html et sael-structure.html et les fonctions de traitement nécessaires.
Modules d’aide : table spip_aides :
- id_aide
- identifiant
- version
- lang_ref
- titre
- descriptif
- maj
Le titre et le descriptif seront à usage interne de SAEL uniquement.
Il faudra prévoir une table spip_aides_auteurs pour pouvoir ajouter des auteurs à un module (voir plus loin). Le champs lang_ref permettra d’indiquer la langue de référence du module, pour la gestion des traductions.
Rubriques d’aide : table spip_rubraides :
- id_rubraide
- identifiant
- titre
- lang
- rang
- maj
- lang_ref ?
Les rubriques d’aide seront partagées entre les différents modules d’aide. Se pose la question de la langue de référence d’une rubrique pour la gestion des traductions (afin d’identifier les traductions devant être mises à jour suite à une modification de la langue de référence). Pistes possibles :
- ne pas avoir de langue de référence pour les rubriques dans la mesure où leur intitulé ne changera que peu (mais risque d’incohérence des traductions).
- imposer une seule langue de référence pour les rubriques d’aide, auquel cas prendre la langue principale du site où est installé le serveur d’aide. C’est la règle la plus simple. Par contre cela impose aux rédacteurs d’un module d’aide de connaitre un minimum la langue de référence du serveur d’aide (soit le français pour http://aide.spip.net).
- considérer que la langue de référence d’une rubrique d’aide peut varier selon la rubrique (nécessite de stocker l’information quelque part, d’où un champ lang_ref), mais ça complexifie l’interface.
Entrées d’aide : table spip_entraides :
- id_entraide
- identifiant
- titre
- texte
- lang
- rang
- id_aide
- id_rubaide
- maj
Les documents joints seront activés sur les entrées d’aide, pour la gestion des images. La recherche interne et les révisions seront activées sur les trois nouveaux objets. Les forums de l’espace privé seront implémentés sur les modules.
Interface
L’interface de gestion des modules et des traductions s’inspirera en partie de la nouvelle interface de trad_lang en cours de développement afin d’avoir des repères communs. Il sera intéressant d’étudier si des modules communs peuvent être réutilisés sachant que les entrées et rubriques d’aide peuvent s’apparenter à des items de langue (identifiant unique, appartenance à un module).
Quelques éléments sur les autorisations
Le site http://aide.spip.net autorisera l’inscription de nouveaux rédacteurs. Tout rédacteur pourra créer un nouveau module.
Seul le/les auteurs d’un module auront les droits pour créer/supprimer/éditer/ordonner une entrée d’un module d’aide. Les autres rédacteurs ne pourront que créer/modifier/éditer les traductions des entrées mais ne pourront changer l’ordre des entrées.
Les auteurs d’un module pourront ordonner leurs entrées d’aide entre elles et par rapport à celles des autres modules, mais ne pourront modifier l’ordre relatif des entrées d’aide des modules dont ils ne sont pas auteur.
Tout auteur de module pourra créer une nouvelle rubriques d’aide. Par contre, il ne pourra pas supprimer une entrée d’aide si celle-ci est utilisée par un autre module.
Concernant l’ordonnancement des rubriques d’aide, il faudra voir s’il est préférable de limiter ce droit ou non aux administrateurs généraux. Le fonctionnement global des autorisations sera de toute façon à affiner à l’usage.
Pense-bête
Prévoir quelques classes spécifiques (<div class="webmaster">..</div> ou <div class="admin">..</div> pour mettre en évidence les éléments de doc spécifiques aux admins et/ou aux webmasters afin que les rédacteurs sachent qu’il peuvent sauter cette partie). On peut facilement ajouter des boutons dédiés au porte-plume.
De même, il faut envisager deux nouveaux raccourcis pour faire un lien sur une autre entrée d’aide ou sur une page de l’espace privé, par exemple [->aide:spip/liens] et [->exec:configurer_avancees].
RSS 2.0