Main features

  • The component Help allows you to use your Joomla! site as server for the help screens in Joomla! Administration.
  • When a Joomla! user clicks on btn help button in administration, he will get the corresponding help screen you have translated on your help server.
  • If the help screen is not yet translated, the user will be proposed to see the corresponding English help screen.
  • Help screens are displayed without any menu or module (component mode from Protostar) to keep the user concentrated on the help content.
  • In order to avoid starting on a standard menu item, the component Help allows to create a menu item which will be used as the home page. This home page could be the help start page or the list of help screens.
  • License for Joomla! Electronic Documentation and a link to the English wiki source page are automatically added.
  • Current version is built to support Joomla! 3.x users.
  • The optionnal plugin HelpToContent allows to use simultaneously the help server as a standard Joomla! site with menus and modules.

How does the Help System work?

Each screen in Joomla! administration is associated with a unique key reference which will be used to generate a URL from which the help information will be retrieved and displayed.

When you click on the help button of an administrator page the process is as follows:

Associated key reference

Each btn help button is associated with a standardised language key. This language key is translated into the key refence by the currently loaded language file.

For example, the Article Manager help screen is associated with the language key JHELP_CONTENT_ARTICLE_MANAGER.

In the case of British English the language file en-GB.ini contains the entry:

JHELP_CONTENT_ARTICLE_MANAGER="Content_Article_Manager"

The resulting key reference for the Article Manager is Content_Article_Manager.

Choice of the help server

The Global Configuration - System Settings screen allows to select the Help Server. The list of available help servers is defined in the XML file /administrator/help/helpsites.xml.

Each server site is defined in this list using the following syntax:

<site tag="language_code" url="server_url">server_name</site>

You can manually edit the helpsites.xml file to change the list.

For example, the default help server is the Joomla! documentation wiki (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 of the URL

The URL in the helpsites.xml file contain codes between braces {}. These codes are substitued by the help system to build the URL to call the help server. You can see the list of existing substitution codes here.

For exemple, if the URL in helpsites.xml is:

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

If you are asking for help from the Article Manager in Joomla! 3.1, the substitution of the codes {major}, {minor} and {keyref} will result in the following URL:

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

Display of the help screen

The component (com_help) of the help server (http://help.joomla.org/proxy/) parses the key reference transmitted (Help31:Content_Article_Manager) to retrieve and display the corresponding help screen (Help of Article Manager) from the Joomla! documentation wiki.

Configuration for users

Update of the file <joomlaroot>/administrator/help/helpsites.xml

Starting from Joomla! 3.2.0, the users only have to navigate to System → Global Configuration → System and click on the button Refresh on the Help Server line. This will update the file helpsites.xml including your server if it has been put in the reference file by the Translation Team.

If your server is on Joomla! previous than 3.2.0 or if your help server is not yet in the reference file of the Translation Team, your users will have to add manually your server information in the helpsites.xml file of their Joomla! installation.

For example, you can see below in red an addition of a server for French help screens:

<?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>

The added elements are:

  • The tag is fr-FR
  • The URL http://help.joomla.fr/{major}/index.php?option=com_help&keyref=Help{major}{minor}:{keyref} includes three parts:
    • First part (http://help.joomla.fr/{major}/) corresponds to the server (domain and subdirectory) where Joomla! installation is. The substitution codes are very flexible. In the example, the code {major} will be replaced by Joomla! major revision number. So, depending on the Joomla! version of the user, the URL of the help server will be http://help.joomla.fr/3/ for Joomla! 3.x and  http://help.joomla.fr/4/ for Joomla! 4.x.
    • Second part (index.php?option=com_help&keyref=) is the component Help with the variable keyref.
    • Last part (Help{major}{minor}:{keyref}) is the key reference of the help screen where the substitution codes will be converted. In the previous examples, the result of the substitution would be Help31:Content_Article_Manager.
  • The name of the server is French (FR) - Aide de Joomla!. This name is the one your users will have to select in the Global Configuration - System Settings screen.

System configuration

Once defined the list of help servers in helpsites.xml, your users have to select your help server in the list in the screen Global Configuration - System Settings.

Configuration of the help server

Installation of the extensions

You have to install two extensions on the Joomla! help server, the component Help and the plugin HepToContent.

The component Help:

  • Receives the key reference in the URL.
  • Displays the help page corresponding to the reference key.
  • If the article is not yet translated it will propose the English page

The plugin HelpToContent:

  • When browsing the help site, it will route links between pages from Help format (index.php?option=com_help&keyref=xxx) to Content format (com_content).
  • The plugin is used only if you want to create a help web site. It is not necessary if you want to implement only the translation of the popup pages of the help buttons.

Installation of the component Help and of the plugin HelpToContent is done as for any Joomla! extension using the extension installer available in Joomla!: Extensions → Extension Manager.

Override of the article display

This section is used only if you want to show an icon IcoMoon before the title as added in Joomla! 3.2.0.

I assume you are using Protostar template with link option on the titles:

  • Create the directories templates/protostar/html/com_content/article.
  • Copy to templates/protostar/html/com_content/article the files default.php, default_links.php and index.html from components/com_content/views/article/tmpl/.
  • Edit the file templates/protostar/html/com_content/article/default.php:
    • Replace the following code:
      <a href="/<?php echo $this->item->readmore_link; ?>"> <?php echo $this->escape($this->item->title); ?></a>
    • By (in red what is new):
      <a href="/<?php echo $this->item->readmore_link; ?>">
      <!-- Rajoz begin - Add icon from xreference before title -->
      <?php if ($this->item->xreference) : ?>
      <?php echo '<span class="'.$this->item->xreference.'" style="font-weight: normal"></span>&nbsp;'; ?>
      <?php endif; ?>
      <!-- Rajoz end -->
      <?php echo $this->escape($this->item->title); ?>
      </a>

Configuration of the extensions

Component Help

  • To configure the component Help select Components → Help → Options in the administration menu of Joomla!.
  • The Help options screen has two parameters :
    • Joomla! current version: Select the current version of Joomla! (3.1, 3.2, 3.5) in the dropdown list. This parameters is used to build the link back to the English Wiki when the screen is not yet translated.
    • Joomla! LTS version: Select the LTS version of Joomla! in the dropdown list. Currently only 3.5 is proposed.

Plugin HelpToContent

  • Navigate to Extensions → Plugin Manager → Content - HelpToContent
  • As every plugin you have to activate the plugin after first installation.
  • The two parameters to configure are the same as the component (current and LTS Joomla! version).

How to convert your translated article in a help screen?

The only thing to do is to add the key reference to the article:

  • LTS Key Reference: The component Help is built to convert automatically the key reference to the LTS version of Joomla!. To be able to support any Joomla! 3.x version, you must use the 3.5 LTS key reference in your articles. In the exemple, the LTS key reference is Help35:Content_Article_Manager.
  • Article modification:
    • Open the selected article.
    • Go to the Publishing tab.
    • Enter in the field "External Reference" the LTS key reference (for example, Help35:Content_Article_Manager).
    • Optionnaly, enter in the field "Key Reference" the title icon based on IcoMoon (for example, icon-stack).
    • Save the article.

List of articles to translate

  • The list of help screens will give you a complete view on the list of articles to translate. Remember It is not a problem if all screens are not yet translated because if a screen is not yet translated,  the user will be proposed to see the English help screen.
  • The key reference for each article is in the column 'Help screen'. You can click on the key reference to display the corresponding help screen. Remember: you have to adapt the key reference. For example, if the key reference in the list is Site_Global_Configuration, the LTS key reference to use in your article will be Help35:Site_Global_Configuration.
  • In the english wiki, the URL of the links to other screens are in the format http://help.joomla.org/proxy/index.php?option=com_help&view=help&keyref=Help31:Content_Article_Manager.
  • In your translated arcticles, use a similar format in relative URL: index.php?option=com_help&view=help&keyref=Help31:Content_Article_Manager. As you can see, the only modification has been to remove the server information (http://help.joomla.org/proxy/). Note: the view (&view=help) is optional.
  • For anchors: you just have to keep the anchor at the end of the link (for exemple, index.php?option=com_help&view=help&keyref=Help31:Content_Article_Manager#Screenshot). You must keep this full link even if the link is to an anchor in the same article. For example, you must not shorten it as only #Screenshot.
  • To create such a link, for example with TinyMCE,  you must use the button "Insert/Edit Link" and enter manually the link URL.
  • Do not use the button Article in the editor to create the link because it uses the component com_content instead of com_help and the presentation of the linked screen will be disrupted.
  • The optional plugin HelpToContent converts com_help links to standard com_content links when users are navigating on the site through menus.

Special screens

The starting screen of the help system (Help35:Start_Here)

  • It is not listed in the list of help screens but you need to translate it because it is the initial screen your users will get when they will select Help → Joomla Help from the admin dropdown menu. 
  • The component Help allows you to define a menu item on this article and to use it as the home page of your server.

The screen with the list of help screens (Help35:Help_screens)

  • As explained before, the list of help screens will give you the complete list of the articles to translate and their key references.
  • It is not listed it-self in the list of help screens however the translation and links to this screen will help your users to find the help screen they are looking for.
  • To be more effective, you can replace in your translation the three columns 'Path in user interface', 'Component/View' and 'Language key' by only one column with the title of the help screen.
  • The component Help allows you to define a menu item on this article and to use it as the home page of your server.

The help screen for the component Help (Help35:Components_Help_User_Guide_AFUJ_English)

  • This screen is the help screen for the component Help. You can find the same information in the readme.txt file in the component package.
  • The key reference Components_Help_User_Guide_AFUJ_English of this screen is defined by the entry COM_HELP_TOOLBAR_HELP in the admin language file (en-GB.com_help.ini) of the component Help. Note: As defined in helpsites.xml the string 'Help:35' will be added to the key reference by the help system. 
  • Important: Initially, you get this screen remotely from the help server of the AFUJ (Association Francophone des Utilisateurs de Joomla!). This behavior is done by the word AFUJ in the key reference. If you want to use a local translated screen, you must remove the word AFUJ and change the entry in the language file to match with the key reference of your article. For example, the entry COM_HELP_TOOLBAR_HELP="Components_Help_User_Guide" will call the local article whose LTS Key Reference is Help35:Components_Help_User_Guide.

Categories

  • It is highly recommended to follow the organisation of the groups of the help screens list to create your categories: System, Users, Menus, Menu Item Types, Content, Components, Components Options, Extensions, Module Types. This organisation corresponds to the administration menus.
  • To manage more easily your articles, you can create subcategories, for example Banners as subcategory of Components for all articles whose LTS key reference is starting by 'Help35:Components_Banners_...'.

Images

  • It is easier to build for article images a folder hierarchy similar to the one used for categories organisation.
  • It is also recommended to use names easy to remember such as screenshot.png or toolbar.png. For example, the main screenshot for Article Manager could be stocked in images/help/content/article_manager/screenshot.png
Copyright © 2013 Joomla.fr - Association Francophone des Utilisateurs de Joomla! Tous droits réservés.