TYPO3-translation/cms-dashboard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TYPO3 v15 dev-main snapshot ()

Browse Source
This commit is contained in:
wappler
2026-08-10 22:31:14 +02:00
commit ff4622ba97
138 changed files with 9045 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/Configuration/Index.rst
+20
View File
@@ -0,0 +1,20 @@
.. include:: /Includes.rst.txt
.. _configuration:
=============
Configuration
=============
Target group: **Developers** and **Integrators**
.. toctree::
:maxdepth: 3
:titlesonly:
WidgetRegistration
WidgetGroupCreation
WidgetPresets
WidgetSettings
WidgetTemplate
PermissionHandlingOfWidgets
Documentation/Configuration/PermissionHandlingOfWidgets.rst
+17
View File
@@ -0,0 +1,17 @@
.. include:: /Includes.rst.txt
.. _permission-handling-of-widgets:
======================
Permissions of widgets
======================
Backend users marked as administrator have always access to all registered widgets.
Other backend users can be restricted via :guilabel:`Access List > Dashboard widgets` inside of user groups.
Each widget needs to be explicitly allowed.
.. figure:: /Images/AccessRestriction.png
:align: center
Granting access to dashboard widgets for backend users.
Documentation/Configuration/WidgetGroupCreation.rst
+45
View File
@@ -0,0 +1,45 @@
.. include:: /Includes.rst.txt
.. _create-widget-group:
===================
Create widget group
===================
Widget groups are used to group widgets into tabs.
This will have an effect when adding new widgets to an dashboard.
See :ref:`adding-widgets` to get an idea of the UI.
Groups are defined as PHP array:
.. code-block:: php
:caption: Example from EXT:dashboard/Configuration/Backend/DashboardWidgetGroups.php
<?php
return [
'general' => [
'title' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widget_group.general',
],
'systemInfo' => [
'title' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widget_group.system',
],
'typo3' => [
'title' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widget_group.typo3',
],
'news' => [
'title' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widget_group.news',
],
'documentation' => [
'title' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widget_group.documentation',
],
];
The file has to return an array of groups.
Each group consists of an array key used as identifier and an single option :php:`title`.
The title will be processed through translation and can be an ``LLL`` reference.
Each extension can create arbitrary widget groups.
Widgets can be assigned to multiple groups using the :confval:`widget-tag-groupNames`.
Please read :ref:`register-new-widget` to understand how this is done.
Documentation/Configuration/WidgetPresets.rst
+124
View File
@@ -0,0 +1,124 @@
.. include:: /Includes.rst.txt
.. _dashboard-presets:
=================
Dashboard Presets
=================
It is possible to configure presets of dashboards.
The extension already ships a ``default`` as well as an ``empty`` dashboard preset.
.. _create-preset:
Create preset
-------------
New presets can be configured:
.. code-block:: php
:caption: Example from EXT:dashboard/Configuration/Backend/DashboardPresets.php
<?php
return [
'default' => [
'title' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:dashboard.default',
'description' => 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:dashboard.default.description',
'iconIdentifier' => 'content-dashboard',
'defaultWidgets' => [
't3information',
't3news',
'docGettingStarted',
[
'identifier' => 'rss',
'settings' => [
'label' => 'My RSS Feed',
'feedUrl' => 'https://typo3.org/rss',
'limit' => 10,
],
],
],
'showInWizard' => false,
],
];
The file has to return an array with all presets.
Each prefix itself is an array, with an identifier as key.
The identifier is used to configure presets for users, see :ref:`configure-preset-for-user`.
Each preset consists of the following options:
.. php:class:: TYPO3\CMS\Dashboard\DashboardPreset
.. confval:: title
:type: string
:name: widget-presets-title
The title used for the preset. E.g. a ``LLL:EXT:`` reference..
.. confval:: description
:type: string
:name: widget-presets-description
The description used for the preset. E.g. a ``LLL:EXT:`` reference..
.. confval:: iconIdentifier
:type: string
:name: widget-presets-iconIdentifier
The identifier of the icon to use.
.. confval:: defaultWidgets
:type: array
:name: widget-presets-defaultWidgets
An array of widget identifiers, or fine-grained structure, that should be part of the dashboard preset.
Widgets are always filtered by permissions of each user.
Only widgets with access are actually part of the dashboard.
Have a look at :ref:`permission-handling-of-widgets` to understand how to handle permissions.
.. confval:: showInWizard
:type: bool
:name: widget-presets-showInWizard
Boolean value to indicate, whether this preset should be visible in the wizard,
when creating new dashboards, see :ref:`adding-dashboard`.
This can be disabled, to add presets via :ref:`configure-preset-for-user`, without
showing up in the wizard.
.. _configure-preset-for-user:
Configure preset for user
-------------------------
To define the default preset for a backend user, the following User TSconfig can be added:
.. code-block:: typoscript
options.dashboard.dashboardPresetsForNewUsers = default
Where ``default`` is the identifier of the preset.
Even a comma separated list of identifiers is possible:
.. code-block:: typoscript
options.dashboard.dashboardPresetsForNewUsers = default, companyDefault
It is also possible to add another dashboard to the set of dashboards:
.. code-block:: typoscript
options.dashboard.dashboardPresetsForNewUsers := addToList(anotherOne)
If nothing is configured, ``default`` will be used as identifier.
.. seealso::
:ref:`t3tsref:userthetsconfigfield` section of TSconfig manual
explains how to set or register TSconfig for user.
:ref:`t3tsref:typoscript-syntax-syntax-value-modification` explains the usage of
:typoscript:`:=` TypoScript operator.
Documentation/Configuration/WidgetRegistration.rst
+326
View File
@@ -0,0 +1,326 @@
.. include:: /Includes.rst.txt
Widgets need to be provided by an extension, e.g. by ext:dashboard.
They are provided as a PHP class with specific feature sets.
Each of the widgets can be registered with different configurations as documented below.
.. include:: /Shared/DifferenceRegistrationAndImplementation.rst.txt
The below example will use the RSS Widget as a concrete example.
.. _register-new-widget:
===================
Register new Widget
===================
Registration happens through :ref:`Dependency Injection <t3coreapi:DependencyInjection>`
either in :file:`Services.yaml` or :file:`Services.php`.
Both files can exist and will be merged.
:file:`Services.yaml` is recommended and easier to write,
while :file:`Services.php` provide way more flexibility.
.. _register-new-widget-naming:
Naming widgets
--------------
Widgets receive a name in form of ``dashboard.widget.vendor.ext_key.widgetName``.
``vendor``
Should be a snaked version of composer vendor.
``ext_key``
Should be the extension key.
This prevents naming conflicts if multiple 3rd Party extensions are installed.
.. _register-new-widget-services:
Services.yaml file
------------------
In order to turn the PHP class :php:`\TYPO3\CMS\Dashboard\Widgets\RssWidget` into an actual widget,
the following service registration can be used:
.. code-block:: yaml
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
services:
_defaults:
autowire: true
autoconfigure: true
public: false
TYPO3\CMS\Dashboard\:
resource: '../Classes/*'
dashboard.widget.t3news:
class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
arguments:
$buttonProvider: '@dashboard.buttons.t3news'
$options:
feedUrl: 'https://www.typo3.org/rss'
tags:
- name: dashboard.widget
identifier: 't3news'
groupNames: 'news'
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.title'
description: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.description'
iconIdentifier: 'content-widget-rss'
height: 'large'
width: 'medium'
The beginning of the file is not related to the widget itself, but dependency injection in general,
see: :ref:`t3coreapi:configure-dependency-injection-in-extensions`.
.. _register-new-widget-service-configuration:
Service configuration
"""""""""""""""""""""
The last block configured a service called :yaml:`dashboard.widget.t3news`.
This service is configured to use the existing PHP class :php:`TYPO3\CMS\Dashboard\Widgets\RssWidget`.
When creating the instance of this class, an array is provided for the constructor argument :php:`$options`.
This way the same PHP class can be used with different configuration to create new widgets.
The following keys are defined for the service:
.. confval:: class
:type: string
:name: widget-class
:Example: :php:`TYPO3\CMS\Dashboard\Widgets\RssWidget`
Defines the concrete PHP class to use as the implementation of the widget.
.. confval:: arguments
:type: map
:name: widget-arguments
A set of key-value pairs, where the keys are the argument names and the
values are the corresponding argument values. The specific arguments depend
on the widget being configured, and each widget can define custom arguments.
Documentation for the provided widgets is available at :ref:`widgets`.
.. confval:: tags
:type: array of dictionaries
:name: widget-tags
Registers the service as an actual widget for :composer:`typo3/cms-dashboard`. Each entry in
the array is a dictionary that can include various properties like name,
identifier, groupNames, and so on, used to categorize and identify the widget.
See :ref:`register-new-widget-tags-section`.
.. _register-new-widget-tags-section:
Tags Section
""""""""""""
In order to turn the instance into a widget, the tag `dashboard.widget` is configured in `tags` section.
The following options are mandatory and need to be provided:
.. confval:: name
:type: string
:name: widget-tag-name
:required:
:Example: `dashboard.widget`
Always has to be `dashboard.widget`.
Defines that this tag configures the service to be registered as a widget for
ext:dashboard.
.. confval:: identifier
:type: string
:name: widget-tag-identifier
:required:
:Example: `t3news`
Used to store which widgets are currently assigned to dashboards.
Furthermore, it is used to allow access control, see :ref:`permission-handling-of-widgets`.
.. confval:: groupNames
:type: string (comma-separated)
:name: widget-tag-groupNames
:required:
:Example: `news`
Defines which groups should contain the widget.
Used when adding widgets to a dashboard to group related widgets in tabs.
Multiple names can be defined as a comma-separated string, e.g.: `typo3, general`.
See :ref:`create-widget-group` regarding how to create new widget groups.
There is no difference between custom groups and existing groups.
Widgets are registered to all groups by their name.
.. confval:: title
:type: string (language reference)
:name: widget-tag-title
:required:
:Example: `LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.title`
Defines the title of the widget. Language references are resolved.
.. confval:: description
:type: string (language reference)
:name: widget-tag-description
:required:
:Example: `LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.description`
Defines the description of the widget. Language references are resolved.
.. confval:: iconIdentifier
:type: string
:name: widget-tag-iconIdentifier
:required:
:Example: `content-widget-rss`
One of the registered icons.
Icons can be registered through :ref:`t3coreapi:icon`.
The following options are optional and have default values which will be used if not defined:
.. confval:: height
:type: string
:name: widget-tag-height
:Example: `large`
Has to be a string value: `large`, `medium`, or `small`.
.. confval:: width
:type: string
:name: widget-tag-width
:Example: `medium`
Has to be a string value: `large`, `medium`, or `small`.
.. _register-new-widget-splitting:
Splitting up Services.yaml
--------------------------
In case the :file:`Services.yaml` is getting to large, it can be split up.
The official documentation can be found at `symfony.com <https://symfony.com/doc/current/service_container/import.html>`__.
An example to split up all Widget related configuration would look like:
.. code-block:: yaml
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
imports:
- { resource: Backend/DashboardWidgets.yaml }
.. note::
Note that you have to repeat all necessary information, e.g. :yaml:`services:` section with :yaml:`_defaults:` again.
.. code-block:: yaml
:caption: Excerpt from EXT:dashboard/Configuration/Backend/DashboardWidgets.yaml
services:
_defaults:
autowire: true
autoconfigure: true
public: false
TYPO3\CMS\Dashboard\Widgets\:
resource: '../Classes/Widgets/*'
dashboard.buttons.t3news:
class: 'TYPO3\CMS\Dashboard\Widgets\Provider\ButtonProvider'
arguments:
$title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.moreItems'
$link: 'https://news.typo3.com'
$target: '_blank'
dashboard.widget.t3news:
class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
arguments:
$buttonProvider: '@dashboard.buttons.t3news'
$options:
feedUrl: 'https://www.typo3.org/rss'
tags:
- name: dashboard.widget
identifier: 't3news'
groupNames: 'news'
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.title'
description: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.description'
iconIdentifier: 'content-widget-rss'
height: 'large'
width: 'medium'
.. _register-new-widget-services-php:
Services.php File
-----------------
This is not intended for integrators but developers only, as this involves PHP experience.
The typical use case should be solved via :file:`Services.yaml`.
But for more complex situations, it is possible to register widgets via :file:`Services.php`.
Even if :file:`Services.php` contains PHP, it is only executed during compilation of the dependency injection container.
Therefore, it is not possible to check for runtime information like URLs, users, configuration or packages.
Instead, this approach can be used to register widgets only if their service dependencies are available.
The :php:`ContainerBuilder` instance provides a method :php:`hasDefinition()`
that may be used to check for optional dependencies.
Make sure to declare the optional dependencies in :file:`composer.json` as
suggested extensions to ensure packages are ordered correctly in order for
services to be registered with deterministic ordering.
The following example demonstrates how a widget can be registered via :file:`Services.php`:
.. code-block:: php
<?php
declare(strict_types=1);
namespace Vendor\ExtName;
use Vendor\ExtName\Widgets\ExampleWidget;
use Vendor\ExtName\Widgets\Provider\ExampleProvider;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Component\DependencyInjection\Reference;
use TYPO3\CMS\Report\Status;
return function (ContainerConfigurator $configurator, ContainerBuilder $containerBuilder) {
$services = $configurator->services();
if ($containerBuilder->hasDefinition(Status::class)) {
$services->set('widgets.dashboard.widget.exampleWidget')
->class(ExampleWidget::class)
->arg('$buttonProvider', new Reference(ExampleProvider::class))
->arg('$options', ['template' => 'Widget/ExampleWidget'])
->tag('dashboard.widget', [
'identifier' => 'widgets-exampleWidget',
'groupNames' => 'systemInfo',
'title' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:widgets.dashboard.widget.exampleWidget.title',
'description' => 'LLL:EXT:ext_key/Resources/Private/Language/locallang.xlf:widgets.dashboard.widget.exampleWidget.description',
'iconIdentifier' => 'content-widget-list',
'height' => 'medium',
'width' => 'medium'
])
;
}
};
Above example will register a new widget called ``widgets.dashboard.widget.exampleWidget``.
The widget is only registered, in case the extension "reports" is enabled, which
results in the availablity of the :php:`TYPO3\CMS\Report\Status` during container compile time.
Configuration is done in the same way as with :file:`Services.yaml`, except a PHP API is used.
The :php:`new Reference` equals to :yaml:`@` inside the YAML, to reference another service.
:yaml:`arguments:` are registered via :php:`->arg()` method call.
And :yaml:`tags:` are added via :php:`->tag()` method call.
Using this approach, it is possible to provide widgets that depend on 3rd party code,
without requiring this 3rd party code.
Instead the 3rd party code can be suggested and is supported if its installed.
Further information regarding how :file:`Services.php` works in general, can be found
at `symfony.com <https://symfony.com/doc/current/components/dependency_injection.html>`_.
Make sure to switch code examples from YAML to PHP.
Documentation/Configuration/WidgetSettings.rst
+59
View File
@@ -0,0 +1,59 @@
.. include:: /Includes.rst.txt
.. _settings:
=====================================
Adjust settings of registered widgets
=====================================
.. versionadded:: 14.0
`Configurable Dashboard Widgets <https://docs.typo3.org/permalink/changelog:feature-107036-1738837673>`_
have been introduced with TYPO3 14.0.
.. contents:: Table of contents
.. _adjust-settings-of-widget-why:
.. _configurable-widgets:
Configurable dashboard widgets
------------------------------
.. versionadded:: 14.0
Dashboard widgets can be configured on a per-instance level using the Settings
API. This allows widget authors to define configurable settings that editors
can modify directly from the dashboard interface, making widgets more
flexible and user-friendly.
Examples are URLs for RSS feeds, limits on displayed items, or categories for
filtering content.
Each widget instance maintains its own configuration, enabling multiple
instances of the same widget type with different settings on the same or
different dashboards.
Configurable widgets display a `settings (cog) icon <https://docs.typo3.org/permalink/typo3/cms-dashboard:widgets-configuration>`_
and allow editors to configure the widget in a modal dialog.
Extension authors can implement :php-short:`\TYPO3\CMS\Dashboard\Widgets\WidgetRendererInterface`
to make their widgets configurable:
`Configurable dashboard widget implementation <https://docs.typo3.org/permalink/typo3/cms-dashboard:configurable-widget-implementation>`_.
.. _adjust-settings-of-widget:
Adjust settings of registered widgets
=====================================
Each widget is registered with an identifier, and all :file:`Services.*` files are merged.
Therefore it is possible to override widgets.
In order to override, the extension which should override has to be loaded after the extension that registered the widget.
Concrete options depend on the widget to configure.
Each widget should provide documentation covering all possible options and their meaning.
For delivered widgets by EXT:dashboard see :ref:`widgets`.
In case a widget defined by EXT:dashboard should be adjusted,
the extension has to define a dependency to EXT:dashboard.
Afterwards the widget can be registered again, with different options. See
:ref:`register-new-widget` to get an in depth example of how to register a widget.
Documentation/Configuration/WidgetTemplate.rst
+26
View File
@@ -0,0 +1,26 @@
.. include:: /Includes.rst.txt
.. _adjust-template-of-widget:
==========================
Adjust template of widgets
==========================
When adding own widgets, it might be necessary to provide custom templates.
In such a case the file path containing the template files needs to be added.
This is done using a :file:`Configuration/page.tsconfig` file, see
:doc:`changelog <ext_core:Changelog/12.0/Feature-96812-OverrideBackendTemplatesWithTSconfig>` and
:doc:`changelog <ext_core:Changelog/12.0/Feature-96614-AutomaticInclusionOfPageTsConfigOfExtensions>`
for details on this:
.. code-block:: typoscript
# Pattern: templates.typo3/cms-dashboard."something-unique" = "overriding-extension-composer-name":"entry-path"
templates.typo3/cms-dashboard.1644485473 = myvendor/myext:Resources/Private
A template file can then be added to path :file:`Resources/Private/Templates/Widgets/MyExtensionsGreatWidget.html`
and is referenced in the PHP class using :php:`->render('Widgets/MyExtensionsGreatWidget');`. The registration
into namespace :php:`typo3/cms-dashboard` is shared between all extensions. It is thus a good idea to give
template file names unique names (for instance by prefixing them with the extension name), to avoid situations
where templates from multiple extensions that provide different widgets override each other.