Help system/How the help system works

From Joomla! Documentation

< Help system

Each screen in the Joomla Administrator, or an extension to Joomla that has an Administrator area, is associated with a unique "key reference" that will be used to generate a URL from which the help information will be retrieved. Joomla internally converts the key reference to a URL which is presented in the help toolbar button. When this button is clicked a new browser window is opened with the generated URL.

In the case of the British English Joomla help screens, the URL points to the relevant page on the Joomla documentation wiki so that the help screens can be updated and maintained by the Joomla community. For Joomla itself, the key references are standardised and a complete list is available here. Extension developers are free to construct their own key reference scheme and provide their own help screens.

Available help servers are defined in an XML file that can contain separate entries for each installed language. 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 the XML file, which is /administrator/help/helpsites-MM.xml, where MM is the major and minor Joomla version numbers concatenated (e.g. '16' for Joomla 1.6). For example, the helpsites file for Joomla 1.6 is /administrator/help/helpsites-16.xml. The format of the helpsites XML file is described here.

If no URL is specified, by default the help system will look for local help files in the /administrator/help/ln-LN/ directory. The default Joomla distribution includes a complete set of British English (en-GB) local help files, but these are merely dummy files containing clickable links to the up-to-date online help screens that are ultimately served from the Joomla documentation wiki.

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 generate the final URL that will be used by the help system. A complete list of the available substitution codes may be found here.

It should be noted that In order for the URLs themselves to be fully localised, help screen key references are passed through the Joomla language translation 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 that is looked up in the currently loaded language files. In the case of British English, the language file en-GB.ini contains the entry:


So the string Content_Article_Manager will be substituted into the URL as the key reference. The helpsites-16.xml file defines the default URL for the British English (en-GB) help server to be;keyref=Help{major}{minor}:{keyref}

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

See Help system/Substitution codes for a complete list of the available codes.

There are no restrictions on the structure of the help URL as defined in the helpsites XML file, other than the obvious requirement that it must result in a valid URL after substitution has taken place. For example, if you want to use a Joomla 1.5 instance as a help server then you can use the "traditional" access mechanism using a URL of the form:;task=findkey&amp;tmpl=component&amp;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 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.

In summary, an internal key reference follows these steps in order to generate a URL that will be bound to the help toolbar button.

Help screen key reference  Language translation  Substitute into URL from helpsites.xml  Toolbar button

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 while those used in Joomla 1.6 can be found here.