TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:14 +02:00
commit ff4622ba97
138 changed files with 9045 additions and 0 deletions
@@ -0,0 +1,83 @@
+.. include:: /Includes.rst.txt
+..  _make-refreshable:
+
+==================
+The refresh option
+==================
+
+In each widget the refresh option can be enabled. If the option is enabled the
+widget displays a reload button in the top right corner. It can then be
+refreshed via user interaction or via a javascript api.
+
+To enable the refresh action button, you have to define the
+:yaml:`refreshAvailable` option in the :yaml:`$options` part of the widget
+registration. Below is an example of a RSS widget with the refresh option enabled.
+
+.. code-block:: yaml
+
+   dashboard.widget.myOwnRSSWidget:
+     class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
+     arguments:
+       $options:
+         rssFile: 'https://typo3.org/rss'
+         lifeTime: 43200
+         refreshAvailable: true
+     tags:
+       - name: dashboard.widget
+         identifier: 'myOwnRSSWidget'
+         groupNames: 'general'
+         title: 'LLL:EXT:extension/Resources/Private/Language/locallang.xlf:widgets.myOwnRSSWidget.title'
+         description: 'LLL:EXT:extension/Resources/Private/Language/locallang.xlf:widgets.myOwnRSSWidget.description'
+         iconIdentifier: 'content-widget-rss'
+         height: 'medium'
+         width: 'medium'
+
+.. note::
+
+   In this example, the TYPO3 core :php:`TYPO3\CMS\Dashboard\Widgets\RssWidget`
+   widget class is used. In case you have implemented own widget classes, you
+   have to implement the :php:`getOptions()` method, returning :php:`$this->options`,
+   to the corresponding classes. Otherwise the refresh option won't have any
+   effect.
+
+..  _refresh-button:
+
+Enable the refresh button
+-------------------------
+
+Widgets can render a refresh button to allow users to manually refresh them.
+
+This is done by passing the value :php:`['refreshAvailable'] = true;` back
+via :php:`getOptions()` method of the widget.
+
+All TYPO3 Core widgets implement this behaviour and allow integrators to
+configure the option:
+
+.. include:: /Widgets/Options/RefreshAvailable.rst.txt
+
+..  _refresh-javascript:
+
+JavaScript API
+--------------
+
+It is possible for all widgets to dispatch an event, which will cause
+the widget being refreshed. This is possible for all widgets on the dashboard
+even when the :yaml:`refreshAvailable` option is not defined, or set to `false`.
+This will give developers the option to refresh the widgets whenever they think
+it is appropriate.
+
+To refresh a widget, dispatch the :js:`widgetRefresh` event on the
+widget container (the :html:`div` element with the :html:`dashboard-item` class).
+You can identify the container by the data attribute :html:`widget-hash`, which
+is a unique hash for every widget, even if you have more widgets of the same
+type on your dashboard.
+
+A small example below:
+
+.. code-block:: javascript
+
+   document
+     .querySelector('[data-widget-hash="{your-unique-widget-hash}"]')
+     .dispatchEvent(new Event('widgetRefresh', {bubbles: true}));
+
+See :ref:`implement-new-widget-custom-js` to learn how to add custom JavaScript.