Introduction
The current Joomla! help system has worked remarkably well over the years and has remained essentially unchanged since Mambo days. However, there are some inherent difficulties with it that lead to consideration of an updated help system.
- The back-end help server must be either a (remote) Joomla! installation or the local Joomla! filesystem. Non-Joomla! back-ends are not easily supported.
- There is no flexibility in the interface to the remote help server. The URL used to access the remote system is fixed and would require a core hack to change it.
- Similarly there is no flexibility in the interface to the local help files.
- The table of contents page is generated from the directory of local help files that happen to be present, plus those added from third-party component help directories. A new help file added to a remote help server is effectively invisible.
- Local help files can only be updated during the normal update cycle for Joomla! itself, whereas experience has shown that the development of help information works to a different cycle to that of the code.
- Arbitrary back-end help servers may be supported. In particular, we will be able to move the official help screens from help.joomla.org (a Joomla! instance) to docs.joomla.org (a MediaWiki instance) where they will be easier to maintain. This is perhaps the most significant reason for wanting to change the current help system as it makes it easier for the Doc WG to bring the help screens into the modular, re-usable documentation methodology that we are moving towards for the bulk of the documentation.
- All Joomla! produced error and warning messages become potential entry-points into the documentation. This will allow the user to obtain context-sensitive help with specific error conditions and by using a wiki the Dev and Doc WG can evolve the support given in the light of experience with the software.
- Flexible support for multi-language back-end help servers. We will have a range of options for handling multi-lingual help that are not be tied to a specific technology.
- All these same capabilities will be available for extension developers to exploit if they wish to.
- No changes are required to key references in the current code base.
- Existing help servers can continue to be used if required.
Help sites are currently listed in administrator/help/helpsites-15.xml, which can be thought of as a registry of available help sites. Currently this contains just the one entry:
Code: Select all
<?xml version="1.0" encoding="iso-8859-1"?>
<joshelp>
<sites>
<site tag="en-GB" url="http://help.joomla.org">English (GB)</site>
</sites>
</joshelp>
The intention is that the help sites registry will contain information about all help sites including those used by the installed extensions.
Properties
Each registry entry has the following properties:
- key is a unique identifier string which can be used to reference a specific registry entry. All keys beginning with an underscore are reserved for use by Joomla! itself.
- type is a string indicating the type of the registry entry. The following types have special meaning:-
joomla means that the help site contains full help information for Joomla! These sites are the ones that will be listed as help sites in Global Configuration and the User Manager. Help sites that provide support for extensions will use their own type string. - method is a string containing the name of the method used to access the help site. The currently supported methods are:- file to access files on a mounted filesystem; http to access web pages via the HTTP protocol. Support for other methods may be added in the future as required.
- name is a string describing the help site and is for display purposes only.
- resource is a string most likely containing a path or URL that will be used to access pages on the help site. A resource string may contain substitution codes that will be replaced before it is used (see later).
- selected is a boolean which indicates the preferred or currently selected help site amongst entries with a given type. For example, the default Joomla! help site selected in Global Configuration will have the selected property set to true while others with type = joomla are set to false.
JHelp manages the repository of information about help sites and is the API for access to the registry. The JHelp class requires the following methods:-
- addSite ( $key, $type, $name, $resource, $method='http' )
Adds a site to the registry. - removeSite ( $key )
Removes a site from the registry. - createUrl ( $key, $id, $extver='' )
Returns the URL (or path) to access the resource using the given reference. This method already exists but will need to be extended to support substitution codes in the resource name and the addition of a $key to specify which help site to use. The optional $extver parameter is so that third-party extension developers can pass an extension version string for the {extver} substitution code. - createSiteList ( $type=null, $selected=false )
Returns an array of help sites which match the type requested. If $type is empty or null then all help sites will be returned. In effect, the type forms a namespace for help sites and extension developers should carefully select a unique name, probably based on the name of their extension, to avoid help site name collisions. This method already exists but needs to be modified to allow selection by type. If $selected is true then only help sites with the selected property set to true will be returned. Otherwise, help sites with selected property in either state will be returned. - selectSite ( $key )
Sets the select property of the entry specified by $key to true. The select property of all other entries with the same type string as the one specified by $key will be set to false.
The following codes (at least) should be available for substitution into the resource string by the createUrl method.
- {id} is a unique identifier for the help resource. For example, in the old-style key reference "screen.installer.15", the "screen.installer" part would be regarded as the {id}. This is just the $id parameter passed to createUrl.
- {version} is a shortened version of the for Joomla! version number comprising the major and minor version numbers with no dot separator. For example, for Joomla! 1.6.x {version} would be "16". This is backwards compatible with the current version suffix string.
- {major} is the major version number. For example, for Joomla! version 1.6.2 {major} would be "1".
- {minor} is the minor version number. For example, for Joomla! version 1.6.2 {minor} would be "6".
- {maintenance} is the maintenance release number. For example, for Joomla! version 1.6.2 {maintenance} would be "2".
- {language} is the ISO-defined language code for the current language. For example, "en-GB" is used for British English.
- {langcode} is the short language code consisting of the first two characters of the ISO-defined language code for the current language. For example, if the ISO language code is "en-US" then {langcode} would be "en".
- {client} is the Joomla! client name ("site" for the front-end, "administrator" for the back-end, "installer" for the installer).
- {extver} is the version of the extension (where relevant). This is just the $extver parameter passed to createUrl.
The following two entries would give backwards compatibility with the current help server options.
The following example illustrates how local help files could be located anywhere on a local area network using a mounted filesystem.key = “local”
type = “joomla”
method = “file”
name = “Local help”
resource = "administrator/help/{language}/{id}.{version}.html"
key = “joomla”
type = “joomla”
method = "http"
name = “English (GB) – help.joomla.org"
resource = "http://help.joomla.org/index2.php?optio ... }.{version}”
This example illustrates how the MediaWiki at docs.joomla.org could be used as a help server back-end. This example uses language pseudo-namespaces to serve multi-lingual help.key = “lan”
type = “joomla”
method = “file”
name = “LAN file server”
resource = “/mnt/net41/joomla/help/{language}/{id}.{version}.xml”
Another approach to multi-lingual help is to have separate help server instances each in its own subdomain. [Can the full ISO language code be used as a subdomain name? Would we want to do that anyway?]. This is the preferred approach for us to produce a multi-lingual documentation site.key = “wiki”
type = “joomla”
method = “http”
name = “Joomla! official documentation site”
resource = “http://docs.joomla.org/{langcode}:{id}_{version}”
We would implement a hard redirect of http://en.joomla.org/docs to http://docs.joomla.org using mod_rewrite.key = “multi-lingual wiki”
type = “joomla”
method = “http”
name = “Multi-lingual documentation site”
resource = “http://{langcode}.joomla.org/docs/{id}_{version}”
For an example of a set of multi-lingual MediaWiki pages using this method see http://en.wikipedia.org/wiki/Spreadsheet
For more information on multi-language support in MediaWiki see, http://en.wikipedia.org/wiki/Help:Interlanguage_links
http://www.itia.ntua.gr/~anthony/tmp/mu ... wikis.html
Core parameter types
helpsites
The core parameter type “helpsites” should be modified as follows:-
- default attribute will be used as the id parameter in a call to createSiteList.
- helptype is a new attribute that will be passed as the type parameter in a call to createSiteList.
- selected is a new attribute that will be passed as the selected parameter in a call to createSiteList. This attribute is optional.
Code: Select all
<param name=”helpsites” type=”helpsites” helptype=”com_musthave” default=”” label=”Help sites” description=”Select a help site” selected=”false” />
While not strictly necessary, a new core parameter type, called “help”, is proposed. This will allow extension developers to add a button to any parameter screen for access to extension and context-specific help information. It has the following parameters:
- name is the field name.
- type is 'help' to indicate that this a help parameter.
- helpsite will be passed as the key parameter in a call to createUrl.
- helpid will be passed as the id parameter in a call to createUrl.
- label will be used as a label for the button.
- description will be used as alternative text for the button.
Code: Select all
<param name=”helpwithsomething” type=”help” helpsite=”com_musthave” helpid=”Help_with_parameter_x” label=”Help me” description=”Click me for help with something” />
Extension Developers
Extension developers can add information about their own help servers into the registry using the $type field as a kind of namespace. Access to help for an extension can then be supported in the same way as with Joomla! itself, but without involving the official Joomla! websites. Help sites can be added to the registry using the addSite method in the com_install function (and removed using the removeSite method in the com_uninstall function).
However, a straightforward extension to the installer XML would simplify this for developers. For example, the following XML fragment could easily be supported to add a help site during component installation.
Code: Select all
<helpsites>
<helpsite key=”com_musthave” type=”com_musthave”>
<name>Must have component help site</name>
<resource>http://musthave.com/help/{id}.{extver}</resource>
</helpsite>
</helpsites>
Just as a user clicking on a help toolbar button can be thought of as a cry for help, the presentation of a warning or error message could be the precursor to such a cry. By adding a link in the message presented, the user can be given the opportunity to request help with the specific condition. Additionally, community experience with a particular error condition can be fed into the resource that is linked to by the error message so that feedback to the user can be improved over time.
Adding the link is easy to achieve programmatically but requires that each error/warning condition have a unique identifier that can be used to construct the URL. JHelp::createUrl is called to create the link, passing this unique id into the {id} substitution code. The following format for the id string is suggested:
Code: Select all
<package>_<subpackage>_<uid>
- <package> is the name of the package where the error/warning occurred. This should match the @package name in the phpdoc tags for the code where the error/warning occurred. Extension developers must not use the Joomla! package names (which should therefore be regarded as "reserved").
- <subpackage> is the optional name of the subpackage where the error/warning occurred. This should match the @subpackage name in the phpdoc tags for the code where the error/warning occurred. Extension developers are free to use subpackage names which match those used in Joomla! itself.
- <uid> is a unique numeric identifier for the error/warning condition. This identifier must be unique within the package. In other words, the same identifier must not be used in different locations within the same package. The <package><uid> together should form a globally unique identifier. The code 99999 has the special meaning of “not yet allocated”. Prior to a release, the codebase can easily be swept for occurrences of this code so that proper codes can be assigned. Code numbers are allocated sequentially and are not re-used.
Code: Select all
JFramework_Utilities_1234
By adding each wiki error page to a special “error” category, the wiki will automatically maintain an alphabetical contents page so that it becomes easy to assign the next sequential error code.
Tooltips
An interesting but probably impractical extension to this idea is to store tooltip text in the back-end help server and have it retrieved, perhaps via AJAX, as the user hovers over the relevant region. This would be useful because the tooltip text could then be transcluded into the help screen text. This would help to ensure that tooltip and help screen text is kept up-to-date with the minimum of effort. Raw wiki text can be retrieved programmatically using the MediaWiki API which returns it with a minimal XML wrapper. The tooltip text chunks might also be re-used elsewhere in the documentation.
The MediaWiki API is described here: http://en.wikipedia.org/w/api.php
Admin help page
At present the user is presented with an alphabetical table of contents generated from all the local help files, together with local help files found in all the installed components. Whilst quite clever, this is not all that helpful as it is merely listing the help screens available from individual screens in the software. It would be nice to find a way to present task- or goal-orientated information instead.
The suggestion here is that the left-hand list merely comprises a list of registered help sites that are currently selected. Clicking on any of the links will bring up a page with a standard id, perhaps “Start_here”. This page must be present on all registered help sites for this to work. The content of this standard page can be anything but in the case of the Joomla! help sites should be lists of tasks or goals, perhaps grouped by user type (eg. editor, publisher, administrator, etc). Extension developers can choose to organise their help sites in other ways if they choose.
The top item on the help sites list should always be the help sites for Joomla! itself, followed by registered extension help sites. When the help page is first presented, the “Start_here” page for Joomla! will therefore be shown.
Impact on performance
Having the createUrl method retrieve the resource from the help sites registry could have a performance impact depending on how the registry is implemented. However, the resource can easily be cached to mitigate this.
The proposal regarding tooltips clearly adds network latency to the time taken to show tooltip text to the user. Whether this will be acceptable is uncertain.