Joomla! Documentation™

One of the aims in redeveloping the help system in Joomla 1.6 was to allow greater flexibility in the kinds of help servers that can be constructed. Prior to Joomla 1.6 it was necessary for a help server to be running on a Joomla 1.0 or 1.5 installation, unless you were prepared to do some tricky URL-rewriting in an htaccess file. The reason for this restriction was that the basic structure of help screen URLs was hard-coded and could not be changed without a core hack.

With the advent of Joomla 1.6, help screen URLs can be constructed in a very flexible way that does not restrict you to serving help screens from a Joomla installation. The following notes give information about how to serve help screens from a number of different platforms. The list is not exhaustive and you don't even need to run a content management system to serve the help files; they could even be static HTML (or XML) pages, for instance.

Serving help screens from a Joomla 1.6 installation

The basic idea when serving help screens from Joomla 1.6 is to add each key reference into the alias field of an article. Providing SEF support has been turned on, help screens can then be retrieved using the SEF alias for the article. Note that putting the key reference into the xreference field, analogously to the way in which help screens were handled in Joomla 1.5, will not work because no equivalent to the findkey method has been implemented in Joomla 1.6. Remember that the key reference in the URL will have been passed through the language translation system and so will most likely not be the same as the "key reference" found by looking at the PHP code for a particular screen.

It is likely that you will not want any navigation menus, headers, footers and other modules, adorning your help screens as these tend to distract the user. You could include an additional argument in the helpsites URL, such as "tmpl=component", which would load a sub-template of the default template, or "template=help", which would load a specially-written template called "help", but both of these methods suffer from a fundamental drawback: clicking on a link in the first help screen shown will take the user back to the default template for the site when the next page is displayed. Of course, you could assign the special "help" template to each of the help screen pages, but this is a somewhat labour-intensive task and it means that the help screen pages will use the special "help" template even when accessed via the main website.

For this reason it is recommended that you set up a separate Joomla instance specifically to serve help screens, then create a default template that does not include any unnecessary accoutrements.

Serving help screens from a Joomla 1.5 installation

It is entirely possible to serve help screens from Joomla 1.5 in the same way that you would from a Joomla 1.6 instance as described above. In other words, by arranging for each key reference to be the alias of the relevant help screen article. However, it is also possible to use the old findkey method that was used to access help screens in Joomla 1.5 and its predecessor, Joomla 1.0. This involves entering the key reference in the "Key reference" field in the Article New/Edit screen.

To access a Joomla 1.5 help server from Joomla 1.6 using the findkey method you need to set the URL in the helpsites XML file to have the following form:

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

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 this way.

Notice the use of index2.php rather than index.php so that the raw component (article) output is produce with minimal wrapping. However, subsequent clicks will return the user to the default template, so the only real solution is to create a default site template and reserve the site for help screens.

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 collaboratively keep them accurate and up-to-date. Pages in the wiki are retrieved via URLs which include the page title so that using key references to refer directly to pages in the wiki is straightforward.

However, the issue already described above for Joomla installations, where the output from the wiki includes navigation and other output that you would generally not want to include in a help screen, is also evident with the wiki. The solution recommended for Joomla installations where a separate MediaWiki installation with a stripped-down template ("theme" in MediaWiki parlance) is used to serve help screens, is much less than ideal because generally the idea of using a wiki in the first place is to encourage collaboration and a largely un-navigable user interface is hardly likely to achieve that.

The solution adopted for the British English help screens for Joomla 1.6 onwards is to serve the help screens 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.

The information flow is as follows. The help screen is initially requested by a user logged in to an instance of the Joomla Administrator. The request is passed to the com_help component running on the proxy at http://help.joomla.org/proxy/. The component parses the request to determine the key reference and uses that to make a request for page data from the wiki at http://docs.joomla.org using the MediaWiki Web API. The wiki returns the data requested as an XML file and com_help then extracts the data it requires, performing some transformations such as replacing relative links and references to absolute ones, removing extraneous information such as tables of content and categorisations. It then constructs a web page, passing it through the default template which adds HTML headers and footers, copyright and license data, then outputs it to the user's web browser.