Actions

Difference between revisions of "Setting up a local help server"

From Joomla! Documentation

m (New page: {{inuse}})
 
m (adding categories)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{inuse}}
+
==What are help screens?==
 +
{{:What are help screens?}}
 +
==What is a local help server?==
 +
{{:What is a local help server?}}
 +
==Setting up a local help server==
 +
[[Image:CreatingLocalHelpServerNoSampleData.png|right]]
 +
===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: [http://joomlacode.org/gf/project/joomla/docman/?subdir=6]
 +
 
 +
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:
 +
{| class="wikitable"
 +
|-
 +
!Filename
 +
!Description
 +
|-
 +
|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 <tt>images.zip</tt>.  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 <tt><joomla-root>/images/stories</tt> directory of your help server.
 +
* Or upload the <tt>images.zip</tt> to your help server and extract it into the <tt><joomla-root>/images/stories</tt> 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:
 +
<pre>
 +
<joomla-root>
 +
+- images
 +
    +- stories
 +
        +- help_screens_1.5
 +
            +- buttons
 +
            +- headers
 +
            +- icons
 +
            +- screenshots
 +
            +- toolbars
 +
            +- userlevels
 +
</pre>
 +
===Step 5: Amend the database scripts===
 +
The default MySQL Table Prefix for a Joomla! 1.0 installation is <tt>jos_</tt>.  If your MySQL Table Prefix (which you noted in Step 1) is '''not''' <tt>jos_</tt> then you will need to amend all five of the <tt>.txt.sql</tt> files before they can be used.  To amend the files, open each one 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 <tt>jos_</tt> with your MySQL Table Prefix.  Repeat this for all five files.
 +
 
 +
===Step 6: Start phpMyAdmin===
 +
[[Image:CreatingLocalHelpServerPHPMyAdminImport.png|right]]
 +
Open [http://www.phpmyadmin.net 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 <tt>.txt.sql</tt> files and click the '''Go''' button.  Repeat this process for each file in turn.  The order in which you import them does not matter.
 +
 
 +
[[Image:CreatingLocalHelpServerPHPMyAdminFileToImport.png]]
 +
 
 +
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:
 +
<pre>
 +
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.x Help Screens: Extensions Menu
 +
Joomla! 1.5.x Help Screens: Tools Menu
 +
</pre>
 +
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 <tt><joomla-root>/images/stories</tt> 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 <tt><joomla-root>/administrator/help/helpsites-15.xml</tt>.  Open this file in a text editor and add the following line in the <tt><sites></tt> segment (replacing the ''url'' attribute with the URL of your local help server):
 +
<source lang="xml">
 +
  <site tag="en-GB" url="http://localhost/joomlahelp">Local Help</site>
 +
</source>
 +
For example, when this line is added to the standard <tt>helpsites-15.xml</tt> file distributed with Joomla! 1.5 it will look like this:
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
Save the file.
 +
===Step 2: Change Global Configuration===
 +
[[Image:CreatingLocalHelpServerSelectServer.png|right]]
 +
Log into the Joomla! Back End of your Joomla! 1.5 site, ''not the local help server''.
 +
 
 +
Go to <tt>Site -> Global Configuration</tt>.  Click on the <tt>System</tt> tab.  Find the <tt>System Settings</tt> group and within that the <tt>Help Server</tt> 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.
 +
 
 +
----
 +
<noinclude>This page was adapted from an [http://help.joomla.org/ghop/feb2008/task102 original document] produced during the [http://docs.joomla.org/Google_Highly_Open_Participation_Contest GHOP Contest] by igeoffi.</noinclude>
 +
[[Category:Server configurations]][[Category:Server setup local]]

Latest revision as of 17:13, 18 October 2012

Contents

What are help screens?

CreatingLocalHelpServerHelpButton.png

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

CreatingLocalHelpServerNoSampleData.png

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: [1]

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:

Filename Description
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
         +- help_screens_1.5
             +- buttons
             +- headers
             +- icons
             +- screenshots
             +- toolbars
             +- userlevels

Step 5: Amend the database scripts

The default MySQL Table Prefix for a Joomla! 1.0 installation is jos_. If your MySQL Table Prefix (which you noted in Step 1) is not jos_ then you will need to amend all five of the .txt.sql files before they can be used. To amend the files, open each one 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 jos_ with your MySQL Table Prefix. Repeat this for all five files.

Step 6: Start phpMyAdmin

CreatingLocalHelpServerPHPMyAdminImport.png

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.

CreatingLocalHelpServerPHPMyAdminFileToImport.png

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.x Help Screens: Extensions Menu
Joomla! 1.5.x 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

CreatingLocalHelpServerSelectServer.png

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.


This page was adapted from an original document produced during the GHOP Contest by igeoffi.