From 6982597b6a6d319dacfbe3bee2edd2a39b3d6d68 Mon Sep 17 00:00:00 2001 From: Richard Steinmetz Date: Thu, 17 Aug 2023 15:09:30 +0200 Subject: feat(dashboard): implement widget item api v2 This API enables the dashboard to render all widgets from the API data alone without having apps to provide their own bundles. This saves a lot of traffic and execution time as a lot less javascript has to be parsed on the frontend. Signed-off-by: Richard Steinmetz --- lib/public/Dashboard/IAPIWidgetV2.php | 43 +++++++++++++ lib/public/Dashboard/IReloadableWidget.php | 41 ++++++++++++ lib/public/Dashboard/Model/WidgetItem.php | 25 +++++++- lib/public/Dashboard/Model/WidgetItems.php | 100 +++++++++++++++++++++++++++++ 4 files changed, 206 insertions(+), 3 deletions(-) create mode 100644 lib/public/Dashboard/IAPIWidgetV2.php create mode 100644 lib/public/Dashboard/IReloadableWidget.php create mode 100644 lib/public/Dashboard/Model/WidgetItems.php (limited to 'lib/public/Dashboard') diff --git a/lib/public/Dashboard/IAPIWidgetV2.php b/lib/public/Dashboard/IAPIWidgetV2.php new file mode 100644 index 00000000000..27cb6510c77 --- /dev/null +++ b/lib/public/Dashboard/IAPIWidgetV2.php @@ -0,0 +1,43 @@ + + * + * @author Richard Steinmetz + * + * @license AGPL-3.0-or-later + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + * + */ + +namespace OCP\Dashboard; + +use OCP\Dashboard\Model\WidgetItems; + +/** + * Interface IAPIWidgetV2 + * + * @since 27.1.0 + */ +interface IAPIWidgetV2 extends IWidget { + /** + * Items to render in the widget + * + * @since 27.1.0 + */ + public function getItemsV2(string $userId, ?string $since = null, int $limit = 7): WidgetItems; +} diff --git a/lib/public/Dashboard/IReloadableWidget.php b/lib/public/Dashboard/IReloadableWidget.php new file mode 100644 index 00000000000..9f65653fbe6 --- /dev/null +++ b/lib/public/Dashboard/IReloadableWidget.php @@ -0,0 +1,41 @@ + + * + * @author Richard Steinmetz + * + * @license AGPL-3.0-or-later + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + * + */ + +namespace OCP\Dashboard; + +/** + * Allow {@see IAPIWidgetV2} to reload their items + * + * @since 27.1.0 + */ +interface IReloadableWidget extends IAPIWidgetV2 { + /** + * Periodic interval in seconds in which to reload the widget's items + * + * @since 27.1.0 + */ + public function getReloadInterval(): int; +} diff --git a/lib/public/Dashboard/Model/WidgetItem.php b/lib/public/Dashboard/Model/WidgetItem.php index 859a5652351..1c54d2bd426 100644 --- a/lib/public/Dashboard/Model/WidgetItem.php +++ b/lib/public/Dashboard/Model/WidgetItem.php @@ -6,6 +6,7 @@ declare(strict_types=1); * @copyright 2021, Julien Veyssier * * @author Julien Veyssier + * @author Richard Steinmetz * * @license GNU AGPL version 3 or any later version * @@ -56,24 +57,30 @@ final class WidgetItem implements JsonSerializable { */ private $sinceId = ''; + /** + * Overlay icon to show in the bottom right corner of {@see $iconUrl} + * + * @since 27.1.0 + */ + private string $overlayIconUrl = ''; /** * WidgetItem constructor * * @since 22.0.0 - * - * @param string $type */ public function __construct(string $title = '', string $subtitle = '', string $link = '', string $iconUrl = '', - string $sinceId = '') { + string $sinceId = '', + string $overlayIconUrl = '') { $this->title = $title; $this->subtitle = $subtitle; $this->iconUrl = $iconUrl; $this->link = $link; $this->sinceId = $sinceId; + $this->overlayIconUrl = $overlayIconUrl; } /** @@ -132,6 +139,17 @@ final class WidgetItem implements JsonSerializable { return $this->sinceId; } + /** + * Get the overlay icon url + * + * @since 27.1.0 + * + * @return string + */ + public function getOverlayIconUrl(): string { + return $this->overlayIconUrl; + } + /** * @since 22.0.0 * @@ -143,6 +161,7 @@ final class WidgetItem implements JsonSerializable { 'title' => $this->getTitle(), 'link' => $this->getLink(), 'iconUrl' => $this->getIconUrl(), + 'overlayIconUrl' => $this->getOverlayIconUrl(), 'sinceId' => $this->getSinceId(), ]; } diff --git a/lib/public/Dashboard/Model/WidgetItems.php b/lib/public/Dashboard/Model/WidgetItems.php new file mode 100644 index 00000000000..4bb51f2f9b6 --- /dev/null +++ b/lib/public/Dashboard/Model/WidgetItems.php @@ -0,0 +1,100 @@ + + * + * @author Richard Steinmetz + * + * @license AGPL-3.0-or-later + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + * + */ + +namespace OCP\Dashboard\Model; + +use JsonSerializable; +use OCP\Dashboard\IAPIWidgetV2; + +/** + * Interface WidgetItems + * + * This class is used by {@see IAPIWidgetV2} interface. + * It represents an array of widget items and additional context information that can be provided to clients via the Dashboard API + * + * @see IAPIWidgetV2::getItemsV2 + * + * @since 27.1.0 + */ +class WidgetItems implements JsonSerializable { + /** + * @param $items WidgetItem[] + * + * @since 27.1.0 + */ + public function __construct( + private array $items = [], + private string $emptyContentMessage = '', + private string $halfEmptyContentMessage = '', + ) { + } + + /** + * Items to render in the widgets + * + * @since 27.1.0 + * + * @return WidgetItem[] + */ + public function getItems(): array { + return $this->items; + } + + /** + * The "half" empty content message to show above the list of items. + * + * A non-empty string enables this feature. + * An empty string hides the message and disables this feature. + * + * @since 27.1.0 + */ + public function getEmptyContentMessage(): string { + return $this->emptyContentMessage; + } + + /** + * The empty content message to show in case of no items at all + * + * @since 27.1.0 + */ + public function getHalfEmptyContentMessage(): string { + return $this->halfEmptyContentMessage; + } + + /** + * @since 27.1.0 + */ + public function jsonSerialize(): array { + $items = array_map(static function (WidgetItem $item) { + return $item->jsonSerialize(); + }, $this->getItems()); + return [ + 'items' => $items, + 'emptyContentMessage' => $this->getEmptyContentMessage(), + 'halfEmptyContentMessage' => $this->getHalfEmptyContentMessage(), + ]; + } +} -- cgit v1.2.3