From f202e0436f9b4b847586e535f0738b06be12e0a3 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 4 Aug 2021 15:10:19 +0200
Subject: [PATCH] add notes about js client and custom events to dev docs
Signed-off-by: Robin Appelman <robin@icewind.nl>
---
DEVELOPING.md | 36 +++++++++++++++++++++++++++++++++---
README.md | 8 +++++++-
2 files changed, 40 insertions(+), 4 deletions(-)
diff --git a/DEVELOPING.md b/DEVELOPING.md
index 9402704..c05aae5 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -9,6 +9,18 @@ If you want to listen to incoming events from the web interface of your Nextclou
you can use the [`@nextcloud/notify_push`](https://www.npmjs.com/package/@nextcloud/notify_push) javascript library.
Which will handle all the details for authenticating and connecting to the push server.
+```js
+import { listen } from '@nextcloud/notify_push'
+
+let has_push = listen('notify_file', () => {
+ console.log("A file has been changed")
+})
+
+if (!hash_push) {
+ console.log("notify_push not available on the server")
+}
+```
+
## Clients
Desktop and other clients that don't run in the Nextcloud web interface can use the following steps to receive notifications.
@@ -65,11 +77,29 @@ discover_endpoint(nextcloud_url, username, password).then((endpoint) => {
```
-```bash
-test_client https://cloud.example.com username password
+## Sending custom events
+
+You can send custom events from a nextcloud app using the methods provided by `OCA\NotifyPush\IQueue`.
+
+```php
+// in a real app, you'll want to setup DI to get an instance of `IQueue`
+$queue = \OC::$server->get(OCA\NotifyPush\IQueue::class);
+$queue->push('notify_custom', [
+ 'user' => "uid",
+ 'message' => "my_message_type",
+ 'body' => ["foo" => "bar"], // optional
+]);
```
-Note that this does not support two-factor authentication of non-default login flows, you can use an app-password in those cases.
+Which will be pushed to client as `'my_message_type {"foo": "bar"}'` and can be used with the `@nextcloud/notify_push` client using
+
+```js
+import { listen } from '@nextcloud/notify_push'
+
+listen('my_message_type', (message_type, optional_body) => {
+
+})
+```
## Building
diff --git a/README.md b/README.md
index 0771734..1b37024 100644
--- a/README.md
+++ b/README.md
@@ -302,4 +302,10 @@ For information about how to use the push server in your own app or client, see
For development and testing purposes a test client is provided which can be downloaded from
the [github actions](https://github.com/nextcloud/notify_push/actions/workflows/rust.yml) page.<br>
(Click on a run from the list, scroll to the bottom and click on `test_client` to download the binary.)<br>
-Please note: the Test client is only build for x86_64 Linux currently.
\ No newline at end of file
+Please note: the Test client is only build for x86_64 Linux currently.
+
+```bash
+test_client https://cloud.example.com username password
+```
+
+Note that this does not support two-factor authentication of non-default login flows, you can use an app-password in those cases.
--
GitLab