Joomla help system

What is the Joomla help system

The Joomla help system provides context-sensitive information to users logged in to the Administrator. Generally this is accessed by clicking on the help toolbar button located at the top right of almost all screens (Note that the toolbar button may be located elsewhere if you are not using one of the administrator templates shipped with Joomla). Clicking on this toolbar button will open a new browser window with information relevant to the screen on which it was pressed.

In addition, by clicking on the Help -> Joomla Help menu item, a list of help topics will be displayed. Clicking on any of these topic titles will bring up relevant information on the same page.

The help system can access information stored locally, as part of the Joomla system, or from a remote help server. It is fully multi-lingual and can be localised using one of the official translations, or by providing your own help information using a separately hosted help server. Third-party extension developers can integrate help information for components that they supply, either from the local component file structure, or from a remote help server.

How the Joomla help system works

In order for relevant information to be retrieved from the help server when the help toolbar button is pressed on a particular screen, it is necessary to pass a "key reference" from the toolbar button to the help server. For Joomla itself, these help screen key references are standardised and a complete list is available here. Extension developers are free to construct their own key reference scheme.

The key reference is used to construct a URL that provides the location of the help information. Available help servers are defined in an XML file which contains separate entries for each of the available languages. The default help server is set in Global Configuration and may be overridden by individual users in their user profiles. The list of available help servers can be changed by manually editing this XML file, which is /administrator/help/helpsites-MM.xml, where MM is the major and minor Joomla version numbers concatenated (eg. '16' for Joomla 1.6). For example, the helpsites file for Joomla 1.6 is /administrator/help/helpsites-16.xml

If no URL is specified then by default the help system will look for local help files in the /administrator/help/ln-LN/ directory.

The URL that will be accessed when a given help toolbar button is pressed, is constructed by merging the URL given in the helpsites XML file with the help screen key reference and other contextual information. This is achieved by including predefined substitution codes in the URL given in the helpsites XML file. These codes are replaced by the contextual information to give the URL that will be used by the help system.

In order for the URLs themselves to be fully localised, help screen key references are passed through the Joomla language system before being substituted into the URL.

For example, the Article Manager screen is associated with the key reference "JHELP_CONTENT_ARTICLE_MANAGER". This is actually a language key which is looked up in the currently loaded language files and in the case of British English the language file en-GB.ini contains the entry

JHELP_CONTENT_ARTICLE_MANAGER="Content_Article_Manager"

So the string "Content_Article_Manager" will be substituted into the URL. The helpsites-16.xml file defines the URL to be

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

This contains a number of substitution codes, including the key reference. In this example, the {major} and {minor} codes are replaced by the major and minor Joomla revision numbers respectively, so that the final URL that will be used will be

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

The complete list of available substitution codes is as follows

Code	Will be substituted by
{app}	Application name (eg. "Administrator" in the Joomla CMS back-end)
{component}	Component name (eg. "com_content" in the Article Manager)
{keyref}	Help screen key reference (after passing through the translation system)
{major}	Joomla major revision number (eg. "1" in Joomla 1.6).
{minor}	Joomla minor revision number (eg. "6" in Joomla 1.6)
{maintenance}	Joomla maintenance revision number (eg. "3" in Joomla 1.6.3).
{language}	Full language code (eg. "en-GB")
{langcode}	Language tag part of the language code (eg. "en" if the full code is "en-GB")
{langregion}	Region tag part of the language code (eg. "GB" if the full code is "en-GB")

There are no restrictions on the structure of the help URL as defined in the helpsites XML file. If you want to a Joomla instance as a help server then you can use the "traditional" access mechanism using a URL of the form

http://www.domain.com/index2.php?option=com_content&task=findkey&tmpl=component&keyref={keyref}.{major}{minor}

In this case you need to add the key reference into the "Key reference" field associated with each Joomla article. For example, if you want to provide help information associated with a key reference of "MyComponent_Manager" then you should enter the information into an article on the Joomla help server and enter "MyComponent_Manager" into the key reference field at the bottom right of the article editor screen. The title (or alias) that you give to the article does not matter as it is not used to retrieve the article when accessed via the help system.

Note that the help screen key references changed considerably between Joomla 1.5 and Joomla 1.6. The key references used in Joomla 1.5 can be found here.

Serving help screens from a MediaWiki installation

Starting with Joomla 1.6 the official English help screens are being served from the wiki at http://docs,joomla.org making it easier and quicker for the Joomla community to keep them accurate and up-to-date. However, there is a general issue with serving help screens from another website and that is that extraneous information, such as headers, footers, advertising modules, menu items and so on, tend to difficult to remove when presenting the information to the user.

Generally, the solution to this problem is to create a stripped-down template for the help server site that does not present any of this unwanted information, however this is not easy when the same website is being used for purposes other than serving help screens. The solution adopted from Joomla 1.6 onwards is to serve the help screens from the wiki via a proxy which uses the MediaWiki web API to pull data from the wiki and present it with a stripped-down template. The proxy happens to be a Joomla instance running a component developed for this purpose, but other solutions are also possible.

Local help files

Local help files are served from /administrator/help/ln-LN/ directory in the local Joomla file structure, where "ln-LN" is the current language code, rather than a remote web server. In order for local help to work it is necessary to ensure that every key reference in Joomla has a corresponding file in this directory. The name of each file must be a valid key reference after localisation by the Joomla language system. For example, the help screen associated with the Article Manager is determined by passing the language tag "JHELP_CONTENT_ARTICLE_MANAGER" through the language system as described earlier, to give the key reference "Content_Article_Manager". If the current language is British English then the help system will look for a file called either "Content_Article_Manager.html" or "Content_Article_Manager.xml" in the /administrator/help/en-GB directory. Note that because help files may use the ".xml" extension it is possible to write help screens using any XML dialect including DocBook XML.

Administrator help area

Under the menu item Help -> Joomla help you will see a general help area which lists all the available help screens on the left, with the content of the currently selected screen on the right. It is important to note that the content list is always generated by scanning the contents of the local help directory regardless of whether local or remote help is being used.

Since the name of each file in the /administrator/help/ln-LN directory must be a valid key reference, Joomla uses this fact to automatically construct a language tag "JHELP_CONTENT_ARTICLE_MANAGER" by removing the extension, uppercasing and adding a "JHELP_" prefix.

The language tag is then looked up in the currently loaded language files and in this case en-GB.ini contains the entry

JHELP_CONTENT_ARTICLE_MANAGER="Content_Article_Manager"

which gives the "key reference" as "Content_Article_Manager". This is then used to construct the URL which is used to retrieve the help screen. For example, if the help URL is

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

then this will result in the URL

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

in Joomla 1.6.x. If the help URL is not specified then the default help URL is /help/{language}/{keyref}

resulting in the file

http://www.domain.com/administrator/help/en-GB/Content_Article_Manager.html

being retrieved.

Adding help support to a component

<<Documentation for third-party developers wanting to include online or offline help in their components.>>