diff --git a/TODO b/TODO new file mode 100644 index 0000000000..183d65597a --- /dev/null +++ b/TODO @@ -0,0 +1,6 @@ +TODO: +1) PHP API reference + links +2) Arcade video +3) Screenshoty +4) Przekazywanie danych do tagu typu video - czy tylko url? +5) Stylowanie custom twig template diff --git a/code_samples/back_office/product_tour/config/general_scenario.yaml b/code_samples/back_office/product_tour/config/general_scenario.yaml new file mode 100644 index 0000000000..168da93152 --- /dev/null +++ b/code_samples/back_office/product_tour/config/general_scenario.yaml @@ -0,0 +1,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 diff --git a/code_samples/back_office/product_tour/config/targetable_scenario.yaml b/code_samples/back_office/product_tour/config/targetable_scenario.yaml new file mode 100644 index 0000000000..b008f05421 --- /dev/null +++ b/code_samples/back_office/product_tour/config/targetable_scenario.yaml @@ -0,0 +1,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 diff --git a/code_samples/back_office/product_tour/src/EventSubscriber/NotificationScenarioSubscriber.php b/code_samples/back_office/product_tour/src/EventSubscriber/NotificationScenarioSubscriber.php new file mode 100644 index 0000000000..81faed6518 --- /dev/null +++ b/code_samples/back_office/product_tour/src/EventSubscriber/NotificationScenarioSubscriber.php @@ -0,0 +1,65 @@ +notificationService = $notificationService; + } + + public static function getSubscribedEvents(): array + { + return [ + RenderProductTourScenarioEvent::class => ['onRenderScenario'], + ]; + } + + public function onRenderScenario(RenderProductTourScenarioEvent $event): void + { + $scenario = $event->getScenario(); + $steps = $scenario->getSteps(); + + if ($scenario->getIdentifier() !== 'notifications') { + return; + } + + foreach ($steps as $step) { + $scenario->removeStep($step); + } + + if (!$this->hasUnreadNotifications()) { + return; + } + + $customStep = new ProductTourStep(); + $customStep->setIdentifier('custom_step_identifier'); + $customStep->setInteractionMode('clickable'); + $customStep->setTarget('.ibexa-header-user-menu__notifications-toggler'); + $customStep->setTitle('You have unread notifications'); + $customStep->addBlock(new TextBlock('Click here to preview your unread notifications.')); + $customStep->addBlock(new LinkBlock( + 'https://doc.ibexa.co/projects/userguide/en/latest/getting_started/notifications/', + 'Learn more about notifications' + )); + + $scenario->addStep($customStep); + } + + private function hasUnreadNotifications(): bool + { + return $this->notificationService->getPendingNotificationCount() > 0; + } +} diff --git a/composer.json b/composer.json index 07fc0600c9..78455ddcd9 100644 --- a/composer.json +++ b/composer.json @@ -75,7 +75,8 @@ "ibexa/messenger": "~4.6.x-dev", "ibexa/collaboration": "~4.6.x-dev", "ibexa/share": "~4.6.x-dev", - "ibexa/phpstan": "~4.6.-dev" + "ibexa/phpstan": "~4.6.-dev", + "ibexa/integrated-help": "dev-dev as 4.6.x-dev" }, "scripts": { "fix-cs": "php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots", diff --git a/docs/administration/back_office/configure_product_tour.md b/docs/administration/back_office/configure_product_tour.md new file mode 100644 index 0000000000..d630548b9d --- /dev/null +++ b/docs/administration/back_office/configure_product_tour.md @@ -0,0 +1,281 @@ +--- +description: Configure custom product tour scenarios with steps, blocks, and interaction modes. +edition: lts-update +month_change: false +--- + +# 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](multisite.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. + +## Configuration structure + +Product tour scenarios are configured under the `ibexa.system..product_tour` key. +Each scenario has a unique identifier and contains steps, which in turn contain blocks. + +Basic configuration structure of a scenario: + +```yaml +ibexa: + system: + >: # For example, admin or admin_group + product_tour: + : + type: + user_groups_excluded: [, ...] # Optional + steps: + : # Scenario step, unique within a scenario + step_title_translation_key: + background_image: # Only for general type, optional + target: # Only for targetable type, required + interaction_mode: # Only for targetable type, optional + blocks: + - 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: + +``` yaml +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 `
` entities to `<br/>`. + +## 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), 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. +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](product_tour.md#scenario-types). + +```yaml +product_tour: + welcome_tour: + type: general +``` + +### User group restrictions + +Restrict scenario visibility by excluding specific user groups by using their content remote IDs: + +```yaml +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](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. +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. + +```yaml hl_lines="6 10" +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 0, 14) =]] +``` + +### Targeted tour steps + +Targeted tour steps highlight specific UI elements using CSS selectors. +You can select a specific element by using the `target` setting. + +```yaml hl_lines="6 10" +[[= include_file('code_samples/back_office/product_tour/config/targetable_scenario.yaml', 0, 15) =]] +``` + +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 + +Select how the scenario step interacts with the target element by using the `interaction_mode` setting. +Targeted steps support [three interaction modes](product_tour.md#targeted-scenarios): + +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. +Users continue the scenario with Previous/Next buttons: + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/targetable_scenario.yaml', 7, 15) =]] +``` + +**Clickable mode**: + +A tooltip attached to specific element on the page is displayed. +Users continue the scenario by clicking the highlighted element. + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/targetable_scenario.yaml', 15, 23) =]] +``` + +**Draggable mode**: + +A tooltip attached to specific element on the page is displayed. +Users continue the scenario by [dragging](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API#draggable_items) the highlighted element. + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/targetable_scenario.yaml', 31, 39) =]] +``` + +## 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. + +TODO: Step screenshot with all 7 blocks available? + +### Title block + +Display bold, prominent titles: + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 11, 14) =]] +``` + +### Text block + +Display regular text content: + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 14, 17) =]] +``` + +### Link block + +Add external or internal links: + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 17, 21) =]] +``` + +### List block + +Create bulleted lists with title: + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 29, 36) =]] +``` + +The `title_translation_key` property is optional. + +### 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', 21, 25) =]] +``` + +#### Video block + +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', 25, 29) =]] +``` + +### Custom Twig template block + +For advanced content, use custom Twig templates that allows you to fully control the styling of the block: + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml', 36, 39) =]] +``` + +Create the dedicated template, for example in `templates/custom_template.html.twig`. + +``` html+twig +{% trans_default_domain 'app' %} + +{{ 'custom_step_description'|trans }} +``` + +and provide the required translations in `translations/app.en.yaml`: + +``` yaml +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. + +```yaml +[[= include_file('code_samples/back_office/product_tour/config/general_scenario.yaml') =]] +``` + +### Example 2: Targeted feature tour with interactive steps + +The following example showcases the three interaction modes of a `targetable` scenario building an onboarding scenario for the [customizable dashboard](customize_dashboard.md): + +```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). diff --git a/docs/administration/back_office/customize_product_tour.md b/docs/administration/back_office/customize_product_tour.md new file mode 100644 index 0000000000..4c46d33181 --- /dev/null +++ b/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 diff --git a/docs/administration/back_office/integrated_help.md b/docs/administration/back_office/integrated_help.md index 54f5e4f720..2fce218169 100644 --- a/docs/administration/back_office/integrated_help.md +++ b/docs/administration/back_office/integrated_help.md @@ -1,7 +1,7 @@ --- description: Integrated help provides quick access to documentation, training, and support resources. edition: lts-update -month_change: false +month_change: true --- # Integrated help @@ -13,9 +13,18 @@ With this feature installed, users can click the ![Help icon](about-info.png){.i Integrated help is contextual, therefore, apart from user documentation, release notes, and partner guidelines, which are available to editors and store managers, developers can access API references, the GraphQL console, or the support portal. +## Product tours + +Product tours are interactive guided walkthroughs that help users discover and learn [[= product_name =]] features, available starting with [[= product_name =]] v4.6.28. +They provide step-by-step guidance directly within the application interface, accelerating user adoption and reducing training time. + +Developers can create custom onboarding journeys tailored to specific client implementations, user roles, or business processes. + +For more information, see [Product tour](product_tour.md). + ## Install package -Integrated help is optional. +The Integrated help LTS Update is optional. To enable it, run the following command: ```bash @@ -24,8 +33,14 @@ composer require ibexa/integrated-help After installation, you must [enable the help center in user settings]([[= user_doc =]]/getting_started/discover_ui#enable-help-center) to use the feature. -## Customize help menu +## Learn more -You can extend or alter the integrated help menu by quickly changing the link to user documentation, or adding or removing menu items or even entire menu sections. +[[= cards([ + "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", +]) =]] -For more information, see [Customize integrated help](customize_integrated_help.md). +TODO: Add PHP API link here diff --git a/docs/administration/back_office/product_tour.md b/docs/administration/back_office/product_tour.md new file mode 100644 index 0000000000..12a450bee6 --- /dev/null +++ b/docs/administration/back_office/product_tour.md @@ -0,0 +1,77 @@ +--- +description: Product tours provide interactive guided walkthroughs to help users learn Ibexa DXP features. +edition: lts-update +month_change: false +--- + +# Product tour + +Product tour is an in-app onboarding tool that helps users discover and learn [[= product_name =]] features through interactive, step-by-step guided walkthroughs. +Unlike static documentation, product tours provide real-time, contextual guidance directly within the application interface. + +With product tours, you can create customized onboarding journeys tailored to specific client implementations, user roles, or business processes. +This accelerates user adoption, reduces training time, and helps users confidently navigate the platform. + +Product tour functionality is available from version 4.6.28 as part of the Integrated help package. +To use product tours, you must first [install the Integrated help LTS Update](integrated_help.md#install-package). + +TODO: Arcade video here, showing a quick demo of the feature + +## Key concepts + +Product tour consists of three main elements: + +- **Scenario** - A complete onboarding scenario containing multiple steps that guide users through a specific feature or workflow +- **Step** - An individual instruction or explanation within a scenario, containing blocks, displayed as an overlay or tooltip +- **Block** - A content element within a step, such as text, images, videos, or links that provide information to the user + +## Scenario types + +[[= product_name =]] supports two types of scenarios, each designed for different use cases: + +TODO: screenshot for each type + +### General scenarios + +General tours display information in centered modals without targeting specific UI elements. +These tours provide an overview of features or concepts without requiring interaction with particular interface elements. + +General tours are ideal for: + +- Introducing new users to the platform +- Explaining high-level concepts or feature overviews +- Welcoming users with customizable background images and branding + +### Targeted scenarios + +Targeted scenarios highlight specific UI elements on the page and guide users through interactive workflows. +Each step targets a particular element using CSS selectors, drawing attention to buttons, navigation elements, or other interface components. + +Targeted scenarios are ideal for: + +- Demonstrating specific features or workflows +- Guiding users through multi-step processes +- Teaching users how to interact with particular UI elements + +The steps building the scenario support three interaction modes: + +- Standard - Users navigate between steps using "Previous" and "Next" buttons +- Clickable - Users must click the highlighted element to proceed to the next step +- Draggable - Users must drag and drop an element to continue the scenario + +TODO: Screenshot here + +## Scenario lifecycle + +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 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). diff --git a/docs/api/event_reference/event_reference.md b/docs/api/event_reference/event_reference.md index aa3b1fdb1a..5f4bff1cec 100644 --- a/docs/api/event_reference/event_reference.md +++ b/docs/api/event_reference/event_reference.md @@ -15,3 +15,30 @@ For example, copying a content item is connected with two events: `BeforeCopyCon ``` php [[= include_file('code_samples/api/public_php_api/src/EventSubscriber/MyEventSubcriber.php') =]] ``` + +[[= cards([ + "api/event_reference/ai_action_events", + "api/event_reference/cart_events", + "api/event_reference/catalog_events", + "api/event_reference/collaboration_events", + "api/event_reference/content_events", + "api/event_reference/content_type_events", + "api/event_reference/discounts_events", + "api/event_reference/integrated_help_events", + "api/event_reference/language_events", + "api/event_reference/location_events", + "api/event_reference/object_state_events", + "api/event_reference/order_management_events", + "api/event_reference/other_events", + "api/event_reference/page_events", + "api/event_reference/payment_events", + "api/event_reference/role_events", + "api/event_reference/section_events", + "api/event_reference/segmentation_events", + "api/event_reference/site_events", + "api/event_reference/taxonomy_events", + "api/event_reference/trash_events", + "api/event_reference/twig_component_events", + "api/event_reference/url_events", + "api/event_reference/user_events", +], columns=3) =]] diff --git a/docs/api/event_reference/integrated_help_events.md b/docs/api/event_reference/integrated_help_events.md new file mode 100644 index 0000000000..77e437bb04 --- /dev/null +++ b/docs/api/event_reference/integrated_help_events.md @@ -0,0 +1,18 @@ +--- +description: Events that are triggered when working with integrated help features like product tours. +edition: lts-update +page_type: reference +month_change: true +--- + +# Integrated help events + +## Product tour events + +The following event is dispatched when rendering a [product tour scenario](product_tour.md). + +| Event | Dispatched by | +|---|---| +|`RenderProductTourScenarioEvent`|`Ibexa\IntegratedHelp\Renderer\ProductTourRenderer::render()`| + +To learn how you can use this event to customize your product tour scenarios, see [Customize product tour](customize_product_tour.md). diff --git a/mkdocs.yml b/mkdocs.yml index 5acb5e5573..29afa05b43 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -103,6 +103,7 @@ nav: - AI Action events: api/event_reference/ai_action_events.md - Discounts events: api/event_reference/discounts_events.md - Collaboration events: api/event_reference/collaboration_events.md + - Integrated help events: api/event_reference/integrated_help_events.md - Other events: api/event_reference/other_events.md - Administration: - Administration: administration/administration.md @@ -164,6 +165,9 @@ nav: - Integrated help: - Integrated help: administration/back_office/integrated_help.md - 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