Aide par Objet

Ce plugin pour les personnes qui font du développement propose une aide contextuelle sommaire, dans la partie privée, sur la partie gauche, pour les objets ou exec de vos plugins. Cette aide est extrêmement aisée à mettre en oeuvre et absolument pas chronophage. C’est cette dernière raison qui m’a amené à la développer.

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.

  1. Il y a tout d’abord la possibilité d’étendre l’aide en ligne de SPIP ;
  2. Il y a la possibilité de créer un assistant de premiers pas avec SPIP, Compagnon.
  3. 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>&lt;img>cadenas-24.svg&lt;/img><br>&lt;class>basic inverse&lt;/class><br>&lt;class_titre>centered&lt;/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.

Notes

[1L’aide est une boite (#BOITE_OUVRIR #BOITE_FERMER) incluse par le pipeline affiche_gauche. Le fichier inclu est prive/objets/infos/inc-aide_par_objet.html. Il est accompagné d’un fichier de fonctions.

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

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.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom