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 with 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 Customize product tour.

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

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

The basic configuration structure of a scenario is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
ibexa:
    system:
        <scope>>: # For example, admin or admin_group
            product_tour:
                <scenario_identifier>:
                    type: <general|targetable>
                    scenario_title_translation_key: <translation_key>  # Optional
                    user_groups_excluded: [<user_group_remote_content_id>, ...]  # Optional
                    steps:
                        <step_identifier>: # Scenario step, unique within a scenario
                            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. Ibexa recommends using translation keys instead of literal values in the YAML configuration, and providing 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
9
tour.my_general_scenario.title: "My general scenario"
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"

To insert a line break into a translation, HTML encode the <br> entities to &lt;br/&gt;.

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.

There are two scenario types:

  • general scenarios appear at the earliest opportunity (on any page after logging in), with an exception of the user settings area
  • targetable scenarios begin if their target element is found in the DOM when the page is loaded. Targetable scenarios don't trigger in the user settings area as well.

To control where a targetable tour appears, ensure that the first step targets an element unique to that specific page. You can target elements that appear after a user action, for example, modals like content browser, but the first step's target must be present in the DOM when the page is loaded.

Once a scenario ends, the system evaluates the next scenario from the configuration and, if applicable, displays it.

Scenario title

Use the optional scenario_title_translation_key field to provide a human-readable label for a scenario. This label is displayed in the user settings page where users can reset their product tour progress.

1
2
3
4
product_tour:
    welcome_tour:
        type: general
        scenario_title_translation_key: tour.welcome_tour.title

If the translation key is not set, the raw scenario identifier is used as the label.

Translations must be provided in the ibexa_integrated_help translation domain, for example, in translations/ibexa_integrated_help.en.yaml.

User group restrictions

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

1
2
3
product_tour:
    my_scenario:
        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, decide whether the existing product tour scenarios should be available for these new user groups. If not, add the new group to the exclusion list.

Warning

If a scenario contains information meant only for specific group of users, always use the user_groups_excluded setting to exclude other groups. Don't rely only on UI access restrictions to control the access to scenarios, as a malicious internal user could trigger and preview them outside of the intended place.

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 setting, allowing you to set a shared background image for each step. For the background, you can use an absolute URL or place your image in the public directory and provide the path relative to it. To resolve the path relative to the site root, prefix it with /.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
ibexa:
    system:
        admin_group:
            product_tour:
                my_general_scenario:
                    type: 'general'
                    scenario_title_translation_key: tour.my_general_scenario.title
                    steps:
                        welcome_step:
                          step_title_translation_key: title
                          background_image: /public/img/background.jpg
                          blocks:
                              - type: title
                                params:

Targetable tour steps

Targetable tour steps highlight specific UI elements by 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:
        admin_group:
            product_tour:
                targetable_dashboard_scenario:
                    type: 'targetable'
                    scenario_title_translation_key: tour.targetable_dashboard_scenario.title
                    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:

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

Interaction modes

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

Note

Clickable and draggable modes are 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 button won't be displayed.

Standard mode:

The default value. A tooltip attached to a 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

Standard interaction mode

Clickable mode:

A tooltip attached to a 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

Clickable interaction mode

Draggable mode:

A tooltip attached to a 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

You can use this mode only with HTML elements that have the draggable attribute set to true.

Draggable interaction mode

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. If multiple blocks are defined for a step, they are displayed one after the other.

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

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.

Media blocks

To provide data to the media block, provide absolute URLs or place your image or video files in the public directory and provide the path relative to it. To resolve the path relative to the site root, prefix it with /.

Image block

Embed images inside the step. You can provide alternative text by using the alt_translation_key property.

Assuming a public/img/diagram.jpg image exists, set the configuration value to /img/diagram.jpg.

1
2
3
4
                              - type: image
                                params:
                                    src: /public/img/diagram.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

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 a 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
40
ibexa:
    system:
        admin_group:
            product_tour:
                my_general_scenario:
                    type: 'general'
                    scenario_title_translation_key: tour.my_general_scenario.title
                    steps:
                        welcome_step:
                          step_title_translation_key: title
                          background_image: /public/img/background.jpg
                          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: /public/img/diagram.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: Targetable feature tour with interactive steps

The following example showcases how the three interaction modes of a targetable scenario can be used to build an onboarding tour 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
40
ibexa:
    system:
        admin_group:
            product_tour:
                targetable_dashboard_scenario:
                    type: 'targetable'
                    scenario_title_translation_key: tour.targetable_dashboard_scenario.title
                    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

To learn how to customize your scenarios even further with PHP code, see Customize product tour.