1. Déclarer l’usage du plugin aide et de son pipeline
Le plugin aide
est fourni avec la distribution de SPIP (plugins-dist/aide/
). Il est de bonne pratique de déclarer son utilisation dans le paquet de votre plugin de façon à ce que l’on sache qu’il est utilisé, au cas où la distribution viendrait à changer.
L’usage du plugin aide
déclaré, il faut également indiquer que vous allez utiliser son pipeline.
Exemple : Le Plugin Pense-bêtes, dans son paquet, déclare ainsi l’aide :
<!-- on utilise le plugin d'aide de SPIP -->
<utilise nom="aide" compatibilite="[2.0.2;[" />
<!-- Rendre l'aide active -->
<pipeline nom="aide_index" inclure="pensebetes_pipelines.php" />
2. Se brancher sur le pipeline de l’aide de SPIP
Le plugin aide
crée un pipeline permettant l’enrichissement d’un index des aides disponibles. C’est en utilisant le pipeline aide_index
que vous pourrez enrichir l’index des aides disponibles en indiquant celles que propose votre plugin.
Exemple : Le Plugin Pense-bêtes déclare ainsi ses aides dans le fichier pensebetes_pipelines.php :
/**
* Utiliser ce pipeline permet d'ajouter une aide au plugin,
*
* @pipeline aide_index
* @param array $flux Données du pipeline
* @return array Données du pipeline
*/
function pensebetes_aide_index($index) {
$index['assopb'] = [
'possibles',
'association'
];
return $index;
}
Vous pouvez, pour mieux comprendre encore, regarder comment le plugin Aide déclare l’aide de SPIP.
Deux points de vigilance :
- La déclaration consiste à ajouter à l’index d’aide, qui est un
tableau
, une entrée composée d’uneclé
, appelée groupe, et devaleurs
appelées entrées. Soyez attentif à ne pas définir vos groupes et entrées en utilisant d’underscore
(caractère :_
) afin de permettre une bonne lisibilité des idiomes de langue qui seront définis en{groupe}_{entrée}
(voir le point 4 de cet article). - Soyez attentif à éviter les homonymies : si vous déclarer un groupe déjà existant, vous allez le remplacer par votre déclaration. Préfixer vos groupes par le nom de votre plugin ou un abrégé de celui-ci peut-être une bonne pratique.
3. Créer l’arborescence des répertoires nécessaires et y placer les fichiers d’aide ad hoc
L’arborescence des répertoires de votre plugin doit refléter les déclarations que vous avez faites pour enrichir l’index de l’aide. En effet, c’est auprès des fichiers placés dans ces répertoires, que le plugin aide
ira chercher les aides que vous aurez rédigées pour votre propre plugin.
L’aide pouvant être traduite, elle est représentée par un premier répertoire signalant la langue. En-dessous se trouve chaque répertoire correspondant au groupe, puis le/les fichier texte avec l’extension .spip
, appelée entrée, accueillant l’aide elle-même.
La bonne surprise, lors de la rédaction des aides de votre plugin, est que les conventions suivent celles que vous utilisez à l’intérieur d’un article. Vous pouvez utiliser les même conventions typographiques.
Exemple : Le plugin Pense-bêtes a une arborescence de ses répertoires et des fichiers d’aide disponibles qui traduisent les déclarations faire dans le pipeline aide_index
:
Aux déclarations...
$index['assopb'] = [
'possibles',
'association'
];
... correspond l’arborescence :
.../pensebetes/aide/fr/assopb/possibles.spip
.../pensebetes/aide/fr/assopb/association.spip
4. Créer quelques idiomes de langue pour le groupe et l’entrée
L’avant dernière tâche à faire est de donner valeurs aux idiomes en créant un fichier de langue dénommé aide_fr.php
au sein du répertoire ./lang
de votre plugin.
Exemple : Le contenu du fichier de langue du plugin Pense-bêtes est ainsi rédigé :
<?php
$GLOBALS[$GLOBALS['idx_lang']] = array(
'assopb' => 'Associer des Pense-bêtes',
'assopb_possibles' => 'Définir les Objets sur lequels placer des Pense-bêtes',
'assopb_association' => 'Quel Pense-bête associer ?',
);
5. Rendre disponible l’aide créée
Il y a quatre manières d’appeler l’aide.
a) Utiliser la balise #AIDER
dans un squelette
Vous pouvez, dans les squelettes de votre plugin, offrir l’aide rédigée en utilisant la balise #AIDER.
Exemple : SPIP utilise cette balise pour proposer une aide pour les articles. Le formulaire d’édition appelle la balise #AIDER par ce simple code :
<em class="aide">#AIDER{soustitre}</em>
Toutefois, noter que cette forme d’appel n’est plus conforme. Elle reste maintenue pour des raisons historiques. Il convient d’appeler l’aide par son groupe ou son groupe et son entrée comme vous le verrez ci-après.
b) Utiliser l’aide avec le plugin Saisies pour formulaire
Le plugin Saisies pour formulaire permet très facilement d’appeler l’aide en ligne de SPIP [1].
Exemple : Le plugin Pense-bêtes utilise cette possibilité en déclarant une aide lors de la saisie textarea
permettant de compléter le contenu d’un Pense-bête.
function formulaires_editer_pensebete_saisies_dist($id_pensebete='new', $id_parent='', $retour='', $associer_objet='', $lier_trad=0, $config_fonc='',
// (...)
$saisies = array(
array( // le fieldset
'saisie' => 'fieldset',
'options' => array(
'nom' => 'le_pensebete',
'label' => _T('pensebete:info_le_pensebete'),
'icone' => 'pensebete-24'
),
array( // champ texte : un bloc de texte
'saisie' => 'textarea',
'options' => array(
'nom' => 'texte',
'label' => _T('pensebete:label_message'),
'rows' => 3,
'cols' => 60,
'longueur_max' => $maxlength_corps, // limiter la taille du texte
'aide' => 'textepb'
),
'verifier' => array(
'type' => 'taille',
'options' => array ('min' => 0, 'max' => $maxlength_corps)
),
),
),
)
);
return $saisies;
}
c) Utiliser les déclarations dans les tables
La déclaration des tables peut être l’occasion de déclarer des aides. SPIP en donne un exemple avec la déclaration de la table spip_articles
. Est précisée une aide lors du changement de statut de l’objet.
function lister_tables_objets_sql(?string $table_sql = null, $desc = []) {
$infos_tables = [
'spip_articles' => [
// (....)
'aide_changer_statut' => 'artstatut',
// (....)
]
];
d) Utiliser la fonction aide()
via un script PHP
Le plugin Pense-bêtes appelle l’aide en ligne en PHP depuis le pipeline recuperer_fond pour permettre aux utilisateurs de mieux comprendre les associations de Pense-bêtes. Voici comment le plugin procède :
function pensebetes_recuperer_fond($flux) {
// travailler sur le fond editer_objet
if (isset($flux['args']['fond']) and $flux['args']['fond'] == 'formulaires/editer_liens') {
// si on est dans le cadre de l'association de pense-bêtes
if (isset($flux['args']['contexte']['_vue_ajout']) and $flux['args']['contexte']['_vue_ajout'] == 'pensebetes_associer'){
// proposer une aide sur les associations de Pense-bêtes - Générer un lien d'aide (icône + lien)
if ($aide = charger_fonction('aide', 'inc') and $aider = $aide('assopb/association')){
$rechercher = '<h3 class="titrem">' . _T('pensebete:texte_ajouter_pensebete');
$remplacer = $rechercher . $aider;
$flux['data']['texte'] = str_replace ($rechercher, $remplacer, $flux['data']['texte']);
}
}
}
return $flux;
}
Aucune discussion
Ajouter un commentaire
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.
Suivre les commentaires : |