158 lines
7.0 KiB
ReStructuredText
158 lines
7.0 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
||
|
||
.. _breaking-90660:
|
||
|
||
============================================================
|
||
Breaking: #90660 - Registration of dashboard widgets changed
|
||
============================================================
|
||
|
||
See :issue:`90660`
|
||
|
||
Description
|
||
===========
|
||
|
||
As the registration of dashboard widgets changed to allow creation of widgets
|
||
through configuration, it is necessary to change your registration of widgets you
|
||
registered yourself in version 10.3. The abstracts used to kick start your
|
||
widgets were removed and the widgets shipped with EXT:dashboard were refactored.
|
||
|
||
|
||
Impact
|
||
======
|
||
|
||
As the abstracts previously used to kick-start a widget are removed, you need
|
||
to change to the new way of registering widgets. The dashboard
|
||
module will break if you do not update your registration.
|
||
|
||
|
||
Affected Installations
|
||
======================
|
||
|
||
All 3rd party extensions that registered an own widget with TYPO3 v10.3, will be
|
||
affected and need to update the widget registration. If you only used the widgets
|
||
shipped with core, you don't have to do anything.
|
||
|
||
|
||
Migration
|
||
=========
|
||
|
||
|
||
Migration of widgets based on default widget types
|
||
--------------------------------------------------
|
||
|
||
This section demonstrates how to migrate widgets that are based on one of
|
||
the existing widget types shipped by core. If your widgets are extending
|
||
one of the following classes, you can use this section to migrate your registration
|
||
to the new syntax.
|
||
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractBarChartWidget`
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractChartWidget`
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractCtaButtonWidget`
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractDoughnutChartWidget`
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractListWidget`
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractNumberWithIconWidget`
|
||
- :php:`\TYPO3\CMS\Dashboard\Widgets\AbstractRssWidget`
|
||
|
||
First of all you need to update your registration in the :file:`Services.yaml` file.
|
||
Here comes an example of a registration of RSS widget in the old version.
|
||
|
||
**Before**
|
||
|
||
.. code-block:: yaml
|
||
|
||
Vendor\Package\Widgets\MyOwnRSSWidget:
|
||
arguments: [‘myOwnRSSWidget’]
|
||
tags:
|
||
- name: dashboard.widget
|
||
identifier: myOwnRSSWidget
|
||
widgetGroups: ‘general’
|
||
|
||
|
||
As you can now use the predefined widgets and only have to register your own
|
||
implementation with your own configuration, you have to alter this registration
|
||
a little bit.
|
||
|
||
**Now**
|
||
|
||
.. 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'
|
||
# 12 hours cache
|
||
lifeTime: 43200
|
||
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'
|
||
|
||
|
||
It starts with the name of the service. Best practise is to use a dot-styled
|
||
name as there will be no class with that name. You can have multiple services
|
||
using the same class.
|
||
|
||
On the second line, we define which widget to use. In this case we choose the
|
||
RssWidget from the dashboard core extension. In the documentation, we explain
|
||
all the arguments like :php:`$view` and :php:`$cache`. For the migration you need
|
||
the :php:`$options` argument.
|
||
|
||
As you can see we specify the RSS file and the cache lifetime for this feed.
|
||
In the old situation you had to set these values in the class.
|
||
Now you can just put those values in the registration.
|
||
|
||
The second part that changed a little bit, is that you need to set the title,
|
||
description, icon, height and width in the tags section of the registration.
|
||
You can still use translatable strings like
|
||
``LLL:EXT:extension/Resources/Private/Language/locallang.xlf:widgets.myOwnRSSWidget.title``.
|
||
Important to remember is that the :yaml:`widgetGroups` property changed to :yaml:`groupNames`
|
||
to stay consistent with other service registrations.
|
||
|
||
Please note that valid values for height and width are now: :yaml:`small`, :yaml:`medium`,
|
||
and :yaml:`large`.
|
||
|
||
In the following table you can see which WidgetType to use now based on the
|
||
abstract you used previously.
|
||
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| Previously used abstract | Widget class to use for your registration |
|
||
+======================================+======================================================================+
|
||
| :php:`AbstractBarChartWidget` | :php:`TYPO3\CMS\Dashboard\Widgets\BarChartWidget` |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| :php:`AbstractChartWidget` | This was only used as an abstract of the other chart widgets and is |
|
||
| | not used anymore. If you want another graph type, you have to create |
|
||
| | your own widget. |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| :php:`AbstractCtaButtonWidget` | :php:`TYPO3\CMS\Dashboard\Widgets\CtaWidget` |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| :php:`AbstractDoughnutChartWidget` | :php:`TYPO3\CMS\Dashboard\Widgets\DoughnutChartWidget` |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| :php:`AbstractListWidget` | :php:`TYPO3\CMS\Dashboard\Widgets\ListWidget` |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| :php:`AbstractNumberWithIconWidget` | :php:`TYPO3\CMS\Dashboard\Widgets\NumberWithIconWidget` |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
| :php:`AbstractRssWidget` | :php:`TYPO3\CMS\Dashboard\Widgets\RssWidget` |
|
||
+--------------------------------------+----------------------------------------------------------------------+
|
||
|
||
|
||
You can check the documentation of EXT:dashboard to see the exact options for every type of widget.
|
||
|
||
|
||
Migration of widgets based on own widget type
|
||
---------------------------------------------
|
||
|
||
When you created your complete own widget type, the main thing to check is you
|
||
use the Dependency Injection options you have now. Please refer to the documentation
|
||
of EXT:dashboard to see how to create your own widget type and what options you
|
||
have.
|
||
|
||
.. index:: Backend, ext:dashboard, NotScanned
|