Créer une aide en ligne pour un plugin

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’une clé, appelée groupe, et de valeurs 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.

<em class="aide">#AIDER{soustitre}</em>

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;
 }

function lister_tables_objets_sql(?string $table_sql = null, $desc = []) {
 $infos_tables = [
  'spip_articles' => [
  // (....)
   'aide_changer_statut' => 'artstatut',
  // (....)
  ]
 ];

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;
}