Principales fonctionnalités

  • Le composant Help vous permet d'utiliser votre site Joomla! comme serveur pour les écrans d'aide de l'administration de Joomla!.
  • Quand un utilisateur clique sur btn aide dans l'administration, il reçoit l'écran d'aide correspondant que vous avez traduit dans votre serveur d'aide.
  • Si l'écran d'aide n'est pas encore traduit, il sera proposé à l'utilisateur de voir l'écran d'aide correspondant en anglais.
  • Les écrans d'aide sont affichés sans aucun menu ni module (mode component de Protostar) pour garder l'utilisateur concentré sur le contenu de l'aide.
  • De façon à ne pas démarrer sur un menu standard, le composant Help permet de créer un lien de menu qui sera utilisé comme page d'accueil. Cette page d'accueil peut être la page de démarrage de l'aide ou la page avec la liste des écrans d'aide.
  • La licence de la Documentation Electronique de Joomla! et un lien vers la page source du wiki en anglais sont automatiquement ajoutés.
  • La version actuelle supporte les utilisateurs Joomla! 3.x
  • Le plug-in optionnel HelpToContent permet d'utiliser simultanément le serveur d'aide comme site Joomla! standard avec des menus et des modules.

Comment fonctionne le système d'aide ?

Chaque écran de l'administration de Joomla! est associé à une clé de référence unique qui est utilisée pour générer l'URL d'où sera retrouvée l'information d'aide.

Quand vous cliquez sur le bouton d'aide d'un écran de l'administration de Joomla!, le processus est le suivant :

Clé de référence associée

Chaque bouton btn aide est associé à une clé de langue standardisée. Cette clé de langue est traduite en clé de référence selon le fichier de langue en cours.

Par exemple, l'écran d'aide de la Gestion des articles est associé avec la clé de langue JHELP_CONTENT_ARTICLE_MANAGER.

Dans le cas de l'anglais, le fichier de langue en-GB.ini contient l'entrée :

JHELP_CONTENT_ARTICLE_MANAGER="Content_Article_Manager"

La clé de référence qui en résulte pour la Gestion des articles est Content_Article_Manager.

Choix du serveur d'aide

L'écran de Configuration (Système → Configuration → Système → Serveur d'aide) permet de sélectionner le serveur d'aide. La liste des serveurs disponibles est définie dans le fichier XML /administrator/help/helpsites.xml.

Chaque serveur est défini dans la liste en utilisant la syntaxe suivante :

<site tag="code_langue" url="url_serveur">nom_server</site>

Vous pouvez manuellement modifier le fichier helpsites.xml file pour changer la liste.

Par exemple, le serveur par défaut est le wiki de documentation de Joomla! en anglais (English (GB) - Joomla help wiki) :

<?xml version="1.0" encoding="utf-8"?>
<joshelp>
    <sites>
        <site
            tag="en-GB"
            url="http://help.joomla.org/proxy/index.php?option=com_help&keyref=Help{major}{minor}:{keyref}">English (GB) - Joomla help wiki</site>
    </sites>
</joshelp>

Construction de l'URL

Les URL du fichier helpsites.xml contiennent des codes entre accolades {}. Ces codes sont substitués par le système d'aide pour construire l'URL pour appeler le serveur d'aide. Vous pouvez voir ICI la liste des codes de substitutions existants.

Par exemple, si l'URL dans helpsites.xml est :

http://help.joomla.org/proxy/index.php?option=com_help&keyref=Help{major}{minor}:{keyref}

Si vous demandez de l'aide pour la Gestion des articles de Joomla! 3.1, la substitution des codes {major}, {minor} et {keyref} aura pour résultat l'URL suivante :

http://help.joomla.org/proxy/index.php?option=com_help&keyref=Help31:Content_Article_Manager

Affichage de l'écran d'aide

Le composant (com_help) du serveur d'aide (http://help.joomla.org/proxy/) analyse la clé de référence transmise (Help31:Content_Article_Manager) pour retrouver et afficher l'écran d'aide correspondant (Help of Article Manger) à partir du wiki de documentation de Joomla!.

Configuration pour les utilisateurs

Mise à jour du fichier <racinejoomla>/administrator/help/helpsites.xml

A partir de Joomla! 3.2.0, les utilisateurs ont seulement à accéder à Système → Configuration → Système et à cliquer sur le bouton Actualiser sur la ligne Serveur d'aide. Cela mettra à jour le fichier helpsites.xml y compris votre serveur s'il a été mis dans le fichier de référence par la Translation Team.

Si votre serveur est sur une version de Joomla! antérieure à la 3.2.0 ou si votre serveur n'est pas encore dans le fichier de référence de la Translation Team, vos utilisateurs vont devoir ajouter manuellement l'information sur votre serveur dans le fichier helpsites.xml de leur installation Joomla!.

Par exemple, vous pouvez voir ci-dessous en rouge l'ajout d'un serveur pour les écrans d'aide en français :

<?xml version="1.0" encoding="utf-8"?>
<joshelp>
    <sites>
        <site
            tag="en-GB"
            url="http://help.joomla.org/proxy/index.php?option=com_help&keyref=Help{major}{minor}:{keyref}">English (GB) - Joomla help wiki</site>
        <site
            tag="fr-FR"
            url="http://help.joomla.fr/{major}/index.php?option=com_help&keyref=Help{major}{minor}:{keyref}">French (FR) - Aide de Joomla!</site>
    </sites>
</joshelp>

Les éléments ajoutés sont les suivants :

  • Le tag est fr-FR
  • L'URL http://help.joomla.fr/{major}/index.php?option=com_help&keyref=Help{major}{minor}:{keyref} comprend trois parties :
    • La première partie (http://help.joomla.fr/{major}/) correspond au serveur (domaine et sous-dossier) où se trouve l'installation Joomla!. Les codes de substitution sont très flexibles. Dans l'exemple, le code {major} est remplacé par le numéro de révision majeure de de Joomla!. Donc en fonction de la version de Joomla! de l'utilisateur, l'URL du serveur d'aide sera http://help.joomla.fr/3/ pour Joomla! 3.x et http://help.joomla.fr/4/ pour Joomla! 4.x.
    • La deuxième partie (index.php?option=com_help&keyref=) est le composant Help avec la variable keyref.
    • La dernière partie (Help{major}{minor}:{keyref}) est la clé de référence de l'écran d'aide où les codes de substitutions seront convertis. Dans les exemples précédents, le résultat de la substitution serait Help31:Content_Article_Manager.
  • Le nom du serveur est French (FR) - Aide de Joomla!. Ce nom est celui que les utilisateurs devront sélectionner dans l'écran Configuration - Paramètres du système.

Configuration du système

Une fois définie la liste des serveurs d'aide dans helpsites.xml, vos utilisateurs doivent choisir votre serveur d'aide dans le champ Serveur d'aide de l'écran Système → Configuration → Système → Paramètres système.

Configuration du serveur d'aide

Installation des extensions

Il faut installer deux extensions sur le serveur d'aide Joomla!, le composant Help et le plugin HelpToContent.

Le composant Help :

  • Reçoit la clé de référence dans l'URL.
  • Affiche la page d’aide correspondant à la clé de référence.
  • Si l’article n’est pas encore traduit, il propose la page en anglais.

Le plug-in HelpToContent :

  • Quand on navigue sur le site, il route les liens entre les pages au format Help (index.php?option=com_help&keyref=xxx) vers le format Content (com_content)
  • Le plug-in n'est utilisé que si vous voulez créer un site web d'aide. Il n'est pas nécessaire si vous voulez uniquement implémenter la traduction des pages pop-up des boutons d'aide.

L'installation du composant Help et du plug-in HelpToContent se fait en utilisant la Gestion des extensions disponible dans Joomla! : Extensions → Gestion des extensions.

Surcharge de l'affichage des articles

Cette section n'est utilisée que si vous voulez afficher une icône IcoMoon devant le titre comme ajouté dans Joomla! 3.2.0.

Je présume que vous utilisez le template Protostar avec l'option liens pour les titres :

  • Créez les répertoires templates/protostar/html/com_content/article.
  • Copiez vers templates/protostar/html/com_content/article les fichiers default.php, default_links.php et index.html de components/com_content/views/article/tmpl
  • Editez le fichier templates/protostar/html/com_content/article/default.php :
    • Replacez le code suivant :
      <a href="/<?php echo $this->item->readmore_link; ?>"> <?php echo $this->escape($this->item->title); ?></a>
    • Par (en rouge le nouveau code) :
      <a href="/<?php echo $this->item->readmore_link; ?>">
      <!-- Rajoz begin - Add icon from xreference before title -->
      <?php if ($this->item->xreference) : ?>
      <?php echo '<span style="font-weight: normal"></span>&nbsp;'; ?>
      <?php endif; ?>
      <!-- Rajoz end -->
      <?php echo $this->escape($this->item->title); ?>
      </a>

Configuration des extensions

Composant Help

  • Pour configurer le composant Help sélectionnez Composants → Help → Paramètres dans le menu déroulant de l'administration de Joomla!
  • L'écran de configuration de Help a deux paramètres :
    • Version actuelle de Joomla! : Selectionnez la version actuelle de Joomla! (3.1, 3.2, 3.5) dans la liste déroulante. Ce paramètre est utilisé pour construire le lien de retour vers le wiki anglais quand l'écran n'est pas encore traduit.
    • Version LTS de Joomla! : Sélectionnez la version longue durée (LTS) de Joomla! dans la liste déroulante. Actuellement seule la 3.5 est proposée.

Plug-in HelpToContent

  • Allez à Extensions → Gestion des plug-ins → Contenu - HelpToContent
  • Comme pour tous les plug-ins vous devez l'activer après la première installation.
  • Les deux paramètres à configurer sont les mêmes que ceux du composant (version actuelle et LTS de Joomla!).

Comment faire pour que votre article traduit devienne un écran d'aide ?

La seule chose à faire c'est d'ajouter la clé de référence à l'article :

  • Clé de référence LTS : Le composant Help convertit automatiquement les clés de référence à la version long terme (LTS) de Joomla!. Pour pouvoir supporter n'importe quelle version 3.X de Joomla!, vous devez utiliser la clé de référence LTS 3.5 dans vos articles. Dans l'exemple, la clé de référence LTS est Help35:Content_Article_Manager.
  • Modification de l'article :
    • Ouvrir l'article sélectionné.
    • Aller à l'onglet Publication.
    • Saisir dans le champ "Référence externe" la clé de référence LTS (par exemple, Help35:Content_Article_Manager).
    • Optionnellement, saisir dans le champ "Clé de référence" l'icône du titre basée sur IcoMoon (par exemple, icon-stack).
    • Enregistrer l'article.

Liste des articles à traduire

  • L'écran liste des écrans d'aide vous donnera une vue complète sur les articles à traduire. Rappelez-vous que ce n'est pas un problème si tous les écrans ne sont pas traduits parce que si un écran n'est pas traduit, les utlisateurs se verront proposer l'écran d'aide correspondant en anglais.
  • La clé de référence de chaque article est dans la colonne 'Help screen'. Vous pouvez cliquer sur la clé de référence pour afficher l'écran d'aide correspondant. Rappelez-vous  que vous devez adapter la clé de référence. Par exemple, si la clé dans la liste est Site_Global_Configuration, la clé de référence à utiliser dans votre article sera Help35:Site_Global_Configuration.

Liens vers d'autres articles

  • Dans le wiki en anglais, l'URL des liens vers d'autres écrans sont du format http://help.joomla.org/proxy/index.php?option=com_help&view=help&keyref=Help31:Content_Article_Manager.
  • Dans vos articles traduits, servez-vous du même type de format avec des URL relatives : index.php?option=com_help&view=help&keyref=Help31:Content_Article_Manager. Comme vous le voyez, la seule modification est d'enlever les informations du serveur (http://help.joomla.org/proxy/). Note : la 'view'  (&view=help) est optionnelle.
  • Pour les ancres : il suffit de conserver l'ancre à la fin du lien (par exemple : index.php?option=com_help&view=help&keyref=Help31:Content_Article_Manager#Screenshot). Vous devez garder le lien complet même si le lien pointe vers une ancre du même article. Par exemple : vous ne devez pas le raccourcir en seulement #Screenshot.
  • Pour créer un lien de ce type, par exemple dans TinyMCE, il faut se servir du bouton "Insérer/Modifier un lien" et saisir manuellement l'URL du lien.
  • Vous ne devez pas utiliser le bouton Article de l'éditeur pour créer le lien parce qu'il se sert du composant com_content au lien de com_help et la présentation de l'écran lié sera différente.
  • Le plug-in optionnel HelpToContent convertit les liens com_help en liens standards com_content quand l'utilisateur navigue sur le site via les menus.

Ecrans spéciaux

L'écran de démarrage du système d'aide (Help35:Start_Here)

  • Il n'est pas dans la liste des écrans d'aide mais vous devez le traduire parce que c'est l'écran initial que vos utilisateurs verront quand ils cliqueront sur Aide → Aide Joomla Help dans le menu déroulant de l'administration.
  • Le composant Help vous permet de définir un lien de menu sur cet article et de l'utiliser comme page d'accueil de votre serveur.

L'écran avec la liste des écrans d'aide (Help35:Help_screens)

  • Comme expliqué plus haut, la liste des écrans d'aide vous donne la liste complète des articles à traduire avec leurs clés de référence.
  • Il n'est pas lui-même listé dans la liste des écrans d'aide cependant la traduction et des liens vers cet écran aideront vos utilisateurs à trouver l'écran d'aide qu'ils recherchent.
  • Pour être plus efficaces, vous pouvez remplacer dans votre traduction les trois colonnes 'Path in user interface', 'Component/View' et 'Language key' par une seule colonne avec le titre de l'écran d'aide.
  • Le composant Help vous permet de définir un lien de menu sur cet article et de l'utiliser comme page d'accueil de votre serveur.

L'écran d'aide du composant Help (Help35:Components_Help_User_Guide_AFUJ_English)

  • Cet écran est l'aide pour le composant Help. Vous pouvez trouver la même information (en anglais) dans le fichier readme.txt file du paquet du composant.
  • La clé de référence Components_Help_User_Guide_AFUJ_English de cet écran est définie par l'entrée COM_HELP_TOOLBAR_HELP dans le fichier de langue de l'administration (en-GB.com_help.ini) du composant Help. Note : Comme défini dans helpsites.xml la chaîne 'Help:35' sera ajoutée à la clé de référence par le système d'aide.
  • Important : Initialement, cet écran s'affiche à partir du serveur d'aide de l'AFUJ (Association Francophone des Utilisateurs de Joomla!). Ce comportement est réalisé par le mot AFUJ dans la clé de référence. Si vous voulez utiliser un écran traduit localement, vous devez supprimer le mot AFUJ et modifier l'entrée dans le fichier de langue pour correspondre avec la clé de référence de votre article. Par exemple, l'entrée COM_HELP_TOOLBAR_HELP="Components_Help_User_Guide" appellera l'article local dont la clé de référence LTS est Help35:Components_Help_User_Guide.

Catégories

  • Il est vivement conseillé de suivre l'organisation des groupes de la liste des écrans d'aide pour créer vos catégories :  Système, Utilisateurs, Menus, Types de liens de menu, Contenu, Composants, Paramètres des composants, Extensions, Types de modules. Cette organisation correspond aux menus de l'administration.
  • Pour gérer plus facilement vos articles, vous pouvez créer des sous-catégories, par exemple Bannières comme sous-catégorie de Composants pour tous les articles dont la clé de référence LTS débute par 'Help35:Components_Banners_...'.

Images

  • Il est plus simple pour les images des articles de créer une hiérarchie de dossiers similaire à celle utilisée pour l'organisation des catégories.
  • Il est aussi recommandé d'utiliser des noms faciles à se rappeler comme screenshot.png ou toolbar.png. Par exemple, L'écran principal de la Gestion des articles peut être stocké dans images/help/content/article_manager/screenshot.png

Informations en relation

Copyright © 2013 Joomla.fr - Association Francophone des Utilisateurs de Joomla! Tous droits réservés.