diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 148 |
1 files changed, 14 insertions, 134 deletions
@@ -8,145 +8,25 @@ An app that notifies the user about import events of other apps. [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/owncloud/notifications/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/owncloud/notifications/?branch=master) [![Code Coverage](https://scrutinizer-ci.com/g/owncloud/notifications/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/owncloud/notifications/?branch=master) -## Notification workflow - -### Example story - -Let's assume the following example scenario. Our app is the files_sharing app. We want -to notify the user when a remote share has to be accepted/decline. If the user has dealt -with it, we want to remove the notification again. - -#### Creating a new Notification - - 1. Grab a new notification object (`\OCP\Notification\INotification`) from the manager - (`\OCP\Notification\IManager`): - ```php - $manager = \OC::$server->getNotificationManager(); - $notification = $manager->createNotification(); - ``` - - 2. Set the necessary information for the notification: - ```php - $acceptAction = $notification->createAction(); - $acceptAction->setLabel('accept') - ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'POST'); - - $declineAction = $notification->createAction(); - $declineAction->setLabel('decline') - ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'DELETE'); - - $notification->setApp('files_sharing') - ->setUser('recipient1') - ->setTimestamp(time()) - ->setObject('remote', 1337) // $type and $id - ->setSubject('remote_share', ['/fancyFolder']) // $subject and $parameters - ->addAction($acceptAction) - ->addAction($declineAction) - ; - ``` - Setting **app, user, timestamp, object and subject** are mandatory. You should not use a - translated subject, message or action label. Use something like a "language key", to avoid - length problems with translations in the storage of a notification app. Translation is done - via invocation of your notifier by the manager when the notification is prepared for display. +## Screenshots - 3. Send the notification back to the manager: - ```php - $manager->notify($notification); - ``` +### No notifications (Sample) -#### Preparing a notification for display +**Note:** +In ownCloud 8.2 the app hides itself, when there is no app registered, +that creates notifications. In this case the bell and the dropdown are not +accessible. - 1. In `app.php` register your Notifier (`\OCP\Notification\INotifier`) interface to the manager, - using a `\Closure`: - ```php - $manager = \OC::$server->getNotificationManager(); - $manager->registerNotifier(function() { - return new \OCA\Files_Sharing\Notifier( - \OC::$server->getL10NFactory() - ); - }); - ``` +![Build Status](img/sample-empty.png) - 2. The manager will execute the closure and then call the `prepare()` method on your notifier. - If the notification is not known by your app, just throw an `\InvalidArgumentException`, - but if it is actually from your app, you must set the parsed subject, message and action labels: - ```php - protected $factory; +### New notifications (Sample) - public function __construct(\OCP\L10N\IFactory $factory) { - $this->factory = $factory; - } +![Build Status](img/sample-new.png) - /** - * @param INotification $notification - * @param string $languageCode The code of the language that should be used to prepare the notification - */ - public function prepare(INotification $notification, $languageCode) { - if ($notification->getApp() !== 'files_sharing') { - // Not my app => throw - throw new \InvalidArgumentException(); - } - - // Read the language from the notification - $l = $this->factory->get('myapp', $languageCode); - - switch ($notification->getSubject()) { - // Deal with known subjects - case 'remote_share': - $notification->setParsedSubject( - (string) $l->t('You received the remote share "%s"', $notification->getSubjectParameters()) - ); - - // Deal with the actions for a known subject - foreach ($notification->getActions() as $action) { - switch ($action->getLabel()) { - case 'accept': - $action->setParsedLabel( - (string) $l->t('Accept') - ); - break; - - case 'decline': - $action->setParsedLabel( - (string) $l->t('Decline') - ); - break; - } - - $notification->addParsedAction($action); - } - return $notification; - break; - - default: - // Unknown subject => Unknown notification => throw - throw new \InvalidArgumentException(); - } - } - ``` - -#### Marking a notification as read/deleted/processed/obsoleted - -Now in case the user accepted the share or the share was removed/unshared, we want to remove -the notification, because no user action is needed anymore. To do this, we simply have to -call the `markProcessed()` method on the manager with the neccessary information on a -notification object: - -```php -$manager = \OC::$server->getNotificationManager(); -$notification->setApp('files_sharing') - ->setObject('remote', 1337) - ->setUser('recipient1'); -$manager->markProcessed($notification); -``` +## Notification workflow -Thereby only the app name is mandatory: so if you don't set the user, the notification -will be marked as processed for all users that have it. So the following example will -remove all notifications for the app files_sharing on the object "remote #1337": +For information how to make your app interact with the notifications app, see +[Sending and processing/"mark as read" notifications as an ownCloud App](https://github.com/owncloud/notifications/wiki/Notification-Workflow-as-an-App-that-sends-Notifications) +in the wiki. -```php -$manager = \OC::$server->getNotificationManager(); -$notification->setApp('files_sharing') - ->setObject('remote', 1337); -$manager->markProcessed($notification); -``` +If you want to present notifications as a client, see [Reading and deleting notifications as an ownCloud Client](https://github.com/owncloud/notifications/wiki/Reading-and-deleting-notifications-as-a-Client). |