85 lines
3.0 KiB
ReStructuredText
85 lines
3.0 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
||
|
||
.. _feature-93210:
|
||
|
||
==========================================================
|
||
Feature: #93210 - Possibility to refresh dashboard widgets
|
||
==========================================================
|
||
|
||
See :issue:`93210`
|
||
|
||
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
|
||
: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:
|
||
$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 :php:`TYPO3\CMS\Dashboard\Widgets\RssWidget`
|
||
widget class is used. In case you have implemented own widget classes, you
|
||
have to add the :php:`getOptions()` method, returning :php:`$this->options`,
|
||
to the corresponding classes. Otherwise the refresh option won't have any
|
||
effect. The method will anyways be required by the :php:`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 :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.
|
||
|
||
You therefore need to 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}));
|
||
|
||
|
||
Impact
|
||
======
|
||
|
||
Widgets with the option :yaml:`refreshAvailable` set to `true`, will now
|
||
feature a refresh action button in the top right corner of the widget.
|
||
|
||
.. index:: Backend, ext:beuser
|