diff --git a/developer_manual/digging_deeper/dashboard.rst b/developer_manual/digging_deeper/dashboard.rst index 7ec0c99ae..9eacdf3c3 100644 --- a/developer_manual/digging_deeper/dashboard.rst +++ b/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": "" + } + ] + } + } + }