From 49e6cfffe91e9cbcf68112f3d63bfdef94f687bc Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Wed, 2 Nov 2022 11:39:40 +0100 Subject: [PATCH 1/2] Document the IConditionalWidget dashboard interface Signed-off-by: Joas Schilling --- developer_manual/digging_deeper/dashboard.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/developer_manual/digging_deeper/dashboard.rst b/developer_manual/digging_deeper/dashboard.rst index 9eacdf3c3..2072a4df2 100644 --- a/developer_manual/digging_deeper/dashboard.rst +++ b/developer_manual/digging_deeper/dashboard.rst @@ -147,6 +147,21 @@ however this method is deprecated and will be removed once Nextcloud 19 is EOL. } } +++++++++++++++++++++++++++++++++ +The IConditionalWidget interface +++++++++++++++++++++++++++++++++ + +The IConditionalWidget interface adds the **isEnabled** method to provide the option for a widget to opt-out later. +While registering the widget the information whether or not a widget should be displayed to the specific user might +not be available or to complex to calculate up front. In this case the IConditionalWidget allows you to check the +conditions only when really needed. + +.. code-block:: php + + public function isEnabled(): bool { + return false; + } + Provide a user interface ------------------------ From 1b8182567fe836600978d061006f5062efca1ab3 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Wed, 2 Nov 2022 12:02:33 +0100 Subject: [PATCH 2/2] Adjust heading levels to what other pages use Signed-off-by: Joas Schilling --- developer_manual/digging_deeper/dashboard.rst | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/developer_manual/digging_deeper/dashboard.rst b/developer_manual/digging_deeper/dashboard.rst index 2072a4df2..77108946b 100644 --- a/developer_manual/digging_deeper/dashboard.rst +++ b/developer_manual/digging_deeper/dashboard.rst @@ -147,9 +147,8 @@ however this method is deprecated and will be removed once Nextcloud 19 is EOL. } } -++++++++++++++++++++++++++++++++ The IConditionalWidget interface -++++++++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The IConditionalWidget interface adds the **isEnabled** method to provide the option for a widget to opt-out later. While registering the widget the information whether or not a widget should be displayed to the specific user might @@ -203,9 +202,8 @@ those additional interfaces: * 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 @@ -240,9 +238,8 @@ There are 3 types of buttons: ]; } -+++++++++++++++++++++++++++ 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. @@ -255,9 +252,8 @@ it returns the URL to the img/app.svg file in your app. ); } -+++++++++++++++++++++++++++ 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 @@ -269,9 +265,8 @@ the widget item icons should be rounded or kept as squares. 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`. @@ -304,9 +299,8 @@ This interface contains an extra `getItems` method which returns an array of `OC * iconUrl: URL to a square icon (svg or jpg/png of at least 44x44px) * sinceId: Item ID or timestamp. The client will then send the latest known sinceId in next dashboard API request. -+++++++++++ Use the API -+++++++++++ +^^^^^^^^^^^ The list of enabled widgets can be requested like that: