Review feedback

Author: mnocon

TODO

@@ -1,45 +1,6 @@
 TODO:
 1) PHP API reference + links
 2) Arcade video
-1) Czy typ image działa? Chyba nie?
-5) Screenshoty
-6) Custom block type?
-
----
-description: Customize product tour scenarios by creating custom step blocks
-edition: lts-update
-month_change: false
----
-
-# Create custom step blocks
-
-TODO: This is not possible
-
-When creating [product tour scenarios](integrated_help.md#product-tours) you're not limited to the [built-in step blocks](configure_product_tour.md#block-types).
-You can create custom block types, allowing you create reusable blocks that can be shared between scenarios.
-
-It's a more customizable alternative the [custom Twig block](configure_product_tour.md#custom-twig-template-block), as you can pass custom variables and add additional logic before rendering the template.
-
-The following example creates a custom `tip` block, a reusable component that you can use in different steps to provide tips to the user.
-
-To create a custom step block, start by creating a class implementing the `Ibexa\Contracts\IntegratedHelp\Builder\Block\BlockBuilderInterface` interface.
-This class is responsbile for converting the YAML configuration into PHP objects.
-
-``` php
-```
-
-Register it as a Symfony service and use the `ibexa.product_tour.block_factory` service tag to register is as a custom block configuration option:
-
-``` yaml
-```
-
-Then, create a class responsible for rendering the block:
-
-``` php
-```
-
-Register it as a Symfony service and use the `ibexa.product_tour.block_renderer` service tag to mark the class as a custom block renderer.
-
-``` yaml
-
-```
+3) Screenshoty
+4) Przekazywanie danych do tagu typu video - czy tylko url?
+5) Stylowanie custom twig template

docs/administration/back_office/configure_product_tour.md

@@ -11,7 +11,7 @@ You can configure the product tour scenarios to adapt it to your project needs,
 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](multisite.md).
 
-For more advanced customization cases that require PHP code, see the [integrated help's `RenderProductTourScenarioEvent`](integrated_help_events.md).
+For more advanced customization cases that require PHP code, see [Customize product tour](customize_product_tour.md).
 
 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.
 
@@ -31,7 +31,7 @@ ibexa:
                     type: <general|targetable>
                     user_groups_excluded: [<user_group_remote_content_id>, ...]  # Optional
                     steps:
-                        <step_key>: # Scenario step
+                        <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
@@ -60,6 +60,8 @@ 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.
@@ -68,7 +70,7 @@ Each scenario must specify its type and can optionally restrict access by user g
 
 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 **general scenario**, the scenario appears at the earliest opportunity (on any page after logging in), with an exception of the user settings area.
 
 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.
@@ -88,17 +90,22 @@ product_tour:
 
 ### User group restrictions
 
-Restrict tour visibility by excluding specific user groups by using their content remote IDs:
+Restrict scenario visibility by excluding specific user groups by using their content remote IDs:
 
 ```yaml
 product_tour:
-    my_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](user_registration.md#user-types), 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.
 
+!!! 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.
@@ -123,6 +130,7 @@ You can select a specific element by using the `target` setting.
 
 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.
+Use unique selectors to avoid triggering your scenarios on other pages.
 
 #### Interaction modes
 
@@ -131,6 +139,12 @@ Targeted steps support [three interaction modes](product_tour.md#targeted-scenar
 
 TODO: 2 pane screenshot here, showing the UI for each of types.
 
+!!! 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 step will be disabled.
+
 **Standard mode**:
 
 The default value. A tooltip attached to specific element on the page is displayed.
@@ -149,12 +163,6 @@ Users continue the scenario by clicking the highlighted element.
 [[= include_file('code_samples/back_office/product_tour/config/targetable_scenario.yaml', 15, 23) =]]
 ```
 
-!!! 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.
@@ -168,6 +176,7 @@ Users continue the scenario by [dragging](https://developer.mozilla.org/en-US/do
 
 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.
 
 TODO: Step screenshot with all 7 blocks available?
 
@@ -195,32 +204,40 @@ Add external or internal links:
 [[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 17, 21) =]]
 ```
 
-### Image block
+### List block
 
-Embed images with alternative text:
+Create bulleted lists with title:
 
 ```yaml
-[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 21, 25) =]]
+[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 29, 36) =]]
 ```
 
-### Video block
+The `title_translation_key` property is optional.
 
-Embed video content by using the [`video` HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video):
+### Media blocks
+
+To provide data to the media block, place your image or video files in the `public` directory and provide the relative path to it.
+
+!!! tip
+
+    To resolve the path relative to the site root, [prefix it with `/`](https://developer.mozilla.org/en-US/docs/Web/API/URL_API/Resolving_relative_references#root_relative).
+
+#### Image block
+
+Embed images with alternative text:
 
 ```yaml
-[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 25, 29) =]]
+[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 21, 25) =]]
 ```
 
-### List block
+#### Video block
 
-Create bulleted lists with title:
+Embed video content by using the [`video` HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video):
 
 ```yaml
-[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 29, 36) =]]
+[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 25, 29) =]]
 ```
 
-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:
@@ -260,3 +277,5 @@ The following example showcases the 3 interaction modes of a `targetable` scenar
 ```yaml
 [[= include_file('code_samples/back_office/product_tour/config/targetable_scenario.yaml') =]]
 ```
+
+To learn how to customize your scenarios even further with PHP code, see [Customize product tour](customize_product_tour.md).

docs/administration/back_office/customize_product_tour.md

@@ -0,0 +1,53 @@
+---
+description: Customize product tour scenarios with custom event listeners
+edition: lts-update
+month_change: true
+---
+
+# Customize scenarios with PHP code
+
+You can customize the product tour scenarios with the [`RenderProductTourScenarioEvent`](integrated_help_events.md) event.
+This event is dispatched before rendering a product tour scenario and you can use it to:
+
+- Modify tour steps based on user permissions or roles
+- Add or remove steps dynamically
+- Change block content based on runtime conditions
+- Integrate custom data into tour scenarios
+
+With the following example, a custom onboarding scenario is built.
+It starts only when the current user has a pending [notification]([[= user_doc =]]/getting_started/notifications/).
+
+First, define a custom product tour scenario.
+It contains a placeholder step with a single block.
+
+``` yaml
+ibexa:
+    system:
+        default:
+            product_tour:
+                notifications:
+                    type: 'targetable'
+                    steps:
+                        placeholder_step:
+                            step_title_translation_key: 'This is a placeholder step'
+                            target: '.ibexa-header-user-menu__notifications-toggler'
+                            blocks:
+                                - type: text
+                                  params:
+                                      text_translation_key: 'This is a placeholder block, modified during event subscriber execution'
+```
+
+Then, create a subscriber modifying the scenario.
+
+```php hl_lines="35-37 39-41 43-45 47-58"
+[[= include_file('code_samples/back_office/product_tour/src/EventSubscriber/NotificationScenarioSubscriber.php') =]]
+```
+
+The subscriber executes the following actions:
+
+- makes sure the correct scenario is being processed
+- removes all the existing scenario steps
+- verifies that the current user has a pending notification
+- adds a custom clickable step to highlight the unread notification
+
+TODO: Screenshot here

docs/administration/back_office/integrated_help.md

@@ -39,6 +39,7 @@ After installation, you must [enable the help center in user settings]([[= user_
     "administration/back_office/customize_integrated_help",
     "administration/back_office/product_tour",
     "administration/back_office/configure_product_tour",
+    "administration/back_office/customize_product_tour",
     "api/event_reference/integrated_help_events",
 ]) =]]
 

docs/administration/back_office/product_tour.md

@@ -66,7 +66,12 @@ TODO: Screenshot here
 Depending on scenario configuration, they automatically appear to users when they first log in or visit a specific page.
 Each scenario appears only once for each user.
 
-Users can complete a tour by finishing all steps or by skipping it with the "Exit tour" button.
+Users can complete a tour with one of the following actions:
+
+- by finishing all steps
+- by skipping it with the **Exit tour** button
+- by skipping it with the **Escape** key
+
 At any time, users can manually restart completed tours from their [user settings]([[= user_doc =]]/getting_started/get_started/#user-settings).
 
 To start building your custom onboarding scenarios, see [configure product tour](configure_product_tour.md).

docs/api/event_reference/integrated_help_events.md

@@ -15,50 +15,4 @@ The following event is dispatched when rendering a [product tour scenario](produ
 |---|---|
 |`RenderProductTourScenarioEvent`|`Ibexa\IntegratedHelp\Renderer\ProductTourRenderer::render()`|
 
-### RenderProductTourScenarioEvent
-
-TODO: Move to "Customize product tour?" Maybe it's a better place
-
-This event is dispatched before rendering a product tour scenario and you can use it to:
-
-- Modify tour steps based on user permissions or roles
-- Add or remove steps dynamically
-- Change block content based on runtime conditions
-- Integrate custom data into tour scenarios
-
-With the following example, the scenario is modified to trigger only when certain conditions are matched. When the current user has a pending [notification]([[= user_doc =]]/getting_started/notifications/), a custom onboarding scenario is triggered.
-
-First, define a custom product tour scenario.
-It contains a placeholder step with a single block.
-
-``` yaml
-ibexa:
-    system:
-        default:
-            product_tour:
-                notifications:
-                    type: 'targetable'
-                    steps:
-                        placeholder_step:
-                            step_title_translation_key: 'This is a placeholder step'
-                            target: '.ibexa-header-user-menu__notifications-toggler'
-                            blocks:
-                                - type: text
-                                  params:
-                                      text_translation_key: 'This is a placeholder block, modified during event subscriber execution'
-```
-
-Then, create a subscriber modifying the scenario.
-
-```php hl_lines="35-37 39-41 43-45 47-58"
-[[= include_file('code_samples/back_office/product_tour/src/EventSubscriber/NotificationScenarioSubscriber.php') =]]
-```
-
-The subscriber executes the following actions:
-
-- makes sure the correct scenario is being processed
-- removes all the existing scenario steps
-- verifies that the current user has a pending notification
-- adds a custom clickable step to highlight the unread notification
-
-TODO: Screenshot here
+To learn how you can use this event to customize your product tour scenarios, see [Customize product tour](customize_product_tour.md).

mkdocs.yml

@@ -167,6 +167,7 @@ nav:
                 - Customize integrated help: administration/back_office/customize_integrated_help.md
                 - Product tour: administration/back_office/product_tour.md
                 - Configure product tour: administration/back_office/configure_product_tour.md
+                - Customize product tour: administration/back_office/customize_product_tour.md
             - Customize search:
                 - Customize search suggestion: administration/back_office/customize_search_suggestion.md
                 - Customize search sorting: administration/back_office/customize_search_sorting.md