Aide par Objet

Ce plugin pour les développeurs 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.

Objet du plugin

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.

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.

Installation, préférences, configuration

Installation

Le plugin a été soumis sur la Zone. Il s’installe comme n’importe quel plugin de SPIP.

Sentez-vous libre de participer au développement du plugin.

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

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.

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.

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.

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' => "La trophallaxie (du grec trophein : nourrir et allassein : échanger) est un mode de transfert de nourriture utilisé par certains insectes hyménoptères. Ce plugin permet de nourrir vos propres plugins de bulles d'aide...", 
'configurer_aide_par_objet_titre' => "Ça veut dire quoi ?", 

Il vous est possible de définir que vous souhaitez avoir votre propre présentation de l’aide proposée pour l’objet. Pour ce faire, vous pouvez définir la chaine de langue de titre en la faisant débutée par #. La chaîne de langue du texte de l’aide ne sera alors plus présentée dans un tableau mais simplement au sein d’une div dont la class sera celle de votre titre. Il est possible de solliciter l’utilisation d’un identifiant unique pour l’ensemble du document en faisant débuter la chaîne de langue du titre par un double ##. La balise div utilisera alors un id.

Un exemple est utilisé dans le plugin Rendez-vous (en cours de développement et bientôt disponible) qui va utiliser la class notice :

'rencontre_edit_texte' => "Lors de la création de votre rencontre, vous définissez par qui elle sera visible dans l'agenda. Faites attention à ne pas donner une diffusion inadaptée à des informations confidentielles.",
'rencontre_edit_titre' => "#notice",

Ce qui permet d’avoir une aide en ligne ayant cette apparence :

Exemple de l'utilisation de la class 'notice'
Exemple de l’utilisation de la class ’notice’

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.

updated on 28 April 2020

Discussion

Aucune discussion

Ajouter un commentaire

Who are you?
[Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom