Feature: #93210 - Possibility to refresh dashboard widgets¶

Description¶

For some widgets it makes sense for users to be able to refresh the widget without reloading the complete dashboard. Therefore, a new refresh action button will be available in the top right corner of widgets, which have the refresh option enabled.

To enable the refresh action button, you have to define the refreshAvailable option in the $options part of the widget registration. Below is an example of a RSS widget with the refresh option enabled.

dashboard.widget.myOwnRSSWidget:
  class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
  arguments:
    $view: '@dashboard.views.widget'
    $cache: '@cache.dashboard.rss'
    $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 \TYPO3\CMS\Dashboard\Widgets\RssWidget widget class is used. In case you have implemented own widget classes, you have to add the getOptions() method, returning $this->options, to the corresponding classes. Otherwise the refresh option won't have any effect. The method will anyways be required by the WidgetInterface in TYPO3 v12.

JavaScript API¶

Besides having a refresh action button on widgets, which have the new option enabled, 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 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.

You therefore need to dispatch the widgetRefresh event on the widget container (the div element with the dashboard-item class). You can identify the container by the data attribute 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:

document
  .querySelector('[data-widget-hash="{your-unique-widget-hash}"]')
  .dispatchEvent(new Event('widgetRefresh', {bubbles: true}));

Impact¶

Widgets with the option refreshAvailable set to true, will now feature a refresh action button in the top right corner of the widget.