Skip to content

Commit da3cc2d

Browse files
dabrtmnocon
dabrt
and
mnocon
committed
IBX-9060: Document revamped notifications (#2797)
* IBX-9060: Document revamped notifications * Add modified query examples * Apply suggestion from @mnocon Co-authored-by: Marek Nocoń <[email protected]> --------- Co-authored-by: dabrt <[email protected]> Co-authored-by: Marek Nocoń <[email protected]>
1 parent f5107d4 commit da3cc2d

File tree

11 files changed

+208
-10
lines changed

11 files changed

+208
-10
lines changed

‎code_samples/back_office/notifications/src/Notification/ListRenderer.php‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace App\Notification;
6+
7+
use Ibexa\Contracts\Core\Repository\Values\Notification\Notification;
8+
use Ibexa\Core\Notification\Renderer\NotificationRenderer;
9+
use Ibexa\Core\Notification\Renderer\TypedNotificationRendererInterface;
10+
use Symfony\Component\HttpFoundation\RequestStack;
11+
use Symfony\Component\Routing\RouterInterface;
12+
use Twig\Environment;
13+
14+
class ListRenderer implements NotificationRenderer, TypedNotificationRendererInterface
15+
{
16+
protected Environment $twig;
17+
18+
protected RouterInterface $router;
19+
20+
protected RequestStack $requestStack;
21+
22+
public function __construct(Environment $twig, RouterInterface $router, RequestStack $requestStack)
23+
{
24+
$this->twig = $twig;
25+
$this->router = $router;
26+
$this->requestStack = $requestStack;
27+
}
28+
29+
public function render(Notification $notification): string
30+
{
31+
$templateToExtend = '@ibexadesign/account/notifications/list_item.html.twig';
32+
$currentRequest = $this->requestStack->getCurrentRequest();
33+
if ($currentRequest && $currentRequest->attributes->getBoolean('render_all')) {
34+
$templateToExtend = '@ibexadesign/account/notifications/list_item_all.html.twig';
35+
}
36+
37+
return $this->twig->render('@ibexadesign/notification.html.twig', [
38+
'notification' => $notification,
39+
'template_to_extend' => $templateToExtend,
40+
]);
41+
}
42+
43+
public function generateUrl(Notification $notification): ?string
44+
{
45+
if (array_key_exists('content_id', $notification->data)) {
46+
return $this->router->generate('ibexa.content.view', [
47+
'contentId' => $notification->data['content_id'],
48+
]);
49+
}
50+
51+
return null;
52+
}
53+
54+
public function getTypeLabel(): string
55+
{
56+
return /** @Desc("Workflow stage changed") */
57+
$this->translator->trans(
58+
'workflow.notification.stage_change.label',
59+
[],
60+
'ibexa_workflow'
61+
);
62+
}
63+
}

‎code_samples/back_office/notifications/src/Notification/MyRenderer.php‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,11 @@
66

77
use Ibexa\Contracts\Core\Repository\Values\Notification\Notification;
88
use Ibexa\Core\Notification\Renderer\NotificationRenderer;
9+
use Ibexa\Core\Notification\Renderer\TypedNotificationRendererInterface;
910
use Symfony\Component\Routing\RouterInterface;
1011
use Twig\Environment;
1112

12-
class MyRenderer implements NotificationRenderer
13+
class MyRenderer implements NotificationRenderer, TypedNotificationRendererInterface
1314
{
1415
protected Environment $twig;
1516

@@ -23,7 +24,10 @@ public function __construct(Environment $twig, RouterInterface $router)
2324

2425
public function render(Notification $notification): string
2526
{
26-
return $this->twig->render('@ibexadesign/notification.html.twig', ['notification' => $notification]);
27+
return $this->twig->render('@ibexadesign/notification.html.twig', [
28+
'notification' => $notification,
29+
'template_to_extend' => $templateToExtend,
30+
]);
2731
}
2832

2933
public function generateUrl(Notification $notification): ?string
@@ -34,4 +38,16 @@ public function generateUrl(Notification $notification): ?string
3438

3539
return null;
3640
}
41+
42+
}
43+
44+
public function getTypeLabel(): string
45+
{
46+
return /** @Desc("Workflow stage changed") */
47+
$this->translator->trans(
48+
'workflow.notification.stage_change.label',
49+
[],
50+
'ibexa_workflow'
51+
);
52+
}
3753
}

‎code_samples/back_office/notifications/templates/themes/admin/notification.html.twig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
{% extends '@ibexadesign/account/notifications/list_item.html.twig' %}
1+
{% extends template_to_extend %}
22

33
{% trans_default_domain 'custom_notification' %}
44

‎code_samples/notifications/Src/Query/search.php‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use Ibexa\Contracts\Core\Repository\Values\NotificationQuery;
6+
7+
$repository = $this->getRepository();
8+
$notificationService = $repository->getNotificationService();
9+
$query = new NotificationQuery([], 0, 25);
10+
11+
$query->addCriterion(new Type('Workflow:Review'));
12+
$query->addCriterion(new Status(['unread']));
13+
14+
$from = new \DateTimeImmutable('-7 days');
15+
$to = new \DateTimeImmutable();
16+
17+
$query->addCriterion(new DateCreated($from, $to));
18+
19+
$notificationList = $notificationService->findNotifications($query);

‎docs/administration/back_office/notifications.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,9 @@ Example:
6363
[[= include_file('code_samples/back_office/notifications/src/EventListener/ContentPublishEventListener.php') =]]
6464
```
6565

66-
To display the notification, write a renderer and tag it as a service.
66+
### Display single notification
67+
68+
To display a single notification, write a renderer and tag it as a service.
6769

6870
The example below presents a renderer that uses Twig to render a view:
6971

@@ -83,6 +85,16 @@ Finally, you need to add an entry to `config/services.yaml`:
8385
[[= include_file('code_samples/back_office/notifications/config/custom_services.yaml') =]]
8486
```
8587

88+
### Display notification list
89+
90+
To display a list of notifications, expand the above renderer.
91+
92+
The example below presents a modified renderer that uses Twig to render a list view:
93+
94+
```php
95+
[[= include_file('code_samples/back_office/notifications/src/Notification/ListRenderer.php') =]]
96+
```
97+
8698
## Notification timeout
8799

88100
To define the timeout for hiding Back-Office notification bars, per notification type, use the `ibexa.system.<scope>.notifications.<notification_type>.timeout` [configuration key](configuration.md#configuration-files):

‎docs/api/event_reference/other_events.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
description: Events that are triggered when working with bookmarks, notifications, settings, forms and others.
33
page_type: reference
4+
month_change: true
45
---
56

67
# Other events
@@ -22,12 +23,14 @@ The following events refer to [notifications displayed in the user menu](notific
2223

2324
| Event | Dispatched by | Properties |
2425
|---|---|---|
25-
|`BeforeCreateNotificationEvent`|`NotificationService::createNotification`|`CreateStruct $createStruct`</br>`Notification|null $notification`|
26-
|`CreateNotificationEvent`|`NotificationService::createNotification`|`Notification $notification`</br>`CreateStruct $createStruct`|
27-
|`BeforeDeleteNotificationEvent`|`NotificationService::deleteNotification`|`Notification $notification`|
28-
|`DeleteNotificationEvent`|`NotificationService::deleteNotification`|`Notification $notification`|
29-
|`BeforeMarkNotificationAsReadEvent`|`NotificationService::markNotificationAsRead`|`Notification $notification`|
30-
|`MarkNotificationAsReadEvent`|`NotificationService::markNotificationAsRead`|`Notification $notification`|
26+
|[`BeforeCreateNotificationEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-BeforeCreateNotificationEvent.html)|[`NotificationService::createNotification`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_createNotification)|`CreateStruct $createStruct`</br>`Notification|null $notification`|
27+
|[`CreateNotificationEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-CreateNotificationEvent.html)|[`NotificationService::createNotification`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_createNotification)|`Notification $notification`</br>`CreateStruct $createStruct`|
28+
|[`BeforeDeleteNotificationEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-BeforeDeleteNotificationEvent.html)|[`NotificationService::deleteNotification`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_deleteNotification)|`Notification $notification`|
29+
|[`DeleteNotificationEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-DeleteNotificationEvent.html)|[`NotificationService::deleteNotification`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_deleteNotification)|`Notification $notification`|
30+
|[`BeforeMarkNotificationAsReadEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-BeforeMarkNotificationAsReadEvent.html)|[`NotificationService::markNotificationAsRead`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_markNotificationAsRead)|`Notification $notification`|
31+
|[`MarkNotificationAsReadEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-MarkNotificationAsReadEvent.html)|[`NotificationService::markNotificationAsRead`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_markNotificationAsRead)|`Notification $notification`|
32+
|[`BeforeMarkNotificationAsUnreadEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-BeforeMarkNotificationAsUnreadEvent.html)|[`NotificationService::markNotificationAsUnread`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_markNotificationAsUnread)|`Notification $notification`|
33+
|[`MarkNotificationAsUnreadEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Events-Notification-MarkNotificationAsUnreadEvent.html)|[`NotificationService::markNotificationAsUnread`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-NotificationService.html#method_markNotificationAsUnread)|`Notification $notification`|
3134

3235
## Settings
3336

‎docs/search/criteria_reference/notification_datecreated_criterion.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
description: Notification DateCreated Search Criterion
3+
month_change: true
4+
---
5+
6+
# Notification DateCreated Criterion
7+
8+
The `DateCreated` Search Criterion searches for notifications based on the date when they were created.
9+
10+
## Arguments
11+
12+
- `created` - date to be matched, provided as a `DateTimeInterface` object
13+
- `operator` - optional operator string (GTE, LTE)
14+
15+
## Example
16+
17+
### PHP
18+
19+
```php hl_lines="14-15 17"
20+
[[= include_file('code_samples/notifications/Src/Query/search.php') =]]
21+
```

‎docs/search/criteria_reference/notification_search_criteria.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: Notification Search Criteria
3+
month_change: true
4+
---
5+
6+
# Notification Search Criteria reference
7+
8+
Notification Search Criteria are only supported by Notification Search (`NotificationService::findNotifications`).
9+
10+
With these Criteria you can filter notifications by their notification creation date, notification status, and notification type.
11+
12+
## Notification Search Criteria
13+
14+
|Search Criterion|Search based on|
15+
|-----|-----|
16+
|[DateCreated](notification_datecreated_criterion.md)|Date and time when notification was created|
17+
|[Status](notification_status_criterion.md)|Status of the notification|
18+
|[Type](notification_type_criterion.md)|Type of the notification|

‎docs/search/criteria_reference/notification_status_criterion.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
description: Notification Status Search Criterion
3+
month_change: true
4+
---
5+
6+
# Notification Status Criterion
7+
8+
The `Status` Search Criterion searches for notifications based on notification status.
9+
10+
## Arguments
11+
12+
- `status` - Boolean value that represents the status of the notification
13+
14+
## Example
15+
16+
### PHP
17+
18+
```php hl_lines="12"
19+
[[= include_file('code_samples/notifications/Src/Query/search.php') =]]
20+
```

‎docs/search/criteria_reference/notification_type_criterion.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
description: Type Search Criterion
3+
month_change: true
4+
---
5+
6+
# Type Criterion
7+
8+
The `Type` Search Criterion searches for notifications by their types.
9+
10+
## Arguments
11+
12+
- `type` - string that represents the type of the notification, takes values defined in notification workflow
13+
14+
## Example
15+
16+
### PHP
17+
18+
```php hl_lines="11"
19+
[[= include_file('code_samples/notifications/Src/Query/search.php') =]]
20+
```

0 commit comments

Comments
 (0)