Skip to content
  • Documentation >
  • Administration >
  • Back office >
  • Integrated help >
  • Configure product tour

Configure product tour scenarios

You can configure the product tour scenarios to adapt it to your project needs, covering different onboarding scenarios.

Product tour scenarios are configured using YAML configuration files. Configuration is SiteAccess-aware, allowing you to create separate onboarding experiences for different back offices in multisite setups.

For more advanced customization cases that require PHP code, see the integrated help's RenderProductTourScenarioEvent.

Use the default provided configuration, available in config/packages/ibexa_integrated_help_tours.yaml, as a starting point that you can adjust to your needs.

Configuration structure

Product tour scenarios are configured under the ibexa.system.<siteaccess>.product_tour key. Each scenario has a unique identifier and contains steps, which in turn contain blocks.

Basic configuration structure of a scenario:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
ibexa:
    system:
        <scope>>: # For example, admin or admin_group
            product_tour:
                <scenario_identifier>:
                    type: <general|targetable>
                    user_groups_excluded: [<user_group_remote_content_id>, ...]  # Optional
                    steps:
                        <step_key>: # Scenario step
                            step_title_translation_key: <translation_key>
                            background_image: <image_path>  # Only for general type, optional
                            target: <css_selector>  # Only for targetable type, required
                            interaction_mode: <null|clickable|draggable>  # Only for targetable type, optional
                            blocks:
                                - type: <block_type>
                                  params:
                                      # Block-specific parameters
                                      # ...

The product tour scenarios are meant to be translatable. It's recommended to use translation keys instead of literal values in the YAML configuration, and provide the translations separately. Use the ibexa_integrated_help translation domain.

For all the examples below, you can provide the translations by creating a translations/ibexa_integrated_help.en.yaml file with the following content:

1
2
3
4
5
6
7
8
title: "Welcome!"
subtitle: "This is the subtitle"
tour.step.description: "This is the description of the step, you can use it to explain what to do in this step."
tour.link.documentation: "Documentation link"
tour.list.title: "This is the list title"
tour.list.item1: "First item"
tour.list.item2: "Second item"
tour.list.item3: "Third item"

Scenario configuration

Each scenario must specify its type and can optionally restrict access by user groups.

Scenario display order

The order of scenarios in the configuration file determines the order in which they are evaluated and, if the right conditions are met, displayed.

For general scenario, the scenario appears at the earliest opportunity (on any page after logging in).

For targeted scenarios, the scenario begins if the target element is found in the DOM. This means the scenario only appears on pages where the target element exists. To control where a targeted tour appears, ensure the first step targets an element unique to that specific page or section.

Once a scenario ends, the next scenario from the configuration is evaluated and, if applicable, displayed.

Scenario type

Set the scenario type to either general or targetable to control how the scenario is displayed.

1
2
3
product_tour:
    welcome_tour:
        type: general

User group restrictions

Restrict tour visibility by excluding specific user groups by using their content remote IDs:

1
2
3
product_tour:
    my_tour:
        user_groups_excluded: ['user_group_content_remote_id_1', 'user_group_content_remote_id_2']  # Exclude specific user groups

When creating new back office user groups, you should decide whether the existing product tour scenarios should be available for the new user group. If not, add the new group to the exclusion list.

Step configuration

Steps define individual instructions within a scenario. The configuration differs based on scenario type:

General scenario steps

General scenario steps display centered modals and support the background_image settings, allowing you to set a shared background image for each step.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
ibexa:
    system:
        default:
            product_tour:
                my_general_scenario:
                    type: 'general'
                    steps:
                        welcome_step:
                          step_title_translation_key: title
                          background_image: build/images/headless.png
                          blocks:
                              - type: title
                                params:
                                    text_translation_key: subtitle

Targeted tour steps

Targeted tour steps highlight specific UI elements using CSS selectors. You can select a specific element by using the target setting.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
ibexa:
    system:
        default:
            product_tour:
                targetable_dashboard_scenario:
                    type: 'targetable'
                    steps:
                        dashboard_options:
                            step_title_translation_key: Open Dashboard options
                            target: ".ibexa-db-header__more"
                            # No interaction_mode specified or the value is set to null
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Learn how to customize the blocks displayed on your dashboard

If a step's target element doesn't exist on the page, the step isn't be displayed and the scenario is be stopped. Ensure your configuration matches the actual DOM structure to avoid broken scenarios.

Interaction modes

Select how the scenario step interacts with the target element by using the interaction_mode setting. Targeted steps support three interaction modes:

TODO: 2 pane screenshot here, showing the UI for each of types.

Standard mode:

The default value. A tooltip attached to specific element on the page is displayed. Users continue the scenario with Previous/Next buttons:

1
2
3
4
5
6
7
8
                        dashboard_options:
                            step_title_translation_key: Open Dashboard options
                            target: ".ibexa-db-header__more"
                            # No interaction_mode specified or the value is set to null
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Learn how to customize the blocks displayed on your dashboard

Clickable mode:

A tooltip attached to specific element on the page is displayed. Users continue the scenario by clicking the highlighted element.

1
2
3
4
5
6
7
8
                        open_dashboard_options:
                            step_title_translation_key: Open Dashboard options
                            target: '.ibexa-db-header__more'
                            interaction_mode: clickable
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Click here to customize your dashboard

Note

Clickable mode is designed for single actions only (buttons, links). You can't select an entire form. If the interaction with the highlighted element results in redirection to a new page or opening a modal window where the previous target element can't be found, the "Previous" navigation step will be disabled.

Draggable mode:

A tooltip attached to specific element on the page is displayed. Users continue the scenario by dragging the highlighted element.

1
2
3
4
5
6
7
8
                        drag_and_drop_step:
                            step_title_translation_key: Drag-and-drop blocks
                            target: ".c-pb-toolbox-blocks-group__blocks > * .c-pb-toolbox-block__content:first-of-type"
                            interaction_mode: draggable
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Drag-and-drop blocks from the sidebar to the dashboard to customize it

Block types

Blocks are content elements that make up each step, available both for general and targetable scenarios. Seven block types are available for building step content, and a scenario step must contain at least one.

TODO: Step screenshot with all 7 blocks available?

Title block

Display bold, prominent titles:

1
2
3
                              - type: title
                                params:
                                    text_translation_key: subtitle

Text block

Display regular text content:

1
2
3
                              - type: text
                                params:
                                    text_translation_key: tour.step.description

Add external or internal links:

1
2
3
4
                              - type: link
                                params:
                                    url: https://doc.ibexa.co
                                    text_translation_key: tour.link.documentation

Image block

Embed images with alternative text:

1
2
3
4
                              - type: image
                                params:
                                    src: /bundles/ibexaadminui/img/feature-screenshot.jpg
                                    alt_translation_key: tour.image.alt

Video block

Embed video content by using the video HTML element:

1
2
3
4
                              - type: video
                                params:
                                    #  'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org
                                    url: https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4

List block

Create bulleted lists with title:

1
2
3
4
5
6
7
                              - type: list
                                params:
                                    title_translation_key: tour.list.title
                                    items_translation_keys:
                                        - tour.list.item1
                                        - tour.list.item2
                                        - tour.list.item3

The title_translation_key property is optional.

Custom Twig template block

For advanced content, use custom Twig templates that allows you to fully control the styling of the block:

1
2
3
                              - type: twig_template
                                params:
                                    template: custom_template.html.twig

Create the dedicated template, for example in templates/custom_template.html.twig.

1
2
3
{% trans_default_domain 'app' %}

{{ 'custom_step_description'|trans }}

and provide the required translations in translations/app.en.yaml:

1
custom_step_description: "This is a description coming from custom template"

Configuration examples

Example 1: General welcome tour

The following example showcases all the built-in block types for a general scenario consisting of a single step.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
ibexa:
    system:
        default:
            product_tour:
                my_general_scenario:
                    type: 'general'
                    steps:
                        welcome_step:
                          step_title_translation_key: title
                          background_image: build/images/headless.png
                          blocks:
                              - type: title
                                params:
                                    text_translation_key: subtitle
                              - type: text
                                params:
                                    text_translation_key: tour.step.description
                              - type: link
                                params:
                                    url: https://doc.ibexa.co
                                    text_translation_key: tour.link.documentation
                              - type: image
                                params:
                                    src: /bundles/ibexaadminui/img/feature-screenshot.jpg
                                    alt_translation_key: tour.image.alt
                              - type: video
                                params:
                                    #  'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org
                                    url: https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4
                              - type: list
                                params:
                                    title_translation_key: tour.list.title
                                    items_translation_keys:
                                        - tour.list.item1
                                        - tour.list.item2
                                        - tour.list.item3
                              - type: twig_template
                                params:
                                    template: custom_template.html.twig

Example 2: Targeted feature tour with interactive steps

The following example showcases the 3 interaction modes of a targetable scenario building an onboarding scenario for the customizable dashboard:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
ibexa:
    system:
        default:
            product_tour:
                targetable_dashboard_scenario:
                    type: 'targetable'
                    steps:
                        dashboard_options:
                            step_title_translation_key: Open Dashboard options
                            target: ".ibexa-db-header__more"
                            # No interaction_mode specified or the value is set to null
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Learn how to customize the blocks displayed on your dashboard
                        open_dashboard_options:
                            step_title_translation_key: Open Dashboard options
                            target: '.ibexa-db-header__more'
                            interaction_mode: clickable
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Click here to customize your dashboard
                        customize_dashboard:
                            step_title_translation_key: Customize Dashboard
                            target: '.ibexa-db-actions-popup-menu'
                            interaction_mode: clickable
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Choose "Customize dashboard"
                        drag_and_drop_step:
                            step_title_translation_key: Drag-and-drop blocks
                            target: ".c-pb-toolbox-blocks-group__blocks > * .c-pb-toolbox-block__content:first-of-type"
                            interaction_mode: draggable
                            blocks:
                                - type: text
                                  params:
                                      text_translation_key: Drag-and-drop blocks from the sidebar to the dashboard to customize it