IBX-9060: Document revamped notifications

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

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Notification;
+
+use Ibexa\Contracts\Core\Repository\Values\Notification\Notification;
+use Ibexa\Core\Notification\Renderer\NotificationRenderer;
+use Ibexa\Core\Notification\Renderer\TypedNotificationRendererInterface;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\Routing\RouterInterface;
+use Twig\Environment;
+
+class ListRenderer implements NotificationRenderer, TypedNotificationRendererInterface
+{
+    protected Environment $twig;
+
+    protected RouterInterface $router;
+
+    protected RequestStack $requestStack;
+
+    public function __construct(Environment $twig, RouterInterface $router, RequestStack $requestStack)
+    {
+        $this->twig = $twig;
+        $this->router = $router;
+        $this->requestStack = $requestStack;
+    }
+
+    public function render(Notification $notification): string
+    {
+        $templateToExtend = '@ibexadesign/account/notifications/list_item.html.twig';
+        $currentRequest = $this->requestStack->getCurrentRequest();
+        if ($currentRequest && $currentRequest->attributes->getBoolean('render_all')) {
+            $templateToExtend = '@ibexadesign/account/notifications/list_item_all.html.twig';
+        }
+
+        return $this->twig->render('@ibexadesign/notification.html.twig', [
+            'notification' => $notification,
+            'template_to_extend' => $templateToExtend,
+        ]);
+    }
+
+    public function generateUrl(Notification $notification): ?string
+    {
+        if (array_key_exists('content_id', $notification->data)) {
+            return $this->router->generate('ibexa.content.view', [
+                'contentId' => $notification->data['content_id'],
+            ]);
+        }
+
+        return null;
+    }
+
+    public function getTypeLabel(): string
+    {
+        return /** @Desc("Workflow stage changed") */
+            $this->translator->trans(
+                'workflow.notification.stage_change.label',
+                [],
+                'ibexa_workflow'
+            );
+    }
+}

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

@@ -6,10 +6,11 @@
 
 use Ibexa\Contracts\Core\Repository\Values\Notification\Notification;
 use Ibexa\Core\Notification\Renderer\NotificationRenderer;
+use Ibexa\Core\Notification\Renderer\TypedNotificationRendererInterface;
 use Symfony\Component\Routing\RouterInterface;
 use Twig\Environment;
 
-class MyRenderer implements NotificationRenderer
+class MyRenderer implements NotificationRenderer, TypedNotificationRendererInterface
 {
     protected Environment $twig;
 
@@ -23,7 +24,10 @@ public function __construct(Environment $twig, RouterInterface $router)
 
     public function render(Notification $notification): string
     {
-        return $this->twig->render('@ibexadesign/notification.html.twig', ['notification' => $notification]);
+        return $this->twig->render('@ibexadesign/notification.html.twig', [
+            'notification' => $notification,
+            'template_to_extend' => $templateToExtend,
+        ]);
     }
 
     public function generateUrl(Notification $notification): ?string
@@ -34,4 +38,16 @@ public function generateUrl(Notification $notification): ?string
 
         return null;
     }
+
+    }
+
+    public function getTypeLabel(): string
+    {
+        return /** @Desc("Workflow stage changed") */
+            $this->translator->trans(
+                'workflow.notification.stage_change.label',
+                [],
+                'ibexa_workflow'
+            );
+    }
 }

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

@@ -1,4 +1,4 @@
-{% extends '@ibexadesign/account/notifications/list_item.html.twig' %}
+{% extends template_to_extend %}
 
 {% trans_default_domain 'custom_notification' %}
 

code_samples/notifications/Src/Query/search.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+use Ibexa\Contracts\Core\Repository\Values\NotificationQuery;
+
+$repository = $this->getRepository();
+$notificationService = $repository->getNotificationService();
+$query = new NotificationQuery([], 0, 25);
+
+$query->addCriterion(new Type('Workflow:Review'));
+$query->addCriterion(new Status(['unread']));
+
+$from = new \DateTimeImmutable('-7 days');
+$to = new \DateTimeImmutable();
+
+$query->addCriterion(new DateCreated($from, $to));
+
+$notificationList = $notificationService->findNotifications($query);

docs/administration/back_office/notifications.md

@@ -63,7 +63,9 @@ Example:
 [[= include_file('code_samples/back_office/notifications/src/EventListener/ContentPublishEventListener.php') =]]
 ```
 
-To display the notification, write a renderer and tag it as a service.
+### Display single notification
+
+To display a single notification, write a renderer and tag it as a service.
 
 The example below presents a renderer that uses Twig to render a view:
 
@@ -83,6 +85,16 @@ Finally, you need to add an entry to `config/services.yaml`:
 [[= include_file('code_samples/back_office/notifications/config/custom_services.yaml') =]]
 ```
 
+### Display notification list
+
+To display a list of notifications, expand the above renderer.
+
+The example below presents a modified renderer that uses Twig to render a list view:
+
+```php
+[[= include_file('code_samples/back_office/notifications/src/Notification/ListRenderer.php') =]]
+```
+
 ## Notification timeout
 
 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

@@ -1,6 +1,7 @@
 ---
 description: Events that are triggered when working with bookmarks, notifications, settings, forms and others.
 page_type: reference
+month_change: true
 ---
 
 # Other events
@@ -22,12 +23,14 @@
 
 | Event | Dispatched by | Properties |
 |---|---|---|
-|`BeforeCreateNotificationEvent`|`NotificationService::createNotification`|`CreateStruct $createStruct`</br>`Notification|null $notification`|
-|`CreateNotificationEvent`|`NotificationService::createNotification`|`Notification $notification`</br>`CreateStruct $createStruct`|
-|`BeforeDeleteNotificationEvent`|`NotificationService::deleteNotification`|`Notification $notification`|
-|`DeleteNotificationEvent`|`NotificationService::deleteNotification`|`Notification $notification`|
-|`BeforeMarkNotificationAsReadEvent`|`NotificationService::markNotificationAsRead`|`Notification $notification`|
-|`MarkNotificationAsReadEvent`|`NotificationService::markNotificationAsRead`|`Notification $notification`|
+|[`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`|
+|[`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`|
+|[`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`|
+|[`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`|
+|[`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`|
+|[`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`|
+|[`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`|
+|[`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`|
 
 ## Settings
 

docs/search/criteria_reference/notification_datecreated_criterion.md

@@ -0,0 +1,21 @@
+---
+description: Notification DateCreated Search Criterion
+month_change: true
+---
+
+# Notification DateCreated Criterion
+
+The `DateCreated` Search Criterion searches for notifications based on the date when they were created.
+
+## Arguments
+
+- `created` - date to be matched, provided as a `DateTimeInterface` object
+- `operator` - optional operator string (GTE, LTE)
+
+## Example
+
+### PHP
+
+```php hl_lines="14-15 17"
+[[= include_file('code_samples/notifications/Src/Query/search.php') =]]
+```

docs/search/criteria_reference/notification_search_criteria.md

@@ -0,0 +1,18 @@
+---
+description: Notification Search Criteria
+month_change: true
+---
+
+# Notification Search Criteria reference
+
+Notification Search Criteria are only supported by Notification Search (`NotificationService::findNotifications`).
+
+With these Criteria you can filter notifications by their notification creation date, notification status, and notification type.
+
+## Notification Search Criteria
+
+|Search Criterion|Search based on|
+|-----|-----|
+|[DateCreated](notification_datecreated_criterion.md)|Date and time when notification was created|
+|[Status](notification_status_criterion.md)|Status of the notification|
+|[Type](notification_type_criterion.md)|Type of the notification|

docs/search/criteria_reference/notification_status_criterion.md

@@ -0,0 +1,20 @@
+---
+description: Notification Status Search Criterion
+month_change: true
+---
+
+# Notification Status Criterion
+
+The `Status` Search Criterion searches for notifications based on notification status.
+
+## Arguments
+
+- `status` - Boolean value that represents the status of the notification
+
+## Example
+
+### PHP
+
+```php hl_lines="12"
+[[= include_file('code_samples/notifications/Src/Query/search.php') =]]
+```

docs/search/criteria_reference/notification_type_criterion.md

@@ -0,0 +1,20 @@
+---
+description: Type Search Criterion
+month_change: true
+---
+
+# Type Criterion
+
+The `Type` Search Criterion searches for notifications by their types.
+
+## Arguments
+
+- `type` - string that represents the type of the notification, takes values defined in notification workflow
+
+## Example
+
+### PHP
+
+```php hl_lines="11"
+[[= include_file('code_samples/notifications/Src/Query/search.php') =]]
+```

mkdocs.yml

@@ -670,6 +670,12 @@ nav:
             - UserCriterion: search/activity_log_search_reference/user_criterion.md
         - Action Configuration Search Criteria: search/ai_actions_search_reference/action_configuration_criteria.md
         - Discounts Search Criteria: search/discounts_search_reference/discounts_criteria.md
+        - Notification Search Criteria:
+            - Notification Search Criteria: search/criteria_reference/notification_search_criteria.md
+            - DateCreated: search/criteria_reference/notification_datecreated_criterion.md
+            - Status: search/criteria_reference/notification_status_criterion.md
+            - Type: search/criteria_reference/notification_type_criterion.md
+
         - Sort Clause reference:
             - General Sort Clauses:
                 - General Sort Clause reference: search/sort_clause_reference/sort_clause_reference.md