Aide de l'Administration

Introduction

Presque toutes les pages de l'Administration de Joomla possèdent une barre d'outils contenant un bouton Aide près du coin supérieur droit de la page. Seuls les tableaux de bord sont dépourvus de barre d'outils et donc de bouton Aide.

De nombreuses pages possèdent également un bouton intitulé Afficher/Masquer l'aide. Celui-ci affiche ou masque simplement la description d'un champ si elle est disponible. Son but est de réduire l'encombrement tout en fournissant un mécanisme de rappel lorsque cela peut être utile. Il n'est pas traité davantage ici.

Le bouton Aide déclenche l'ouverture d'une nouvelle fenêtre à l'aide d'une URL intégrée dans le bouton. Un exemple :

data-url="https://help.joomla.org/proxy/index.php?keyref=Help51:Articles&lang=en"

Dans ce cas, le contenu de la page d'aide provient d'une source externe.

La source d'aide - un site MediaWiki

MediaWiki est le logiciel utilisé par Wikipédia. C'est un pack logiciel libre et open source (FOSS) qui utilise PHP et MySQL, tout comme Joomla. Vous pouvez le télécharger et l'installer vous-même. En théorie, vous pourriez créer votre propre serveur d'aide et l'utiliser à la place du serveur d'aide communautaire de Joomla. En pratique, il faut savoir que les pages MediaWiki nécessitent un certain traitement pour être adaptées à un affichage en tant que pages d'aide.

C'est là qu'intervient le proxy. Il récupère la page requise depuis l'installation MediaWiki et la prépare pour un affichage en tant que page d'aide. Vous pouvez voir une page MediaWiki originale dans cet exemple à l'adresse https://docs.joomla.org/Help5.x:Articles et vous pouvez la modifier si vous constatez une erreur.

L'URL d'aide globale

Le fichier configuration.php situé à la racine d'une installation Joomla contient une variable $helpurl :

$helpurl = 'https://help.joomla.org/proxy/index.php?keyref=Help{major}{minor}:{keyref}&lang={langcode}';

Lorsqu'un bouton Aide est sélectionné, chacun des éléments entre accolades est remplacé. Les valeurs {major} et {minor} correspondent aux paramètres de version de votre installation. {langcode} est le code de la langue d'Administration actuellement sélectionnée, qui peut être en, de ou fr.

La variable {keyref} est le nom de fichier d'une page sur le serveur d'aide, sans son espace de noms. Ainsi, pour la page Articles, le nom de fichier correspondant est Articles.

Remarque : https://docs.joomla.org/ est le site permettant de modifier les pages d'aide. Mais https://help.joomla.org/proxy est le site de récupération des pages d'aide.

Il n'existe pas de moyen de modifier l'URL du serveur d'aide par défaut depuis les formulaires de Configuration globale de l'Administration, mais vous pouvez le faire avec un éditeur de texte.

La liste complète des codes de substitution disponibles est :

L'aide globale à l'avenir

L'utilisation d'un site MediaWiki pour la diffusion des pages d'aide représente une certaine charge pour ceux qui maintiennent la documentation, et la procédure pourrait évoluer à l'avenir. En cas de changement, il est probable que la source soit constituée de fichiers HTML préconstruits, accessibles par un simple changement du domaine source de $helpurl.

Aide locale pour un composant personnalisé

Si vous avez un composant personnalisé et que vous êtes à l'aise avec l'édition de code source php et la création de contenu, vous pouvez créer vos propres pages d'aide individuelles. Prenons l'exemple du composant Jdocmanual. En tant que composant personnalisé, il n'y a pas de pages d'aide sur le site MediaWiki docs.joomla.org. Les composants tiers ne sont pas autorisés à y diffuser des pages d'aide.

Examinez cet extrait de code provenant de administrator/components/com_jdocmanual/src/View/Manual/ViewHtml.php :

        $tmpl = $app->input->getCmd('tmpl');
        if ($tmpl !== 'component') {
            ToolbarHelper::help('jdocmanual', true);
        }

La spécification de l'appel ToolbarHelper::help est la suivante :

@param $ref: The name of the target file (excluding the file extension).
@param $useComponent: Use the help file in the component directory.
@param $url: Use this URL instead of any other.
@param $component: Name of component to get Help (null for current component)
function Toolbar::help(
    string $ref,
    bool $useComponent = false,
    string $url = null,
    string $component = null
): HelpButton
Writes a help button for a given option (opens a popup window).

Dans cet exemple, $ref est un nom de fichier à utiliser, ici 'jdocmanual' (la casse doit correspondre à celle du fichier cible), et $useComponent vaut true, ce qui signifie que la page d'aide utilisée sera celle située dans les fichiers du composant, à administrator/component/com_jdocmanual/help/en-GB/jdocmanual.html

Utiliser un fichier d'aide intégré au composant garantit en principe que l'aide n'est jamais manquante et qu'elle est toujours à jour.

Aide distante pour un composant personnalisé

Lors de la création du bouton Aide, vous pouvez définir $useComponent = false et faire pointer l'url vers un emplacement spécifique de votre propre site ou d'un site distant.

    ToolbarHelper::help('jdocmanual', false, 'http://example.com/help/en-GB/jdocmanual.html');

Il suffit donc d'avoir une page HTML portant le bon nom, placée au bon endroit.