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
refresh
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:
$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\
widget class is used. In case you have implemented own widget classes, you
have to implement the get
method, returning $this->options
,
to the corresponding classes. Otherwise the refresh option won't have any
effect.
Enable the refresh button
Widgets can render a refresh button to allow users to manually refresh them.
This is done by passing the value ['refresh
back
via get
method of the widget.
All TYPO3 Core widgets implement this behaviour and allow integrators to configure the option:
refreshAvailable
-
refresh
Available -
- Type
- boolean
- Default
false
Boolean value, either
false
ortrue
.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 refresh
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 widget
event on the
widget container (the div
element with the dashboard-
class).
You can identify the container by the data attribute widget-
, 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.