Product tour

TODO

@@ -0,0 +1,45 @@
+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
+
+```

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

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

code_samples/back_office/product_tour/src/EventSubscriber/NotificationScenarioSubscriber.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\EventSubscriber;
+
+use Ibexa\Contracts\Core\Repository\NotificationService;
+use Ibexa\Contracts\IntegratedHelp\Event\RenderProductTourScenarioEvent;
+use Ibexa\IntegratedHelp\ProductTour\Block\LinkBlock;
+use Ibexa\IntegratedHelp\ProductTour\Block\TextBlock;
+use Ibexa\IntegratedHelp\ProductTour\ProductTourStep;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+final class NotificationScenarioSubscriber implements EventSubscriberInterface
+{
+    private NotificationService $notificationService;
+
+    public function __construct(NotificationService $notificationService)
+    {
+        $this->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;
+    }
+}

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",