Issuu on Google+

Setting up a local Joomla Proxy Help Server

Version 1.0.0 12 August 2009


Setting up a local Joomla Proxy Help Server Table of Contents Introduction......................................................................................................................................3 Requirements...................................................................................................................................3 Installation.......................................................................................................................................4 Configuration of the proxy component............................................................................................5 Configuration of Joomla clients.......................................................................................................5 Substitution codes............................................................................................................................5

This document is made available under the terms of the Joomla Electronic Documentation License:  http://docs.joomla.org/JEDL. Copyright © 2009 Chris Davenport.  All rights reserved.

Version 1.0.0

12 August 2009


Setting up a local Joomla Proxy Help Server Introduction This manual provides instructions on how to set up your own help server to deliver help screens to  Joomla   users   from   your   own   infrastructure.     This   is   most   likely   because   you   want   to   provide  translations of the English Joomla help screens without using the Joomla infrastructure. This manual only covers the more recent method of delivering help screens from a MediaWiki  instance proxied via a Joomla instance.  The earlier method of serving help screens directly from a  Joomla instance is not covered.  The new method is backwards­compatible with the old method. When a user clicks on the Help toolbar button in the Administrator application, Joomla will open a  browser pop­up window, passing to it the URL of the appropriate help page.  This URL contains a  “key reference” which is a unique identifier associated with the particular screen where the toolbar  button is located and which sets the context so that the correct help screen can be displayed. In early versions of Joomla the URL was Joomla­specific and when directed at a Joomla instance  the key­reference passed in the URL was used as a search key to retrieve the relevant Joomla article.  Since the structure of the URL was hard­wired into Joomla itself the help server had to be another  Joomla instance (unless you did something clever with mod_rewrite).  During 2008 the creation and  maintenance of the English help screens was moved to the wiki at  http://docs.joomla.org  and it  became clear that it would be better to serve help pages from the wiki itself rather than copying  them, manually, to a Joomla instance. In the latest versions of Joomla the structure of the URL is specified in an XML file that can be  altered by a system administrator and so the help server no longer needs to be another Joomla  instance   and   can   be   anything   at   all,   including   a   wiki   such   as   the   MediaWiki   used   on  http://docs.joomla.org. There is another problem that arises when help pages are served directly from a Joomla instance or  a MediaWiki instance.  Both Joomla and MediaWiki employ a template or theme system that allows  the   output   to   be   customised   with   additional   material   such   as   a   header,   a   footer,   and   various  navigation menus.   These are generally not required and are rather a nuisance in a help screen,  which  should  ideally contain the page content only, without these additional distractions.   It is  relatively straightforward to get the page contents only from Joomla or MediaWiki for the first page  that is requested.  However, if the user clicks on a link to another page on the same server then these  additional modules will once again appear. This can be solved by making the default template/theme be a minimal one that ensures that only  the content required for the help screens is delivered.  This is a perfectly reasonable approach, but if  the help server is also required to serve non­help screen pages to public visitors it is simply not  practicable.

Requirements To set up a local proxy help server you will need the following: 1. A MediaWiki installation to host the help screens. 2. A dedicated Joomla 1.5 (or later) instance to act as the proxy help server.   If this can be  Version 1.0.0

12 August 2009


Setting up a local Joomla Proxy Help Server installed so that the  localhost interface can be used to communicate with the wiki, then it  will be a bit more efficient. 3. Joomla clients must be running Joomla 1.5.15 (???) or later. The current proxy help component is only suitable where the help screens are being served from a  MediaWiki instance and the proxy is running on Joomla.   The proxy server must be a dedicated  Joomla instance as the default template will be a minimal one that is unlikely to be suitable for  general use. User requests are directed to the proxy server which analyses the request URL and requests the  relevant page from the wiki using the MediaWiki web API.  This ensures that only the page content  is retrieved and does not pass through the MediaWiki theme system.  The proxy also automatically  replaces any embedded links to other pages on the wiki with links to the proxy server.  Thus, if a  user clicks on a link in the help screen it will again be processed by the proxy and be delivered  without any additional theme elements.   Furthermore, any links to pages that have not yet been  written are automatically removed by the proxy so that users are not presented with such links. When   calling   for  help,  Joomla  constructs  the  URI  of a  help  page and  opens  a  popup  window  containing the results of a request to that URL.  This is generally expected to be in HTML format,  although XML is also supported.  Although the server and path are configurable, the query part of  the URI is hard­wired into the Joomla code.  This effectively means that help pages must be served  from a Joomla instance (although it is possible in theory to use mod_rewrite to rewrite URI's on­ the­fly so that some other application could be used to serve help pages). The proxy help component is installed on the help server so that requests for help screens from  Joomla clients are satisfied by pulling an equivalent page from the wiki rather than serving a Joomla  article directly. Links contained in the page retrieved from the wiki are modified by the proxy help component so  that they point to the proxy help server rather than the wiki.  Furthermore, links to pages that have  not yet been written are completely removed so that users who are looking for help do not see these  unwritten page links.

Installation Help   screens   are   served   from   a   MediaWiki   instance   and   so   you   will   need   to   have   installed  MediaWiki on your server.  Installation instructions are available on the MediaWiki website: http:// www.mediawiki.org. The proxy runs on a Joomla 1.5 instance, so you will need to have installed Joomla 1.5 on your  server also.  The wiki and the proxy do not need to run on the same physical server, or even be in  the   same   domain,   but   if   they   can   communicate   via   the   host's   localhost   interface   the   overhead  associated with using a physical network interface can be avoided. The proxy help component, com_help, is installed using the regular Joomla extension installer.  You  will need to configure the component after you have installed it (see below). There is also a minimal help screens template available that does not include any module positions  and is suitable for rendering Joomla help screens.  It includes a CSS stylesheet that is customised for  Version 1.0.0

12 August 2009


Setting up a local Joomla Proxy Help Server Joomla help screens.   This template is also installed using the regular Joomla extension installer.  After you have installed the template you should make it the default template for the site.

Configuration of the proxy component After   installation  the  proxy help  component must be configured.   To configure  the proxy   help  component use the following procedure: 1. Log in to the Joomla Administrator. 2. Click on the Components → Joomla Proxy Help menu item. 3. Click on the Parameters toolbar button. 4. Enter the URL of the MediaWiki instance that will be serving help pages.   For example,  “http://docs.joomla.org”.  Do not add a trailing slash. 5. Enter   the   maximum   number   of   wiki   page   redirects   that   will   be   followed   automatically.  Following   redirects   automatically   introduces   a   delay   in   serving   the   help   page.     If   the  maximum is set too low then the user will be presented with a redirection link that they will  need to click on to reach the help age.  The default is 5. 6. Click Save.

Configuration of Joomla clients Joomla clients running Joomla 1.5.15 or later, or Joomla 1.6.0 or later include the necessary code to  access help screens via the proxy.  Joomla versions prior to 1.5.15 are unable to construct the proxy  URLs required to work with the proxy. Each Joomla client must be configured with the URL of the proxy help server.  To do this you need  to edit the following file: administrator/help/helpsites-16.xml

For a new help server you need to add a <site> element with the appropriate language tag attribute.  The url attribute must have the following format: http://<hostname/path>/index.php?option=com_help&amp;keyref=<page-title>

where: <hostname/path> is  the fully­qualified domain name and path to the Joomla proxy  help  server; and <page­title> gives the structure of help screen page titles on the wiki.  This could be just the  key reference, in which case you would use “{keyref}”, but can also include other elements  such as the Joomla version number.  See the section on Substitution codes for more detail.

Substitution codes The following codes may be embedded in help­site URLs to be automatically replaced as indicated:

Version 1.0.0

12 August 2009


Setting up a local Joomla Proxy Help Server Substitution code Description {keyref}

Unique “key reference” indicating the page for which  help is required.

{language}

Full ISO language code, eg. “en­GB”.

{langcode}

Language code without the region code. eg. '”en”.

{langregion}

Region part of the language code.  eg. “GB”.

{major}

Major part of Joomla version number.

{minor}

Minor part of Joomla version number.

{maintenance}

Maintenance part of Joomla version number.

For   example,   the   Module  Manager  has   a  key  reference  of  screen.module  so  in   Joomla  1.5   the  relevant help page might be at: http://help.joomla.org/help­server/index.php?option=com_help&keyref=screen.module.15 so a suitable set up in helpsites­16.xml would be http://help.joomla.org/help­server/index.php?option=com_help&keyref={keyref}.{major}{minor}

Version 1.0.0

12 August 2009


Setting up a local Joomla proxy help server