mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-02 17:59:36 +07:00
update dashboard api for clients in dev doc
Signed-off-by: Julien Veyssier <julien-nc@posteo.net>
This commit is contained in:
Julien Veyssier
@@ -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": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user