Create Guided Tours for TYPO3 Backend Users

Because reading manuals is normally hard and boring, most people do not read manuals. Therefore many websites and products offer to take a tour through the main features and options. With the extension “guide”, this is now also possible for TYPO3 in your own modules.

The extension “guide” provides a possibility to create a guided tour for your TYPO3 backend module. The two prerequisites are that you provide the configuration for the guided tour and the extension “guide” is installed.

Guided Tours Module

Let’s start with the latter one…

Install EXT:guide

Via EM

Since Sept. 21st there is a new 8LTS compatible version available via TER. Thanks to Thomas Deuling for pushing this release out to be available for this post. The extension can be installed as any other extension via EM:

Open the extension manager

Update the extension list

Search for the extensionkey “guide”

Install and activate the extension

Via composer

The github repository must be added to the repository section of your composer json. This is needed because EXT:guide is not (yet) available via packagist.

Register the tour via php

Another option to provide the configuration is register the tour via php. This possibility enables the usage of yaml files.

Default

1

2

3

4

5

6

7

8

9

\Tx\Guide\Utility\GuideUtility::addTour(

'TemplateModule',// Tour identifier

'LLL:EXT:guide/Resources/Private/Language/BootstrapTourTemplateModule.xlf:tx_guide_tour.title',// Title of the tour

'LLL:EXT:guide/Resources/Private/Language/BootstrapTourTemplateModule.xlf:tx_guide_tour.description',// Description of the Tour

'web_ts',// Module key of the tour

'module-web_ts',// Icon-identifier

'EXT:guide/Configuration/Tours/'// Base path for the yaml files

);

Another advantage of this way is, that it is possible to provide a different tour for each major TYPO3 version, keeping the possibility to overwrite the yaml config with Page TSconfig settings like described above.

If the tour is correctly registered, it will show up in the tour overview, like in this screenshot:

Configuration of a tour

All configuration is collected in the TSconfig node mod.guide.tours. You define your tour in a sub-node like myModule.

Settings for the module “Guided Tours”

Default

1

2

3

4

5

6

7

8

9

10

mod.guide.tours.myModule{

title=My Advanced Module

description=Iwill show you how it works

moduleName=web_myModule

iconIdentifier=module-mymodule-extensionicon

steps{

# In this node, you define the steps of your tour

}

}

This data is displayed in the tour overview of the “Guided Tours” module.

If you start a tour and you get the error “Not Found — The requested URL /typo3/undefined was not found on this server.”, the module name is not correct or the extension providing the module is not yet installed.

Step definition

The node “steps” is a numeric TSconfig array. Each step is a number and contains several definitions, which fix the layout and the content.

Content

The content is packed into the two options “title” and “content”. These are self explanatory … The title contains a header, which is displayed in bold font and the content explaining the element.

Placement

You can also define where the popover is placed within the module. The “selector” is a jQuery selector, which serves as the anchor of the content. It must be unique in the DOM of the module. The popover with the content and step navigation will be shown next to it.

With the option “placement” you define, where the popover is shown in relation to the selector. Possible values are “top”, “bottom”, “left”, “right” and “auto”.

If you set the “showArrow” option to true, the popover will show a small arrow in the direction of the selector.

Actions

With the options “show”, “shown” and “hide” you can set what will happen when a step is executed. “Show” is executed when the display process starts. “Shown” is executed when the display of the popover is finished. And finally “hide” is taken into account, when you click the “next” button in the popover.

Possible actions are “addClass”, “removeClass” and “openSelectBox”. All three take again a “selector” as an (required) option. Additionally you can provide a class name, which will be added or removed from the selector.

The next action is helpful, if you want to concatenate another tour after the current one is finished. You need to provide the name of the next tour and the step where is should start. Usually this will be number “0”, but later steps are also possible.

Here an example of a step definition:

Default

1

2

3

4

5

6

7

8

9

10{

selector=#groupdelegation-overlay

title=GroupDelegation Module

content=Welcome tothe Module"Groupdelegation"

placement=left

showArrow=true

}

“Live” examples of guided tours

The guide extension comes with several tours for the “standard” TYPO3 backend, like the page or the template module.

Conclusion

This is a great way to introduce backend users to (new) functionality of modules. It is quite easy to configure.

Many modules depend on user generated data. Without such data, it is IMHO not possible to provide a full tour. This data must be provided by the admin or must be imported while installation via ext\_tables+adt.sql file. The default data then must be deleted by an admin in order not to interfere with live data.

Amazon – Affiliate

If you like this blog and want to support me, you can use the following Amazon Logo to order products there. For each ordered product, I will receive a small commission. There will be no additional costs for you,