From 0cb1ca53a9f28eb4793e81dfba4e9366da0cdd2a Mon Sep 17 00:00:00 2001 From: Andreas Creten Date: Thu, 20 Feb 2025 22:07:32 +0100 Subject: [PATCH 1/5] Update Notifications docs --- .../desktop/1/the-basics/notifications.md | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/resources/views/docs/desktop/1/the-basics/notifications.md b/resources/views/docs/desktop/1/the-basics/notifications.md index f2406603..e6e6773c 100644 --- a/resources/views/docs/desktop/1/the-basics/notifications.md +++ b/resources/views/docs/desktop/1/the-basics/notifications.md @@ -40,8 +40,97 @@ Notification::title('Hello from NativePHP') ->show(); ``` +### Notification Reference + +To keep track of different notifications, each notification gets a reference once created. You can manually set a reference using the `reference()` method. +By default, the current unix timestamp is used as the reference. Once the notification is shown, the reference is stored in the notification class. + +``` +$notification = Notification::title('Hello from NativePHP')->show(); +$notification->reference; // <-- This property contains the reference +``` + +## Configuring Notifications + +### Notification Title + +You may set the notification's title using the `title()` method. + +```php +Notification::title('Hello from NativePHP') + ->show(); +``` + +### Notification Reference + +You can use the `reference()` method to set an event identifier and track which notification triggered a certain event. +This reference will be sent along with any event triggered by the notification. By default, the current unix timestamp is used as the reference. + +```php +Notification::title('Hello from NativePHP') + ->reference(Str::uuid()) + ->show(); +``` + +### Notification Message + +You may set the notification's message using the `message()` method. + +```php +Notification::title('Hello from NativePHP') + ->message('This is a detail message coming from your Laravel app.') + ->show(); +``` + +### Notification Reply + +On macOS, you can allow the user to reply to a notification using the `hasReply()` method. + +```php +Notification::title('Hello from NativePHP') + ->hasReply() + ->show(); +``` + +The `hasReply()` method accepts a placeholder reply message as an argument. + +```php +Notification::title('Hello from NativePHP') + ->hasReply('This is a placeholder') + ->show(); +``` + +### Notification Actions + +On macOS, you can add action buttons to a notification using the `addAction()` method. + +```php +Notification::title('Hello from NativePHP') + ->addAction('Click here') + ->show(); +``` + +You can call the `addAction()` method multiple times if you need to add multiple buttons. + +```php +Notification::title('Hello from NativePHP') + ->addAction('Button One') + ->addAction('Button Two') + ->show(); +``` + ## Events ### `NotificationClicked` The `Native\Laravel\Events\Notifications\NotificationClicked` event is dispatched when a user clicks on a notification. +### `NotificationClosed` +The `Native\Laravel\Events\Notifications\NotificationClosed` event is dispatched when a user closes a notification. + +### `NotificationReply` +The `Native\Laravel\Events\Notifications\NotificationReply` event is dispatched when a user replies to a notification. + +### `NotificationActionClicked` +The `Native\Laravel\Events\Notifications\NotificationActionClicked` event is dispatched when a user clicks an action button on a notification. + +The `$index` references to the order of the buttons. The first button added has an index of `0`. From 0e323a340ceb075fd1d6fcdd03c76681dadfe269 Mon Sep 17 00:00:00 2001 From: Andreas Creten Date: Fri, 21 Feb 2025 15:02:29 +0100 Subject: [PATCH 2/5] Correct docs for ID instead of timestamp --- resources/views/docs/desktop/1/the-basics/notifications.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/views/docs/desktop/1/the-basics/notifications.md b/resources/views/docs/desktop/1/the-basics/notifications.md index e6e6773c..43faa356 100644 --- a/resources/views/docs/desktop/1/the-basics/notifications.md +++ b/resources/views/docs/desktop/1/the-basics/notifications.md @@ -43,7 +43,7 @@ Notification::title('Hello from NativePHP') ### Notification Reference To keep track of different notifications, each notification gets a reference once created. You can manually set a reference using the `reference()` method. -By default, the current unix timestamp is used as the reference. Once the notification is shown, the reference is stored in the notification class. +By default, a unique ID is generated as the reference. Once the notification is shown, the reference is stored in the notification class. ``` $notification = Notification::title('Hello from NativePHP')->show(); @@ -64,7 +64,7 @@ Notification::title('Hello from NativePHP') ### Notification Reference You can use the `reference()` method to set an event identifier and track which notification triggered a certain event. -This reference will be sent along with any event triggered by the notification. By default, the current unix timestamp is used as the reference. +This reference will be sent along with any event triggered by the notification. By default, the unique ID is generated as the reference. ```php Notification::title('Hello from NativePHP') From 3fc5fdba161ed20ba01c5d230437db7767fe0f7a Mon Sep 17 00:00:00 2001 From: Andreas Creten Date: Fri, 21 Feb 2025 22:27:42 +0100 Subject: [PATCH 3/5] Fix typo --- resources/views/docs/desktop/1/the-basics/notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/views/docs/desktop/1/the-basics/notifications.md b/resources/views/docs/desktop/1/the-basics/notifications.md index 43faa356..c9879970 100644 --- a/resources/views/docs/desktop/1/the-basics/notifications.md +++ b/resources/views/docs/desktop/1/the-basics/notifications.md @@ -64,7 +64,7 @@ Notification::title('Hello from NativePHP') ### Notification Reference You can use the `reference()` method to set an event identifier and track which notification triggered a certain event. -This reference will be sent along with any event triggered by the notification. By default, the unique ID is generated as the reference. +This reference will be sent along with any event triggered by the notification. By default, a unique ID is generated as the reference. ```php Notification::title('Hello from NativePHP') From e2f53dfc78c0c178940ae8ee7fc90923e13f200e Mon Sep 17 00:00:00 2001 From: Andreas Creten Date: Tue, 25 Feb 2025 16:14:49 +0100 Subject: [PATCH 4/5] Add examples of notification handling --- .../desktop/1/the-basics/notifications.md | 56 ++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/resources/views/docs/desktop/1/the-basics/notifications.md b/resources/views/docs/desktop/1/the-basics/notifications.md index c9879970..f6487791 100644 --- a/resources/views/docs/desktop/1/the-basics/notifications.md +++ b/resources/views/docs/desktop/1/the-basics/notifications.md @@ -124,6 +124,34 @@ Notification::title('Hello from NativePHP') ### `NotificationClicked` The `Native\Laravel\Events\Notifications\NotificationClicked` event is dispatched when a user clicks on a notification. +Example usage: +```php +Event::listen(NotificationClicked::class, function (NotificationClicked $event) { + $reference = $event->reference; // The unique reference to the clicked notification +}); +``` + +The reference can be used to track which notification was clicked: +```php +// Get recent posts +$posts = Post::query()->where('created_at', '>', now()->subMinute())->get(); + +// Generate notifications for recent posts +$posts->each(function(Post $post) { + Notification::title('New post: ' . $post->title) + ->reference($post->id) + ->event(\App\Events\PostNotificationClicked::class) + ->show(); +}); + +// Handle the click on a notification and redirect to the respective post +Event::listen(\App\Events\PostNotificationClicked::class, function (\App\Events\PostNotificationClicked $event) { + $post = Post::findOrFail($event->reference); + + Window::open()->url($post->url); +}); +``` + ### `NotificationClosed` The `Native\Laravel\Events\Notifications\NotificationClosed` event is dispatched when a user closes a notification. @@ -132,5 +160,31 @@ The `Native\Laravel\Events\Notifications\NotificationReply` event is dispatched ### `NotificationActionClicked` The `Native\Laravel\Events\Notifications\NotificationActionClicked` event is dispatched when a user clicks an action button on a notification. - The `$index` references to the order of the buttons. The first button added has an index of `0`. + +Example usage: +```php +Event::listen(NotificationActionClicked::class, function (NotificationActionClicked $event) { + $reference = $event->reference; // The unique reference to the clicked notification + $index = $event->index; // The index of the action button +}); +``` + +The `$index` is used to understand which button was clicked: +```php +Notification::title('Two buttons from NativePHP') + ->addAction('Accept') // <-- This will be $index = 0 + ->addAction('Decline') // <-- This will be $index = 1 + ->show(); + +// Handle the click on a button +Event::listen(NotificationActionClicked::class, function (NotificationActionClicked $event) { + if ($event->index === 0) { + // The logic for accepting here + } elseif ($event->index === 1) { + // The logic for declining here + } else { + throw new RuntimeException('Unhandled action button'); + } +}); +``` From b0ce7625493bffd43af40b5b53bf85505ea19e3b Mon Sep 17 00:00:00 2001 From: Simon Hamp Date: Wed, 26 Feb 2025 11:40:36 +0000 Subject: [PATCH 5/5] Simplified --- .../desktop/1/the-basics/notifications.md | 116 ++++++++---------- 1 file changed, 54 insertions(+), 62 deletions(-) diff --git a/resources/views/docs/desktop/1/the-basics/notifications.md b/resources/views/docs/desktop/1/the-basics/notifications.md index f6487791..1e855efa 100644 --- a/resources/views/docs/desktop/1/the-basics/notifications.md +++ b/resources/views/docs/desktop/1/the-basics/notifications.md @@ -10,6 +10,7 @@ NativePHP allows you to send system notifications using an elegant PHP API. Thes When used sparingly, notifications can be a great way to inform the user about events that are occurring in your application and to bring their attention back to it, especially if further input from them is required. Notifications are sent using the `Notification` facade. + ```php use Native\Laravel\Facades\Notification; ``` @@ -40,15 +41,12 @@ Notification::title('Hello from NativePHP') ->show(); ``` -### Notification Reference +### Notification References -To keep track of different notifications, each notification gets a reference once created. You can manually set a reference using the `reference()` method. -By default, a unique ID is generated as the reference. Once the notification is shown, the reference is stored in the notification class. +To keep track of different notifications, you may use the notification's `$reference` property. -``` -$notification = Notification::title('Hello from NativePHP')->show(); -$notification->reference; // <-- This property contains the reference -``` +By default, a unique reference is generated for you, but you may manually set a reference by [chaining the `reference()`](#notification-reference) method when creating +the notification. ## Configuring Notifications @@ -63,8 +61,15 @@ Notification::title('Hello from NativePHP') ### Notification Reference -You can use the `reference()` method to set an event identifier and track which notification triggered a certain event. -This reference will be sent along with any event triggered by the notification. By default, a unique ID is generated as the reference. +You can access the `$reference` property of a notification after it has been created: + +``` +$notification = Notification::title('Hello from NativePHP')->show(); + +$notification->reference; +``` + +You may chain the `reference()` method to set a custom reference when creating a notification: ```php Notification::title('Hello from NativePHP') @@ -72,6 +77,28 @@ Notification::title('Hello from NativePHP') ->show(); ``` +The reference will be sent along with any event triggered by the notification and can be used to track which specific notification was clicked: + +```php +use App\Events\PostNotificationClicked; +use App\Models\Post; + +Post::recentlyCreated() + ->get() + ->each(function(Post $post) { + Notification::title('New post: ' . $post->title) + ->reference($post->id) + ->event(PostNotificationClicked::class) + ->show(); + }); + +Event::listen(PostNotificationClicked::class, function (PostNotificationClicked $event) { + $post = Post::findOrFail($event->reference); + + Window::open()->url($post->url); +}); +``` + ### Notification Message You may set the notification's message using the `message()` method. @@ -119,39 +146,32 @@ Notification::title('Hello from NativePHP') ->show(); ``` -## Events +When an action button is clicked, it will trigger the [`NotificationActionClicked`](#codenotificationactionclickedcode) event. -### `NotificationClicked` -The `Native\Laravel\Events\Notifications\NotificationClicked` event is dispatched when a user clicks on a notification. - -Example usage: -```php -Event::listen(NotificationClicked::class, function (NotificationClicked $event) { - $reference = $event->reference; // The unique reference to the clicked notification -}); -``` +This event contains an `$index` property, which refers to the index of the action button that was clicked. Action button indexes start at `0`: -The reference can be used to track which notification was clicked: ```php -// Get recent posts -$posts = Post::query()->where('created_at', '>', now()->subMinute())->get(); - -// Generate notifications for recent posts -$posts->each(function(Post $post) { - Notification::title('New post: ' . $post->title) - ->reference($post->id) - ->event(\App\Events\PostNotificationClicked::class) - ->show(); -}); +use Native\Laravel\Events\Notifications\NotificationActionClicked; -// Handle the click on a notification and redirect to the respective post -Event::listen(\App\Events\PostNotificationClicked::class, function (\App\Events\PostNotificationClicked $event) { - $post = Post::findOrFail($event->reference); +Notification::title('Do you accept?') + ->addAction('Accept') // This action will be $index = 0 + ->addAction('Decline') // This action will be $index = 1 + ->show(); - Window::open()->url($post->url); +Event::listen(NotificationActionClicked::class, function (NotificationActionClicked $event) { + if ($event->index === 0) { + // 'Accept' clicked + } elseif ($event->index === 1) { + // 'Decline' clicked + } }); ``` +## Events + +### `NotificationClicked` +The `Native\Laravel\Events\Notifications\NotificationClicked` event is dispatched when a user clicks on a notification. + ### `NotificationClosed` The `Native\Laravel\Events\Notifications\NotificationClosed` event is dispatched when a user closes a notification. @@ -160,31 +180,3 @@ The `Native\Laravel\Events\Notifications\NotificationReply` event is dispatched ### `NotificationActionClicked` The `Native\Laravel\Events\Notifications\NotificationActionClicked` event is dispatched when a user clicks an action button on a notification. -The `$index` references to the order of the buttons. The first button added has an index of `0`. - -Example usage: -```php -Event::listen(NotificationActionClicked::class, function (NotificationActionClicked $event) { - $reference = $event->reference; // The unique reference to the clicked notification - $index = $event->index; // The index of the action button -}); -``` - -The `$index` is used to understand which button was clicked: -```php -Notification::title('Two buttons from NativePHP') - ->addAction('Accept') // <-- This will be $index = 0 - ->addAction('Decline') // <-- This will be $index = 1 - ->show(); - -// Handle the click on a button -Event::listen(NotificationActionClicked::class, function (NotificationActionClicked $event) { - if ($event->index === 0) { - // The logic for accepting here - } elseif ($event->index === 1) { - // The logic for declining here - } else { - throw new RuntimeException('Unhandled action button'); - } -}); -```