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 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.

Enable the refresh button

Widgets can render a refresh button to allow users to manually refresh them.

This is done by passing the value ['refreshAvailable'] = true; back via getOptions() method of the widget.

All TYPO3 Core widgets implement this behaviour and allow integrators to configure the option:

refreshAvailable

Boolean value, either false or true.

Provides a refresh button to backend users to refresh the widget. If the option is omitted false is assumed.

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 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 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}));

See Providing custom JS to learn how to add custom JavaScript.