Skip to content

Commit b66ca80

Browse files
dabrtmnocon
dabrt
and
mnocon
authored
IBX-10163: Document integrated help (#2937)
* IBX-10163: Document integrated help * Change the metadata in the "customize" article * Implement review comments * Move code to a separate file * PHP & JS CS Fixes * Describe global disable option * Mention user settings and adjust config key to enable --------- Co-authored-by: dabrt <[email protected]> Co-authored-by: Marek Nocoń <[email protected]>
1 parent ca3e822 commit b66ca80

File tree

8 files changed

+190
-2
lines changed

8 files changed

+190
-2
lines changed

‎code_samples/back_office/menu/menu_item/src/EventSubscriber/HelpMenuSubscriber.php‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace App\EventSubscriber;
6+
7+
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
8+
use Symfony\Contracts\EventDispatcher\Event;
9+
10+
final class HelpMenuSubscriber implements EventSubscriberInterface
11+
{
12+
public function __construct(
13+
private readonly bool $kernelDebug
14+
) {
15+
}
16+
17+
public static function getSubscribedEvents(): array
18+
{
19+
return [
20+
'ibexa_integrated_help.menu_configure.help_menu' => 'onHelpMenuConfigure',
21+
];
22+
}
23+
24+
public function onHelpMenuConfigure(Event $event): void
25+
{
26+
$menu = $event->getMenu();
27+
28+
// Remove roadmap menu item
29+
if ($menu->getChild('help__general')) {
30+
$generalSection = $menu->getChild('help__general');
31+
if ($generalSection->getChild('help__product_roadmap')) {
32+
$generalSection->removeChild('help__product_roadmap');
33+
}
34+
}
35+
36+
// Add videos tab, shown only in production
37+
if ($this->kernelDebug === false) {
38+
$resourcesSection = $menu->addChild('help__videos', [
39+
'label' => 'Product videos',
40+
]);
41+
42+
$resourcesSection->addChild('help__webinar_v5', [
43+
'label' => 'Webinar: Introducing Ibexa DXP v5',
44+
'uri' => 'https://www.youtube.com/watch?v=qWaBHG2LRm8',
45+
'extras' => [
46+
'isHighlighted' => false,
47+
'icon' => 'https://doc.ibexa.co/en/5.0/templating/twig_function_reference/img/icons/video.svg.png',
48+
'description' => 'Discover new features and improvements brought by Ibexa DXP v5.',
49+
],
50+
]);
51+
}
52+
}
53+
}

‎docs/administration/back_office/customize_integrated_help.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
description: Customize the integrated help menu.
3+
edition: lts-update
4+
month_change: true
5+
---
6+
7+
# Customize integrated help
8+
9+
The integrated help menu is part of the Integrated help introduced as an [LTS Update](editions.md#lts-updates).
10+
By default, it provides editors and developers with convenient access to documentation, training and other resources directly from the back office.
11+
12+
You can extend or modify the integrated menu in two ways:
13+
14+
- by disabling it for all users
15+
- by modifying a link to user documentation
16+
- by subscribing to the `ibexa_integrated_help.menu_configure.help_menu` event
17+
18+
## Disable integrated help for all users
19+
20+
After you have installed the integrated help package, you may still want to disable it globally, for example, to run UI tests in a `dev` [environment](environments.md).
21+
To do it, in `config/packages` create the `ibexa_integrated_help.yaml` file, with the following configuration:
22+
23+
``` yaml
24+
ibexa_integrated_help:
25+
enabled: false
26+
```
27+
28+
## Modify user documentation link
29+
30+
[[= product_name =]] provides a comfortable method for replacing a link to user documentation, when you do not want to modify the rest of the integrated help menu.
31+
This way you can direct application users such as editors or store managers to specific guidelines in force at your organization, without having to resort to development.
32+
33+
To do it, in `config/packages` create the `ibexa_integrated_help.yaml` file, with the following configuration:
34+
35+
``` yaml
36+
ibexa_integrated_help:
37+
user_documentation: <https://custom.user.documentation.address>
38+
```
39+
40+
## Intercept and modify event
41+
42+
[[= product_name =]] uses [KnpMenuBundle](https://github.com/KnpLabs/KnpMenuBundle) to build its backend menus.
43+
When it builds the integrated help menu, it dispatches the `ibexa_integrated_help.menu_configure.help_menu` event to pass information about the contents of the help menu to the front end.
44+
45+
You can intercept this event, and change its contents by creating a subscriber.
46+
With that subscriber, you can access the `menu` object, which is an instance of the `Knp\Menu\MenuItem`, and all the options passed by this object, and modify them.
47+
This way you can adjust menu sections that are reproduced by the front end as tabs, add new items, or integrate custom links into the help system.
48+
49+
### Menu object structure
50+
51+
The default `menu` object is structured as follows.
52+
Recreate this pattern when modifying an existing event with an intention to send it to the front end.
53+
54+
```
55+
root (MenuItem)
56+
│
57+
├── help__general // ("General" section)
58+
│ ├── help__user_documentation // (User docs, highlighted menu option)
59+
│ │ (...)
60+
│ └── help__submit_idea // (Submit idea, regular option)
61+
│
62+
└── help__developers // (conditional "Developers" section)
63+
├── help__developer_documentation // (Developer docs, highlighted)
64+
│ (...)
65+
└── help__support_portal
66+
```
67+
68+
`help_general` and `help_developers` are menu sections, or tabs.
69+
Sections consist of entries, and each entry carries the following information:
70+
71+
- `label` - a name of the help menu item
72+
- `uri` - an external link to the resource
73+
- `isHighlighted` - a Boolean switch that decides whether the menu item should be placed at the top of the tab
74+
- `icon` - a link to a graphic file to accompany the menu item
75+
- `description` - a summary of what users can expect after clicking the menu item
76+
77+
### Create a subscriber
78+
79+
Build a subscriber that intercepts the event and modifies it.
80+
In this example, it removes a product roadmap entry from the menu and adds a help menu tab with links to product videos.
81+
The tab is displayed in a production environment only.
82+
83+
``` php
84+
[[= include_file('code_samples/back_office/menu/menu_item/src/EventSubscriber/HelpMenuSubscriber.php') =]]
85+
```
86+
87+
!!! tip
88+
89+
If `autoconfigure` is enabled, the event subscriber is registered as a service by default.
90+
If not, register it as a service and tag with `kernel.event.subscriber`.
91+
92+
```yaml
93+
services:
94+
App\EventSubscriber\HelpMenuSubscriber:
95+
arguments:
96+
$kernelDebug: '%kernel.debug%'
97+
tags:
98+
- { name: kernel.event_subscriber }
99+
```
100+
101+
For more ideas on how you can extend the help menu, see [Back office menus](back_office_menus.md).

‎docs/administration/back_office/img/5_0_integrated_help_menu.png‎

177 KB
Loading

‎docs/administration/back_office/img/about-info.png‎

695 Bytes
Loading

‎docs/administration/back_office/integrated_help.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
description: Integrated help provides quick access to documentation, training, and support resources.
3+
edition: lts-update
4+
month_change: true
5+
edition: lts-update
6+
---
7+
8+
# Integrated help
9+
10+
Integrated help is an [LTS Update](editions.md#lts-updates) that brings documentation, training resources and product roadmap-related information into the back office.
11+
With this feature installed, users can click the ![Help icon](about-info.png){.inline-image} icon to access relevant content straight from the UI.
12+
13+
![Integrated help menu](5_0_integrated_help_menu.png)
14+
15+
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.
16+
17+
## Install package
18+
19+
Integrated help is optional.
20+
To enable it, run the following command:
21+
22+
```bash
23+
composer require ibexa/integrated-help
24+
```
25+
26+
After installation, you must [enable the help center in user settings]([[= user_doc =]]/getting_started/discover_ui#enable-help-center) to use the feature.
27+
28+
## Customize help menu
29+
30+
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.
31+
32+
For more information, see [Customize integrated help](customize_integrated_help.md).

‎docs/ibexa_products/editions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,4 @@ The features brought by LTS Updates become standard parts of the next LTS releas
6767
| Feature | [[= product_name_headless =]] | [[= product_name_exp =]] | [[= product_name_com =]] |
6868
|-----------------|-----------------|-----------------|-----------------|
6969
| [Anthropic connector](configure_ai_actions.md#install-anthropic-connector) | &#10004; | &#10004; | &#10004; |
70+
| [Integrated help](integrated_help.md) | &#10004; | &#10004; | &#10004; |

‎docs/release_notes/ibexa_dxp_v5.0.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,6 @@ The PHP API has been expanded with the following:
5757
[[% include 'snippets/release_50.md' %]]
5858
[[= release_note_entry_end() =]]
5959

60-
[[% set version = 'v5.0.2' %]]
61-
6260
[[= release_note_entry_begin("Ibexa DXP " + version, '2025-09-09', ['Headless', 'Experience', 'Commerce', 'New feature']) =]]
6361

6462
#### Collaboration

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,9 @@ nav:
161161
- Multi-file upload: administration/back_office/multifile_upload.md
162162
- Sub-items list: administration/back_office/subitems_list.md
163163
- Notifications: administration/back_office/notifications.md
164+
- Integrated help:
165+
- Integrated help: administration/back_office/integrated_help.md
166+
- Customize integrated help: administration/back_office/customize_integrated_help.md
164167
- Customize search:
165168
- Customize search suggestion: administration/back_office/customize_search_suggestion.md
166169
- Customize search sorting: administration/back_office/customize_search_sorting.md

0 commit comments

Comments
 (0)