Help system/Adding a help button to the toolbar

If you look at the code for almost any of the Joomla core components, you will find that the way to add a help button to the component toolbar is a call like this one from the Banners component:

JToolBarHelper::help( 'JHELP_COMPONENTS_BANNERS_BANNERS' );

The single argument is an unlocalised key reference that will first be passed through JText::_() to obtain a localised key reference that will be substituted to form the URL of the help page to be displayed. It is customary to assemble the toolbar in the view.html.php file of the component view.

However, this will call a help screen on the default help server only, so it is really only of use in the core components. For third-party developers wanting to add help screens to their extensions it is necessary to use some of the additional arguments to JToolBarHelper::help.

Third-party developers have a variety of options regarding the location of their help files and the help system is designed to be flexible enough to support the vast majority of requirements. The first step in adding help support to your Joomla extension is to decide where you want the help files to be located. In particular, are the help files going to be distributed and installed along with the extension or are they going to be hosted on a website elsewhere?

Local help

If help screens are included in the extension installation then the second argument to JToolBarHelper::help should be set to true. For example, to force the use of local component help files, use code like this:

JToolBarHelper::help( 'MY_COMPONENT_HELP_VIEW_TYPE1', true );

This call will look for the language key MY_COMPONENT_HELP_VIEW_TYPE1 and use the value found, if any, to construct a local file path to the help file. For example, if the component language file /language/en-GB/en-GB.com_my_component.ini contains the key-value pair

MY_COMPONENT_HELP_VIEW_TYPE1="view_type1"

then the file path constructed will be

/components/com_my_component/help/en-GB/view_type1.html

Advanced notes

• the file extension can be either .html or .xml, with .html as the default. To use a .xml extension, for example, if you want to use DocBook format for your help screens, then add the extension in the language file. For example, if the language key-value is MY_COMPONENT_HELP_VIEW_TYPE1="view_type1.xml" then the file path constructed will be /components/com_my_component/help/en-GB/view_type1.xml.
• you can specify a different file path at the component level by including a "helpURL" parameter in your component parameters.
• you can override individual help screens at the site level by adding language strings with the language override system.

Remote help

If you are developing a Joomla extension and you want to host your help screens on your own server, it is possible to completely override the URL generated by Joomla, giving you complete control over the location of the help files. For example, suppose you have a help server located at http://www.example.com/en-GB/help-server and you to host all your (British English) help files there. Then

$help_url  = 'http://www.example.com/{language}/help-server';
JToolBarHelper::help( 'MY_COMPONENT_HELP_VIEW_TYPE1', false, $help_url );

with language key-value pair

MY_COMPONENT_HELP_VIEW_TYPE1="view_type1"

will generate http://www.example.com/en-GB/help-server/view_type1 as the help screen URL. Note that this is language-aware so that a French site visitor will be presented with http://www.example.com/fr-FR/help-server/view_type1_in_French as the help screen URL given that the language key-value pair in the French component language file (/language/fr-FR/fr-FR.com_my_component.ini) is set up as

MY_COMPONENT_HELP_VIEW_TYPE1="view_type1_in_French"

Since there is complete freedom in the way that help screen URLs are constructed, it is not necessary to host the help screens on a Joomla instance (which was the case with Joomla versions prior to version 1.6). Help screens may be regular web pages, wiki pages, forum pages/threads/boards, social network groups, or anything else you can think of.

Please note that the Joomla documentation wiki (http://docs.joomla.org) is not to be used for hosting third-party extension help screens. Pages created for that purpose will be deleted.

Advanced note

Although it is possible to include the name of the component in the help screen URL, there are some situations where you might want to override the component name automatically determined by Joomla. For example, if you have multiple components as part of a package, but you want to them all to refer to help screens as if they were part of a single component. In such cases, it is possible to pass a fourth argument to JToolBarHelper::help which will override the component name. For example,

JToolBarHelper::help( 'MY_COMPONENT_HELP_VIEW_TYPE1', false, '', 'com_mycomponent' );

with the help URL specified as

http://www.example.com/{component}/{keyref}/{langcode}

this will generate the URL (for English site visitors)

http://www.example.com/com_mycomponent/view_type1/en

See also

• Format of the helpsites XML file.
• Substitution codes for use in help screen URLs.
• JHelp::createURL
• JHelp::createSiteList