Merge pull request #9211 from nextcloud/enh/noid/dashboard-client-api-list-widgets

Update dashboard client API doc

Author: ChristophWurst

developer_manual/digging_deeper/dashboard.rst

@@ -180,9 +180,83 @@ as plain JavaScript:
 Dashboard API for clients
 ---------------------------------------
 
-+++++++++++++++++
-Implement the API
-+++++++++++++++++
+To provide more information about your widget through the dashboard API for clients, you can implement
+those additional interfaces:
+
+* IButtonWidget to add buttons to be rendered by the client in the widget
+* IIconWidget to set the widget icon URL
+* IOptionWidget to set additional options
+* IAPIWidget to actually provide the widget content (the item list)
+
++++++++++++++++++++++++++++
+The IButtonWidget interface
++++++++++++++++++++++++++++
+
+
+The IButtonWidget interface adds the **getWidgetButtons** method to provide a list of buttons
+to be displayed by the clients in the widget.
+Those buttons let you define actions that can be triggered from the widget in the clients.
+
+There are 3 types of buttons:
+
+* WidgetButton::TYPE_NEW To let users create new elements in your app
+* WidgetButton::TYPE_MORE To let users see more information
+* WidgetButton::TYPE_SETUP If the widget requires some configuration
+
+.. code-block:: php
+
+	public function getWidgetButtons(string $userId): array {
+		return [
+			new WidgetButton(
+				WidgetButton::TYPE_NEW,
+				'https://somewhere.org',
+				$this->l10n->t('Create new element')
+			),
+			new WidgetButton(
+				WidgetButton::TYPE_MORE,
+				'https://my.nextcloud.org/apps/your-app/',
+				$this->l10n->t('More notifications')
+			),
+			new WidgetButton(
+				WidgetButton::TYPE_SETUP,
+				'https://my.nextcloud.org/apps/settings/user',
+				$this->l10n->t('Configure')
+			),
+		];
+	}
+
++++++++++++++++++++++++++++
+The IIconWidget interface
++++++++++++++++++++++++++++
+
+The IIconWidget interface adds the **getIconUrl** method to provide the URL to the widget icon. In the following example
+it returns the URL to the img/app.svg file in your app.
+
+.. code-block:: php
+
+	public function getIconUrl(): string {
+		return $this->urlGenerator->getAbsoluteURL(
+			$this->urlGenerator->imagePath(Application::APP_ID, 'app.svg')
+		);
+	}
+
++++++++++++++++++++++++++++
+The IOptionWidget interface
++++++++++++++++++++++++++++
+
+The IOptionWidget interface adds the **getWidgetOptions** method to provide additional widget options. It returns
+a WidgetOptions object which only contains the **roundItemIcons** boolean value for now. This tells the clients if
+the widget item icons should be rounded or kept as squares.
+
+.. code-block:: php
+
+	public function getWidgetOptions(): WidgetOptions {
+		return new WidgetOptions(true);
+	}
+
++++++++++++++++++++++++++++
+The IAPIWidget interface
++++++++++++++++++++++++++++
 
 If you want your widget content to be accessible with the dashboard API for Nextcloud clients,
 it must implement the `OCP\\Dashboard\\IAPIWidget` interface rather than `OCP\\Dashboard\\IWidget`.
@@ -219,7 +293,63 @@ This interface contains an extra `getItems` method which returns an array of `OC
 Use the API
 +++++++++++
 
-From the client point of view, the dashboard widget items can then be obtained with this kind of request:
+The list of enabled widgets can be requested like that:
+
+.. code-block:: bash
+
+    curl -u user:passwd https://my.nextcloud.org/ocs/v2.php/apps/dashboard/api/v1/widgets \
+        -H "Accept: application/json" \
+        -X GET
+
+Example response:
+
+.. code-block:: json
+
+    {
+      "ocs": {
+        "meta": {
+          "status": "ok",
+          "statuscode": 200,
+          "message": "OK"
+        },
+        "data": {
+          "spreed": {
+            "id": "spreed",
+            "title": "Talk mentions",
+            "order": 10,
+            "icon_class": "dashboard-talk-icon",
+            "icon_url": "https://my.nextcloud.org/apps/spreed/img/app-dark.svg",
+            "widget_url": "https://my.nextcloud.org/index.php/apps/spreed/",
+            "item_icons_round": true,
+            "buttons": [
+              {
+                "type": "more",
+                "text": "More unread mentions",
+                "link": "https://my.nextcloud.org/index.php/apps/spreed/"
+              }
+            ]
+          },
+          "github_notifications": {
+            "id": "github_notifications",
+            "title": "GitHub notifications",
+            "order": 10,
+            "icon_class": "icon-github",
+            "icon_url": "https://my.nextcloud.org/apps/integration_github/img/app-dark.svg",
+            "widget_url": "https://my.nextcloud.org/index.php/settings/user/connected-accounts",
+            "item_icons_round": true,
+            "buttons": [
+              {
+                "type": "more",
+                "text": "More notifications",
+                "link": "https://github.com/notifications"
+              }
+            ]
+          },
+        }
+      }
+    }
+
+The items list for each enabled widgets can be requested like that:
 
 .. code-block:: bash
 
@@ -230,3 +360,58 @@ From the client point of view, the dashboard widget items can then be obtained w
 
 If your client periodically gets widget items content with this API,
 include the latest `sinceId` for each widget to avoid getting the items you already have.
+
+Example response:
+
+.. code-block:: json
+
+    {
+      "ocs": {
+        "meta": {
+          "status": "ok",
+          "statuscode": 200,
+          "message": "OK"
+        },
+        "data": {
+          "github_notifications": [
+            {
+              "subtitle": "nextcloud-docker-dev#87",
+              "title": "Improve getting started",
+              "link": "https://github.com/juliushaertl/nextcloud-docker-dev/pull/87",
+              "iconUrl": "https://my.nextcloud.org/index.php/apps/integration_github/avatar/juliushaertl",
+              "sinceId": "2022-10-13T12:34:19Z"
+            },
+            {
+              "subtitle": "integration_github",
+              "title": "v1.0.11",
+              "link": "https://github.com/nextcloud/integration_github/releases",
+              "iconUrl": "https://my.nextcloud.org/index.php/apps/integration_github/avatar/nextcloud",
+              "sinceId": "2022-10-13T12:32:04Z"
+            },
+            {
+              "subtitle": "text#3209",
+              "title": "Rich workspaces: If there is no Readme.md, don’t show editor placeholder but move into \"+\" menu",
+              "link": "https://github.com/nextcloud/text/issues/3209",
+              "iconUrl": "https://my.nextcloud.org/index.php/apps/integration_github/avatar/nextcloud",
+              "sinceId": "2022-10-13T12:14:39Z"
+            }
+          ],
+          "spreed": [
+            {
+              "subtitle": "- Send chat messages without notifying the recipients in case it is not urgent",
+              "title": "Talk updates ✅",
+              "link": "https://my.nextcloud.org/index.php/call/hw39yxkp",
+              "iconUrl": "https://my.nextcloud.org/core/img/actions/group.svg",
+              "sinceId": ""
+            },
+            {
+              "subtitle": "@roberto What's up?",
+              "title": "Jane",
+              "link": "https://my.nextcloud.org/index.php/call/z87agy2o",
+              "iconUrl": "https://my.nextcloud.org/index.php/avatar/toto/64",
+              "sinceId": ""
+            }
+          ]
+        }
+      }
+    }