Help system/How the help system works

Each screen in the Joomla Administrator, or an extension to Joomla which has an Administrator area, is associated with a unique "key reference" which 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 which 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 (eg. '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 then 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 which 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 which is looked up in the currently loaded language files. 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 as the key reference. The helpsites-16.xml file defines the default URL for the British English (en-GB) help server 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, {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 that will be used will be

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

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

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.

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.