1. Objet du plugin
a) Les aides existantes
Il y a beaucoup de façon de proposer de l’aide aux utilisateurs de vos plugins.
- Il y a tout d’abord la possibilité d’étendre l’aide en ligne de SPIP ;
- Il y a la possibilité de créer un assistant de premiers pas avec SPIP, Compagnon.
- Enfin, il y a la possibilité d’expliquer vous-même les champs de vos saisies, par une info bulle ou un label explicatif. Par exemple, le plugin Saisies pour formulaires propose un attribut explication rien que pour cela.
Le présent plugin vous propose une nouvelle façon d’apporter de l’aide en créant une bulle informative sur la partie gauche, par objet ou par exec.
b) Les avantages et inconvénients de la nouvelle aide proposée
Cette aide présente l’inconvénient de venir proposer l’aide sur la partie gauche de la partie privée, ce qui peut provoquer une surabondance d’informations si votre plugin y affiche beaucoup d’éléments.
Cette aide présente l’avantage :
- De répondre à un niveau d’information qui est celui de l’Objet ou de l’Exec. En d’autres termes, l’aide n’explique pas tous les champs d’un formulaire, ce qui est chronophage, mais l’objet lui-même, permettant d’aller à l’essentiel. On n’a donc pas à expliciter des étapes de saisies ou des détails sur des données mais simplement à expliquer le traitement fait.
- L’aide est en permanence visible, ce qui répond à un besoin que ne remplit pas l’aide en ligne, qui sollicite un appel, ou l’aide de premiers pas, par vocation éphémère.
2. Installation, préférences, configuration
Le plugin ne nécessite aucun autre plugin.
a) Installation
Le plugin a été soumis sur la Zone. Il s’installe comme n’importe quel plugin de SPIP.
b) Préférences
Vos utilisateurs pourront par eux-même décider si vos bulles d’information sont utiles ou non. En effet, un auteur, dans ses préférences, peut retirer ou non cette fonctionnalité.
c) Configuration
Il est possible de forcer la présence de l’aide, même si ce n’est pas très convivial, en accédant la configuration du plugin.
3. Utilisation dans votre plugin
Votre plugin peut utiliser ce plugin. Il suffit de deux opérations :
- déclarer l’usage du plugin;
- l’étendre à vos besoins par des chaînes de langue.
a) La dépendance
Préciser la dépendance dans votre plugin comme optionnelle, car le fait de ne pas pouvoir avoir d’aide contextuelle sur un objet ne devrait pas être bloquant ni nécessaire...
L’attribut utilise vous permettra de le faire dans la déclaration précitée le paquet.xml définissant votre plugin.
b) Les chaînes de langues
Créer un fichier déclarant les chaînes de langue que vous souhaitez voir afficher pour un objet, dans le répertoire lang/ et sous le nom aide_par_objet_fr de votre plugin.
La normalisation de la déclaration est la suivante :
[exec_ou_objet]_texte qui correspond à la chaîne de langue qui affichera l’aide elle-même ;
[exec_ou_objet]_titre qui correspond à la chaîne de langue qui affichera le titre de l’aide.
Voici un exemple, pour l’exec configurer_aide_par_objet que vous trouverez dans le fichier /lang/aide_par_objet_fr.
'configurer_aide_par_objet_texte' => 'L’aide est une boite qui apparaitra à gauche lors de la consultation de l’objet ou de l’exec. Pour la mettre en oeuvre, il faut définir deux idiomes de langue, l’un intitulé <code>OBJET_titre</code> - qui sera le titre de la boite -, l’autre intitulé <code>OBJET_texte</code> - qui sera le contenu de la boite. Cette présente bulle d’aide est un exemple que vous trouverez dans le fichier <code>lang/aide_par_objet_fr</code> !<br><br>L’idiome <code>OBJET_titre</code> peut vous permettre de transmettre des arguments permettant de personnaliser la boite, en les plaçant dans les balises suivantes :<br><small><img>cadenas-24.svg</img><br><class>basic inverse</class><br><class_titre>centered</class_titre></small>',
'configurer_aide_par_objet_titre' => 'Comme ça marche ?',c) Transmission d’arguments de personnalisation
L’aide peut être personnalisée en transmettant des arguments [1], en les plaçant dans les balises suivantes :
<img>cadenas-24.svg</img>
<class>basic inverse</class>
<class_titre>centered</class_titre>
Ces balises sont a incorporer dans l’idiome de langue OBJET_titre.
Exemple :
'configurer_aide_par_objet_titre' => '<img>cadenas-24.svg</img><class>basic inverse</class><class_titre>centered</class_titre>Comme ça marche ?',4. Restriction
Il n’y a pas de restriction technique, mais simplement un usage de bon sens.
N’écrivez pas un roman.
- Pour une raison logique, tout d’abord : une aide doit être brève et précise. Ce n’est pas très aidant d’avoir une explication qui demande réflexion...
- Pour une raison technique, ensuite : si votre aide est trop longue elle monopolisera la partie gauche, empêchant d’autres fonctionnalités de s’afficher.
No discussion
Add a comment
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Follow the comments:
|
