Setting up a local help server
From Joomla! Documentation
Revision as of 03:07, 8 July 2008 by Chris Davenport
- 1 What are help screens?
- 2 What is a local help server?
- 3 Setting up a local help server
- 3.1 Step 1: Installing Joomla! 1.0 to use as a local help server
- 3.2 Step 2: Download the latest help screens
- 3.3 Step 3: Extract files into a local directory
- 3.4 Step 4: Extract the help screen images
- 3.5 Step 5: Amend the database scripts
- 3.6 Step 6: Start phpMyAdmin
- 3.7 Step 7: Import the data
- 3.8 Step 8: Test
- 4 Configuring Joomla! 1.5 to use your local help server
What are help screens?
Throughout the Administrator Back-end there are help screens available to guide you in your use of Joomla! You access these screens by clicking on the Help button on the toolbar. Each screen in the Administrator calls a different help screen so the information you are presented with is relevant to what you are looking at in Joomla! In addition, the Help -> Joomla! Help menu option presents you with an alphabetical list of all the help screens. Some installed components might also include their help screens on this list.
By default, help screens are pulled from a remote server at help.joomla.org and displayed in a popup window. However, there is a setting in Global Configuration which allows you to change the location of the remote help server, or to pull help screens from a directory local to your website.
What is a local help server?
A local Joomla! help server provides the same (or similar) help screens as the default help server at help.joomla.org. There are many reasons why you might want to set up a local help server. For example, you might want to
- serve help screens from a server on your local intranet instead of help.joomla.org.
- customise the appearance of the help screens, for example, by adding a corporate logo or using a template that matches your own site style.
- use the English help screens as a starting point for a translation of the help screens into another language.
The disadvantage to running your own local help server is that you will have to remember to update the help screens occasionally and you will have to maintain and secure an additional site.
Setting up a local help server
Step 1: Installing Joomla! 1.0 to use as a local help server
Important note: The following instructions show how to set up a local help server to serve help screens for Joomla! 1.5 installations. Please note that the local help server itself is a Joomla! 1.0 installation. It is possible to run the local help server under Joomla! 1.5 but the help screens are not yet available in the required format.
Setting up a local help server is similar to installing Joomla! on your site. There is one major difference in the installation process though. In a normal Joomla! installation you would normally check the box “Install Sample Data” but when setting up a help server, do not be check this box off.
Important: Note the MySQL Table Prefix and the MySQL Database Name used when installing the Joomla! local help server. You will need to know these later.
Complete the installation process as normal. When you have finished the installation process you will need to delete the <joomla-root>/installation directory.
Step 2: Download the latest help screens
Download the latest copy of the help screens SQL dump from JoomlaCode: 
Note that the date forms part of the filename so ensure that you download the latest version.
Step 3: Extract files into a local directory
Extract the contents of the ZIP file downloaded from JoomlaCode into a directory on your local computer. You should see the following files:
|category.txt.sql||contains the SQL dump for the Joomla! Categories (mos_categories)|
|content.txt.sql||contains the SQL dump for the Joomla! Content Items (mos_content)|
|menu.txt.sql||contains the SQL dump for the Joomla! Menu (mos_menus)|
|modules.txt.sql||contains the SQL dump for the Joomla! Modules (mos_modules)|
|readme.txt||contains a brief description of the help screens package|
|section.txt.sql||ontains the SQL dump for the Joomla! Sections (mos_sections)|
|images.zip||contains all the screenshots, tool bar images, and icons used in the help screens|
Step 4: Extract the help screen images
One of the files you just extracted was images.zip. This contains all the screenshots, tool bar images and icons used in the help screens. Either:
- Extract it to a directory on your local computer, then upload all the files into the <joomla-root>/images/stories directory of your help server.
- Or upload the images.zip to your help server and extract it into the <joomla-root>/images/stories directory using the server control panel or a command-line instruction in an SSH session. This method requires appropriate access to your help server.
Once the upload is complete you should have the following directory structure:
<joomla-root> +- images +- stories +- 1_5_help_screens +- buttons +- headers +- icons +- screenshots +- toolbars +- userlevels
Step 5: Amend the database scripts
The five .txt.sql files must be amended before they can be used. Open each file in turn using a text editor. Do not use a word processing program. Using the Find and Replace or similar function, replace all instances of #_ with your MySQL Table Prefix (which you noted in Step 1). The default MySQL Table Prefix for a Joomla! 1.0 installation is jos_. Repeat this for all five files.
Step 6: Start phpMyAdmin
Open phpMyAdmin or a similar MySQL database management tool. Navigate to the database used by your Joomla! local help server. Go to the Import page.
Step 7: Import the data
Browse to each of the .txt.sql files and click the Go button. Repeat this process for each file in turn. The order in which you import them does not matter.
This completes the process of setting up your local help server.
Step 8: Test
Go to the front-end of your local help site. You should see a new menu item called Help Screens. If you click on it the menu should open up and you should see the following sub-menus:
Joomla! 1.5.x Help Screens: General Joomla! 1.5.x Help Screens: Site Joomla! 1.5.x Help Screens: Menus Menu Joomla! 1.5.x Help Screens: Content Menu Joomla! 1.5.x Help Screens: Components Menu Joomla! 1.5 Help Screens: Extensions Menu Joomla! 1.5 Help Screens: Tools Menu
Try clicking on some of these items and make sure that the help screens are displaying correctly. In particular, check that the screenshots and other images are being shown. If they are not then check the directory structure in the <joomla-root>/images/stories directory as it is important that this is set up correctly.
Configuring Joomla! 1.5 to use your local help server
Step 1: Edit the help server list
The list of available help servers is stored in XML format in the file <joomla-root>/administrator/help/helpsites-15.xml. Open this file in a text editor and add the following line in the <sites> segment (replacing the url attribute with the URL of your local help server):
<site tag="en-GB" url="http://localhost/joomlahelp">Local Help</site>
For example, when this line is added to the standard helpsites-15.xml file distributed with Joomla! 1.5 it will look like this:
<?xml version="1.0" encoding="iso-8859-1"?> <joshelp> <sites> <site tag="en-GB" url="http://help.joomla.org">English (GB) - help.joomla.org</site> <site tag="en-GB" url="http://localhost/joomlahelp">Local Help</site> </sites> </joshelp>
Save the file.
Step 2: Change Global Configuration
Log into the Joomla! Back End of your Joomla! 1.5 site, not the local help server.
Go to Site -> Global Configuration. Click on the System tab. Find the System Settings group and within that the Help Server field. This is a drop-down selection list. Click on it and select your new local help server from the list.
Save your changes to Global Configuration.
Step 3: Test
Go to any screen in the Joomla! Back End and click on the Help toolbar button. You should see the appropriate help screen in a popup window, served from your local help server.
As multiple Joomla! 1.5 sites can share the same local help server, you will need to repeat these steps for each Joomla! 1.5 site.