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