-------------------------
How to use "Guided Tours"
-------------------------


1. Important files and folders
==============================

/gui/register.js
This file is used to initialize the plugin. Developers should register tours here.

/gui/tours
Place your tours in this folder.

/gui/lang
Contains the PO file for register.js

/gui/lang/tours
Contains PO files for tours

/gui/i18n
Contains a build.xml and POT files.



2. How to register a tour
=========================

This is very simple. Open the file "/gui/register.js" and add the following:

Tour.register({
    id: "Tour1",
    title: _("Tour #1"), // underscore function gets proper translation
    src: "tour1.xml", // links to /gui/tours/tour1.xml
    plugin: NAME // just always add this
});

The "id" is used to uniquely identify the tour. "Title" is the translated title.
"src" defined the location of the tour definition (JS or XML file).
You have to add the plugin name - the easiest way is to use the (magic) global variable NAME.
The plugin name is required to use the proper i18n domain when the plugin is started.

A tour is loaded and started by "Tour.load(id)" (in register.js).
If you want to start a tour via the FireBug console, for example, you have to use the full namespace:

ox.api.help.Tour.load(id);



3. How to define a tour
=======================

An example:

<tour>

    <module>mail</module>
    <view>mail/list/unthreaded</view>
    
    <step selector="#ox-side-view" align="right"><![CDATA[
        <h1>Step #1</h1>
        <p>This is step #1</p>
    ]]></step>
    
    <step selector="#mail\.list" align="left"><![CDATA[
        <h1>Step #1</h1>
        <p>This is step #1</p>
    ]]></step>
    
</tour>

The tour switches to module "mail" and to view "mail/list/unthreaded" on start. It has two steps.
The selector is a CSS selector used to highlight a specific element.
"align" positions the tour popup. Possible values are be: top, right, bottom, and left.
When using HTML markup, you have to use CDATA sections - otherwise the markup gets lost.



4. How to translate a tour
==========================

Call the "pot" target of i18n/build.xml, e.g. "ant -f i18n/build.xml pot".
Afterwards, you will see two files in /i18n:
* com.openexchange.help.pot
* com.openexchange.help.tours.pot
These files can be used to translate the tours. The corresponding PO files (e.g., de_DE.po) must be
placed in /gui/lang or /gui/lang/tours respectively.




