diff --git a/docs/design/notifications.rst b/docs/design/notifications.rst index 2205a655..7425c0db 100644 --- a/docs/design/notifications.rst +++ b/docs/design/notifications.rst @@ -41,9 +41,13 @@ Accessibility - Notifications should be accessible and not rely solely on color to convey status, as this can be problematic for Users with color blindness, so use additional HTML attributes according to the notification type. - Toast notifications with interactive content shouldn't automatically disappear to remain WCAG 2.1 compliant. -Using notification components +.. vale off + +Using notification Components ============================= +.. vale on + Standard notifications with icons --------------------------------- @@ -86,11 +90,11 @@ This creates a more substantial notification block with a heading and paragraph, Notifications for the notifications panel ========================================= -Notifications under the panel are managed through the ``NotificationModel`` class, which is defined in ``NotificationModel.php``. +The ``NotificationModel`` class in ``NotificationModel.php`` manages notifications under the panel. .. note:: - The notification template is defined in ``notification.html.twig``. + The system defines the notification template in ``notification.html.twig``. Creating a notification ----------------------- @@ -122,11 +126,11 @@ Parameters: - ``$message`` (string): the main content of the notification. - ``$type`` (string|null): identifies the source and style of the notification (optional). -- ``$isRead`` (boolean): indicates if the notification has been read (default: true). +- ``$isRead`` (boolean): indicates if the system has marked the notification as read (default: true). - ``$header`` (string|null): the header text for the notification (required). - ``$iconClass`` (string|null): CSS class for the notification icon (for example, 'ri-eye-line'). - ``$datetime`` (\\DateTime|null): creation date of the notification. -- ``$user`` (User|null): User object associated with the notification (defaults to current user). +- ``$user`` (User|null): the User object associated with the notification defaults to the current User. - ``$deduplicateValue`` (string|null): used to prevent duplicate notifications within a specified timeframe. - ``$deduplicateDateTimeFrom`` (\\DateTime|null): customizes the ``deduplication timeframe``. @@ -134,7 +138,7 @@ Parameters: .. note:: - The header should only contain the translation string; Twig will handle the translation. + The header should only contain the translation string; Twig handles the translation. Notification types @@ -154,7 +158,7 @@ The ``$type`` parameter determines the visual style of the notification: Example usage ------------- -Here's an example of how to create a notification when a Contact export is scheduled: +Here's how to create a notification when you schedule a Contact export: .. code-block:: php @@ -175,8 +179,8 @@ Here's an example of how to create a notification when a Contact export is sched ); } -This use case showcases how the NotificationModel can be integrated into event-driven processes within Mautic. +This use case shows how to integrate the NotificationModel into event-driven processes within Mautic. This example calls the ``addNotification`` method with specific parameters tailored to the Contact export scenario. The Translator service handles the ``$message`` parameter to generate a localized message. This approach includes the User's Email address in the notification message. The system uses the translation key ``mautic.lead.export.being.prepared`` with the parameter ``%user_email%``, replacing it with the actual Email of the User who scheduled the export. This method allows for dynamic content insertion into the translated string. -If the User's Email wasn't necessary in the message, a normal translation string could have been used without parameter replacement. +If the User's Email weren't needed in the message, the system could have used a normal translation string without parameter replacement. -The other parameters in the ``addNotification`` call are equally important. The system styles the notification as an informational alert using the ``info`` type, which is appropriate for a status update on a scheduled task. The false value for ``$isRead`` ensures that the notification appears as unread, drawing the User's attention to this new information. The header, like the message, uses a translation key ``mautic.lead.export.being.prepared.header`` to maintain language consistency. Null values for the icon class and ``datetime`` mean that the system will use default values for these optional parameters. Finally, by passing the $user object, the notification is specifically associated with the user who initiated the export, ensuring it appears in their personal notification panel. \ No newline at end of file +The other parameters in the ``addNotification`` call are equally important. The system styles the notification as an informational alert using the ``info`` type, which is appropriate for a status update on a scheduled task. The false value for ``$isRead`` ensures that the notification appears as unread, drawing the User's attention to this new information. The header, like the message, uses a translation key ``mautic.lead.export.being.prepared.header`` to maintain language consistency. Null values for the icon class and ``datetime`` mean that the system uses default values for these optional parameters. Finally, by passing the ``$user`` object, the notification is specifically associated with the user who initiated the export, ensuring it appears in their personal notification panel. \ No newline at end of file