TYPO3 v15 dev-main snapshot ()
This commit is contained in:
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,111 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _adding-buttons:
|
||||
|
||||
=======================
|
||||
Adding button to Widget
|
||||
=======================
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
|
||||
In order to add a button to a widget, a new dependency to an :php:`ButtonProviderInterface` can be added.
|
||||
|
||||
.. _adding-buttons-template:
|
||||
|
||||
Template
|
||||
--------
|
||||
|
||||
The output itself is done inside of the Fluid template, for example :file:`Resources/Private/Templates/Widget/RssWidget.html`:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<f:if condition="{button}">
|
||||
<a href="{button.link}" target="{button.target}" class="widget-cta">
|
||||
{f:translate(id: button.title, default: button.title)}
|
||||
</a>
|
||||
</f:if>
|
||||
|
||||
.. _adding-buttons-configuration:
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The configuration is done through an configured Instance of the dependency, for example :file:`Services.yaml`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
services:
|
||||
# …
|
||||
|
||||
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'
|
||||
# …
|
||||
|
||||
See also: :php:`\TYPO3\CMS\Dashboard\Widgets\Provider\ButtonProvider`.
|
||||
|
||||
.. confval:: $title
|
||||
:type: string
|
||||
:name: button-title
|
||||
|
||||
The title used for the button. E.g. an ``LLL:EXT:`` reference like
|
||||
``LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.moreItems``.
|
||||
|
||||
.. confval:: $link
|
||||
:type: string
|
||||
:name: button-link
|
||||
|
||||
The link to use for the button. Clicking the button will open the link.
|
||||
|
||||
.. confval:: $target
|
||||
:type: string
|
||||
:name: button-target
|
||||
|
||||
The target of the link, e.g. ``_blank``.
|
||||
``LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.moreItems``.
|
||||
|
||||
|
||||
.. _adding-buttons-implementation:
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
|
||||
An example implementation could look like this:
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Classes/Widgets/RssWidget.php
|
||||
|
||||
class RssWidget implements WidgetInterface
|
||||
{
|
||||
public function __construct(
|
||||
// …
|
||||
private readonly ButtonProviderInterface $buttonProvider = null,
|
||||
// …
|
||||
) {
|
||||
}
|
||||
|
||||
public function renderWidgetContent(): string
|
||||
{
|
||||
// …
|
||||
$this->view->assignMultiple([
|
||||
// …
|
||||
'button' => $this->buttonProvider,
|
||||
// …
|
||||
]);
|
||||
// …
|
||||
}
|
||||
|
||||
public function getOptions(): array
|
||||
{
|
||||
return $this->options;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
:navigation-title: Configurable widgets
|
||||
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _configurable-widget-implementation:
|
||||
|
||||
============================================
|
||||
Configurable dashboard widget implementation
|
||||
============================================
|
||||
|
||||
.. versionadded:: 14.0
|
||||
`Configurable Dashboard Widgets <https://docs.typo3.org/permalink/changelog:feature-107036-1738837673>`_
|
||||
have been introduced with TYPO3 14.0.
|
||||
|
||||
Widget authors can implement configurable widgets by using to the
|
||||
renderer interface :php:`TYPO3\CMS\Dashboard\Widgets\WidgetRendererInterface`
|
||||
which allows to defining settings in their widget renderer.
|
||||
|
||||
Settings are automatically validated and processed using the Settings API.
|
||||
All types that are available for site settings definition are available:
|
||||
`Definition types <https://docs.typo3.org/permalink/t3coreapi:definition-types>`_.
|
||||
|
||||
.. seealso::
|
||||
:php:`TYPO3\CMS\Dashboard\Widgets\RssWidget` is a configurable widget
|
||||
implementation.
|
||||
|
||||
.. _configurable-widget-implementation-example:
|
||||
|
||||
Example: A configurable widget implementation
|
||||
=============================================
|
||||
|
||||
.. literalinclude:: _codesnippets/_ConfigurableWidget.php.inc
|
||||
:language: php
|
||||
:caption: EXT:my_extension/Classes/Widgets/ConfigurableWidget.php
|
||||
@@ -0,0 +1,174 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _graph-widget-implementation:
|
||||
|
||||
======================
|
||||
Implement graph widget
|
||||
======================
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
|
||||
First of all a new data provider is required, which will provide the data for the chart.
|
||||
Next the data will be provided to the widget instance, which will be rendered with JavaScript modules and Css.
|
||||
|
||||
To make the dashboard aware of this workflow, some interfaces come together:
|
||||
|
||||
* :php:`EventDataInterface`
|
||||
|
||||
* :php:`AdditionalCssInterface`
|
||||
|
||||
Also the existing template file :file:`Widget/ChartWidget` is used, which provides necessary HTML to render the chart.
|
||||
The provided ``eventData`` will be rendered as a chart and therefore has to match the expected structure.
|
||||
|
||||
An example would be :file:`Classes/Widgets/BarChartWidget.php`:
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Classes/Widgets/BarChartWidget.php
|
||||
|
||||
class BarChartWidget implements WidgetInterface, EventDataInterface, AdditionalCssInterface
|
||||
{
|
||||
public function __construct(
|
||||
// …
|
||||
private readonly ChartDataProviderInterface $dataProvider,
|
||||
// …
|
||||
) {
|
||||
// …
|
||||
$this->dataProvider = $dataProvider;
|
||||
// …
|
||||
}
|
||||
|
||||
public function renderWidgetContent(): string
|
||||
{
|
||||
// …
|
||||
$this->view->assignMultiple([
|
||||
// …
|
||||
'configuration' => $this->configuration,
|
||||
// …
|
||||
]);
|
||||
// …
|
||||
}
|
||||
|
||||
public function getEventData(): array
|
||||
{
|
||||
return [
|
||||
'graphConfig' => [
|
||||
'type' => 'bar',
|
||||
'options' => [
|
||||
// …
|
||||
],
|
||||
'data' => $this->dataProvider->getChartData(),
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
public function getCssFiles(): array
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
public function getOptions(): array
|
||||
{
|
||||
return $this->options;
|
||||
}
|
||||
}
|
||||
|
||||
Together with :file:`Services.yaml`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
services:
|
||||
dashboard.widget.sysLogErrors:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\BarChartWidget'
|
||||
arguments:
|
||||
# …
|
||||
$dataProvider: '@TYPO3\CMS\Dashboard\Widgets\Provider\SysLogErrorsDataProvider'
|
||||
# …
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
|
||||
The configuration adds necessary CSS classes, as well as the ``dataProvider`` to use.
|
||||
The provider implements :php:`ChartDataProviderInterface` and could look like the following.
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Classes/Widgets/Provider/SysLogErrorsDataProvider
|
||||
|
||||
class SysLogErrorsDataProvider implements ChartDataProviderInterface
|
||||
{
|
||||
/**
|
||||
* Number of days to gather information for.
|
||||
*
|
||||
* @var int
|
||||
*/
|
||||
protected $days = 31;
|
||||
|
||||
/**
|
||||
* @var array
|
||||
*/
|
||||
protected $labels = [];
|
||||
|
||||
/**
|
||||
* @var array
|
||||
*/
|
||||
protected $data = [];
|
||||
|
||||
public function __construct(int $days = 31)
|
||||
{
|
||||
$this->days = $days;
|
||||
}
|
||||
|
||||
public function getChartData(): array
|
||||
{
|
||||
$this->calculateDataForLastDays();
|
||||
return [
|
||||
'labels' => $this->labels,
|
||||
'datasets' => [
|
||||
[
|
||||
'label' => $this->getLanguageService()->sL('LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.sysLogErrors.chart.dataSet.0'),
|
||||
'backgroundColor' => WidgetApi::getDefaultChartColors()[0],
|
||||
'border' => 0,
|
||||
'data' => $this->data
|
||||
]
|
||||
]
|
||||
];
|
||||
}
|
||||
|
||||
protected function getNumberOfErrorsInPeriod(int $start, int $end): int
|
||||
{
|
||||
$queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable('sys_log');
|
||||
return (int)$queryBuilder
|
||||
->count('*')
|
||||
->from('sys_log')
|
||||
->where(
|
||||
$queryBuilder->expr()->eq(
|
||||
'type',
|
||||
$queryBuilder->createNamedParameter(SystemLogType::ERROR, Connection::PARAM_INT)
|
||||
),
|
||||
$queryBuilder->expr()->gte(
|
||||
'tstamp',
|
||||
$queryBuilder->createNamedParameter($start, Connection::PARAM_INT)
|
||||
),
|
||||
$queryBuilder->expr()->lte(
|
||||
'tstamp',
|
||||
$queryBuilder->createNamedParameter($end, Connection::PARAM_INT)
|
||||
)
|
||||
)
|
||||
->execute()
|
||||
->fetchColumn();
|
||||
}
|
||||
|
||||
protected function calculateDataForLastDays(): void
|
||||
{
|
||||
$format = $GLOBALS['TYPO3_CONF_VARS']['SYS']['ddmmyy'] ?: 'Y-m-d';
|
||||
for ($daysBefore = $this->days; $daysBefore >= 0; $daysBefore--) {
|
||||
$this->labels[] = date($format, strtotime('-' . $daysBefore . ' day'));
|
||||
$startPeriod = strtotime('-' . $daysBefore . ' day 0:00:00');
|
||||
$endPeriod = strtotime('-' . $daysBefore . ' day 23:59:59');
|
||||
$this->data[] = $this->getNumberOfErrorsInPeriod($startPeriod, $endPeriod);
|
||||
}
|
||||
}
|
||||
|
||||
protected function getLanguageService(): LanguageService
|
||||
{
|
||||
return $GLOBALS['LANG'];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _for-developer:
|
||||
|
||||
==============
|
||||
For Developers
|
||||
==============
|
||||
|
||||
Target group: **Developers**
|
||||
|
||||
Welcome to our small dashboard introduction.
|
||||
We will explain how to create widget groups and implement widgets.
|
||||
|
||||
.. include:: /Shared/DifferenceRegistrationAndImplementation.rst.txt
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:titlesonly:
|
||||
|
||||
WidgetImplementation
|
||||
ConfigurableWidgets
|
||||
MakeRefreshable
|
||||
AddingButtons
|
||||
GraphWidgetImplementation
|
||||
Interfaces
|
||||
@@ -0,0 +1,178 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _interfaces:
|
||||
|
||||
==========
|
||||
Interfaces
|
||||
==========
|
||||
|
||||
The following list provides information for all necessary interfaces that are used inside of this documentation.
|
||||
For up to date information, please check the source code.
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
|
||||
.. php:class:: WidgetInterface
|
||||
|
||||
Has to be implemented by all widgets.
|
||||
This interface defines public API used by ext:dashboard to interact with widgets.
|
||||
|
||||
.. php:method:: renderWidgetContent()
|
||||
|
||||
:returntype: string
|
||||
:returns: The rendered HTML to display.
|
||||
|
||||
.. php:method:: getOptions()
|
||||
|
||||
:returntype: array
|
||||
:returns: The options of the widget as set in the registration.
|
||||
|
||||
.. php:class:: RequestAwareWidgetInterface
|
||||
|
||||
This interface declares a widget has a dependency to the current PSR-7 request.
|
||||
When implemented, the dashboard controller will call :php:`setRequest()` immediately
|
||||
after widget instantiation to hand over the current request. Widgets that rely on
|
||||
:php:`BackendViewFactory` typically need the current request.
|
||||
|
||||
.. php:method:: setRequest(ServerRequestInterface $request)
|
||||
|
||||
:returntype: void
|
||||
|
||||
.. php:class:: WidgetConfigurationInterface
|
||||
|
||||
Used internally in ext:dashboard.
|
||||
Used to separate internal configuration from widgets.
|
||||
Can be required in widget classes and passed to view.
|
||||
|
||||
.. php:method:: getIdentifier()
|
||||
|
||||
:returntype: string
|
||||
:returns: Unique identifer of a widget.
|
||||
|
||||
.. php:method:: getServiceName()
|
||||
|
||||
:returntype: string
|
||||
:returns: Service name providing the widget implementation.
|
||||
|
||||
.. php:method:: getGroupNames()
|
||||
|
||||
:returntype: array
|
||||
:returns: Group names associated to this widget.
|
||||
|
||||
.. php:method:: getTitle()
|
||||
|
||||
:returntype: string
|
||||
:returns: Title of a widget, this is used for the widget selector.
|
||||
|
||||
.. php:method:: getDescription()
|
||||
|
||||
:returntype: string
|
||||
:returns: Description of a widget, this is used for the widget selector.
|
||||
|
||||
.. php:method:: getIconIdentifier()
|
||||
|
||||
:returntype: string
|
||||
:returns: Icon identifier of a widget, this is used for the widget selector.
|
||||
|
||||
.. php:method:: getHeight()
|
||||
|
||||
:returntype: int
|
||||
:returns: Height of a widget in rows (1-6).
|
||||
|
||||
.. php:method:: getWidth()
|
||||
|
||||
:returntype: int
|
||||
:returns: Width of a widget in columns (1-4).
|
||||
|
||||
.. php:class:: AdditionalJavaScriptInterface
|
||||
|
||||
Widgets implementing this interface will add the provided JavaScript files.
|
||||
Those files will be loaded in dashboard view if the widget is added at least once.
|
||||
|
||||
.. php:method:: getJsFiles()
|
||||
|
||||
Returns a list of JavaScript file names that should be included, e.g.:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
return [
|
||||
'EXT:my_extension/Resources/Public/JavaScript/file.js',
|
||||
'EXT:my_extension/Resources/Public/JavaScript/file2.js',
|
||||
];
|
||||
|
||||
:returntype: array
|
||||
:returns: List of JS files to load.
|
||||
|
||||
.. php:class:: AdditionalCssInterface
|
||||
|
||||
Widgets implementing this interface will add the provided Css files.
|
||||
Those files will be loaded in dashboard view if the widget is added at least once.
|
||||
|
||||
.. php:method:: getCssFiles()
|
||||
|
||||
Returns a list of Css file names that should be included, e.g.:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
return [
|
||||
'EXT:my_extension/Resources/Public/Css/widgets.css',
|
||||
'EXT:my_extension/Resources/Public/Css/list-widget.css',
|
||||
];
|
||||
|
||||
:returntype: array
|
||||
:returns: List of Css files to load.
|
||||
|
||||
.. php:class:: ButtonProviderInterface
|
||||
|
||||
.. php:method:: getTitle()
|
||||
|
||||
:returntype: string
|
||||
:returns: The title used for the button. E.g. an ``LLL:EXT:`` reference like
|
||||
``LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.moreItems``.
|
||||
|
||||
.. php:method:: getLink()
|
||||
|
||||
:returntype: string
|
||||
:returns: The link to use for the button. Clicking the button will open the link.
|
||||
|
||||
.. php:method:: getTarget()
|
||||
|
||||
:returntype: string
|
||||
:returns: The target of the link, e.g. ``_blank``.
|
||||
``LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.t3news.moreItems``.
|
||||
|
||||
.. php:class:: NumberWithIconDataProviderInterface
|
||||
|
||||
.. php:method:: getNumber()
|
||||
|
||||
:returntype: integer
|
||||
:returns: The number to display for an number widget.
|
||||
|
||||
.. php:class:: EventDataInterface
|
||||
|
||||
.. php:method:: getEventData()
|
||||
|
||||
:returntype: array
|
||||
:returns: Returns data which should be send to the widget as JSON encoded value.
|
||||
|
||||
.. php:class:: ChartDataProviderInterface
|
||||
|
||||
.. php:method:: getChartData()
|
||||
|
||||
:returntype: array
|
||||
:returns: Provide the data for a graph.
|
||||
The data and options you have depend on the type of chart.
|
||||
More information can be found in the documentation of the specific type:
|
||||
|
||||
Bar
|
||||
https://www.chartjs.org/docs/latest/charts/bar.html#data-structure
|
||||
|
||||
Doughnut
|
||||
https://www.chartjs.org/docs/latest/charts/doughnut.html#data-structure
|
||||
|
||||
.. php:class:: ListDataProviderInterface
|
||||
|
||||
.. php:method:: getItems()
|
||||
|
||||
:returntype: array
|
||||
:returns: Provide the array if items.
|
||||
Each entry should be a single string.
|
||||
@@ -0,0 +1,83 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _make-refreshable:
|
||||
|
||||
==================
|
||||
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
|
||||
: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:
|
||||
$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 implement the :php:`getOptions()` method, returning :php:`$this->options`,
|
||||
to the corresponding classes. Otherwise the refresh option won't have any
|
||||
effect.
|
||||
|
||||
.. _refresh-button:
|
||||
|
||||
Enable the refresh button
|
||||
-------------------------
|
||||
|
||||
Widgets can render a refresh button to allow users to manually refresh them.
|
||||
|
||||
This is done by passing the value :php:`['refreshAvailable'] = true;` back
|
||||
via :php:`getOptions()` method of the widget.
|
||||
|
||||
All TYPO3 Core widgets implement this behaviour and allow integrators to
|
||||
configure the option:
|
||||
|
||||
.. include:: /Widgets/Options/RefreshAvailable.rst.txt
|
||||
|
||||
.. _refresh-javascript:
|
||||
|
||||
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 :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.
|
||||
|
||||
To refresh a widget, 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}));
|
||||
|
||||
See :ref:`implement-new-widget-custom-js` to learn how to add custom JavaScript.
|
||||
@@ -0,0 +1,195 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _implement-new-widget:
|
||||
|
||||
====================
|
||||
Implement new widget
|
||||
====================
|
||||
|
||||
.. versionadded:: 14.0
|
||||
`Configurable Dashboard Widgets <https://docs.typo3.org/permalink/changelog:feature-107036-1738837673>`_
|
||||
have been introduced with TYPO3 14.0.
|
||||
|
||||
See also
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
|
||||
.. seealso::
|
||||
|
||||
For information regarding registration of widgets, see: :ref:`register-new-widget`.
|
||||
This section describes the implementation of new widgets for developers.
|
||||
|
||||
Each extension can provide multiple Widgets.
|
||||
ext:dashboard already ships with some widget implementations.
|
||||
|
||||
Each widget has to be implemented as a PHP class.
|
||||
The PHP class defines the concrete implementation and features of a widget,
|
||||
while registration adds necessary options for a concrete instance of a widget.
|
||||
|
||||
For example a TYPO3.org RSS Widget would consist of an :php:`RssWidget` PHP class.
|
||||
This class would provide the implementation to fetch rss news and display them.
|
||||
The concrete registration will provide the URL to RSS feed.
|
||||
|
||||
.. _widget-php-class:
|
||||
|
||||
PHP class
|
||||
---------
|
||||
|
||||
Each Widget has to be a PHP class.
|
||||
This class has to implement the :php:`WidgetInterface` and could look like this:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
class RssWidget implements WidgetInterface, RequestAwareWidgetInterface
|
||||
{
|
||||
private ServerRequestInterface $request;
|
||||
|
||||
public function __construct(
|
||||
private readonly WidgetConfigurationInterface $configuration,
|
||||
private readonly Cache $cache,
|
||||
private readonly BackendViewFactory $backendViewFactory,
|
||||
private readonly ?ButtonProviderInterface $buttonProvider = null,
|
||||
private readonly array $options = []
|
||||
) {
|
||||
}
|
||||
|
||||
public function setRequest(ServerRequestInterface $request): void
|
||||
{
|
||||
$this->request = $request;
|
||||
}
|
||||
|
||||
public function renderWidgetContent(): string
|
||||
{
|
||||
$view = $this->backendViewFactory->create($this->request);
|
||||
$view->assignMultiple([
|
||||
'items' => $this->getRssItems(),
|
||||
'options' => $this->options,
|
||||
'button' => $this->getButton(),
|
||||
'configuration' => $this->configuration,
|
||||
]);
|
||||
return $view->render('Widget/RssWidget');
|
||||
}
|
||||
|
||||
protected function getRssItems(): array
|
||||
{
|
||||
$items = [];
|
||||
// Logic to populate $items array
|
||||
return $items;
|
||||
}
|
||||
|
||||
public function getOptions(): array
|
||||
{
|
||||
return $this->options;
|
||||
}
|
||||
}
|
||||
|
||||
The class should always provide documentation how to use in :file:`Services.yaml`.
|
||||
The above class is documented at :ref:`rss-widget`.
|
||||
The documentation should provide all possible options and an concrete example.
|
||||
It should make it possible for integrators to register new widgets using the implementation.
|
||||
|
||||
The difference between :php:`$options` and :php:`$configuration` in above example is the following:
|
||||
:php:`$options` are the options for this implementation which can be provided through :file:`Services.yaml`.
|
||||
:php:`$configuration` is an instance of :php:`WidgetConfigurationInterface`
|
||||
holding all internal configuration, like icon identifier.
|
||||
|
||||
.. _implement-new-widget-fluid:
|
||||
|
||||
Using Fluid
|
||||
-----------
|
||||
|
||||
Most widgets will need a template.
|
||||
Therefore each widget can define :php:`BackendViewFactory` as requirement for DI in
|
||||
constructor, like done in RSS example.
|
||||
|
||||
|
||||
.. _implement-new-widget-custom-js:
|
||||
|
||||
Providing custom JS
|
||||
-------------------
|
||||
|
||||
There are two ways to add JavaScript for an widget:
|
||||
|
||||
JavaScript module
|
||||
Implement :php:`\TYPO3\CMS\Dashboard\Widgets\JavaScriptInterface`:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
|
||||
class ExampleChartWidget implements JavaScriptInterface
|
||||
{
|
||||
// ...
|
||||
public function getJavaScriptModuleInstructions(): array
|
||||
{
|
||||
return [
|
||||
JavaScriptModuleInstruction::create(
|
||||
'@myvendor/my-extension/module-name.js'
|
||||
)->invoke('initialize'),
|
||||
JavaScriptModuleInstruction::create(
|
||||
'@myvendor/my-extension/module-name2.js'
|
||||
)->invoke('initialize'),
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`t3coreapi:backend-javascript-es6` for more info about JavaScript in TYPO3 Backend.
|
||||
|
||||
Plain JS files
|
||||
Implement :php:`AdditionalJavaScriptInterface`:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
class RssWidget implements WidgetInterface, AdditionalJavaScriptInterface
|
||||
{
|
||||
public function getJsFiles(): array
|
||||
{
|
||||
return [
|
||||
'EXT:my_extension/Resources/Public/JavaScript/file.js',
|
||||
'EXT:my_extension/Resources/Public/JavaScript/file2.js',
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
JavaScript
|
||||
Implement :php:`\TYPO3\CMS\Dashboard\Widgets\JavaScriptInterface`:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
class ExampleChartWidget implements JavaScriptInterface
|
||||
{
|
||||
// ...
|
||||
public function getJavaScriptModuleInstructions(): array
|
||||
{
|
||||
return [
|
||||
JavaScriptModuleInstruction::create(
|
||||
'@typo3/dashboard/chart-initializer.js'
|
||||
)->invoke('initialize'),
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
All ways can be combined.
|
||||
|
||||
.. _custom-css:
|
||||
|
||||
Providing custom CSS
|
||||
--------------------
|
||||
|
||||
It is possible to add custom Css to style widgets.
|
||||
|
||||
Implement :php:`AdditionalCssInterface`:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
class RssWidget implements WidgetInterface, AdditionalCssInterface
|
||||
{
|
||||
public function getCssFiles(): array
|
||||
{
|
||||
return [
|
||||
'EXT:my_extension/Resources/Public/Css/widgets.css',
|
||||
'EXT:my_extension/Resources/Public/Css/list-widget.css',
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Dashboard\Widgets\WidgetContext;
|
||||
use TYPO3\CMS\Dashboard\Widgets\WidgetRendererInterface;
|
||||
use TYPO3\CMS\Dashboard\Widgets\WidgetResult;
|
||||
use TYPO3\CMS\Core\Settings\SettingDefinition;
|
||||
|
||||
class ConfigurableWidget implements WidgetRendererInterface
|
||||
{
|
||||
public function getSettingsDefinitions(): array
|
||||
{
|
||||
return [
|
||||
new SettingDefinition(
|
||||
key: 'title',
|
||||
type: 'string',
|
||||
default: 'Default Title',
|
||||
label: 'LLL:EXT:my_extension/Resources/Private/Language/locallang_my_widget.xlf:settings.label',
|
||||
description: 'LLL:EXT:my_extension/Resources/Private/Language/locallang_my_widget.xlf:settings.description.label',
|
||||
),
|
||||
new SettingDefinition(
|
||||
key: 'limit',
|
||||
type: 'int',
|
||||
default: 10,
|
||||
label: 'LLL:EXT:my_extension/Resources/Private/Language/locallang_my_widget.xlf:settings.limit',
|
||||
description: 'LLL:EXT:my_extension/Resources/Private/Language/locallang_my_widget.xlf:settings.description.limit',
|
||||
),
|
||||
];
|
||||
}
|
||||
|
||||
public function renderWidget(WidgetContext $context): WidgetResult
|
||||
{
|
||||
$settings = $context->settings;
|
||||
$title = $settings->get('title');
|
||||
$limit = $settings->get('limit');
|
||||
|
||||
// Use settings to customize widget output
|
||||
return new WidgetResult(
|
||||
content: '<!-- widget content -->',
|
||||
label: $title,
|
||||
refreshable: true
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _for-editors:
|
||||
|
||||
===========
|
||||
For Editors
|
||||
===========
|
||||
|
||||
Target group: **Editors**
|
||||
|
||||
Welcome to our small dashboard introduction.
|
||||
We will explain the basic usage of the TYPO3 dashboard.
|
||||
|
||||
.. _opening-dashboard:
|
||||
|
||||
Opening Dashboard
|
||||
=================
|
||||
|
||||
By default the dashboard is opened when logging into the backend.
|
||||
|
||||
The dashboard can be opened at any time by clicking the entry
|
||||
:guilabel:`Dashboard` in the module menu.
|
||||
|
||||
.. figure:: /Images/DashboardPosition.png
|
||||
:align: center
|
||||
|
||||
Open the dashboard by clicking on :guilabel:`Dashboard`.
|
||||
|
||||
.. note::
|
||||
If the entry :guilabel:`Dashboard` is not visible in the menu there are two
|
||||
possible causes:
|
||||
|
||||
* You lack sufficient rights to view the dashboard.
|
||||
* The system extension `dashboard` was not installed on your system.
|
||||
|
||||
Ask your administrator about this.
|
||||
|
||||
.. _adding-dashboard:
|
||||
|
||||
Adding Dashboard
|
||||
================
|
||||
|
||||
The EXT:dashboard allows to have multiple dashboards.
|
||||
Switching between different dashboards is possible by using the corresponding tab.
|
||||
|
||||
In order to add further dashboards, press the :guilabel:`+` sign.
|
||||
|
||||
.. figure:: /Images/DashboardTabs.png
|
||||
:align: center
|
||||
|
||||
Tabs allowing to switch and add dashboards.
|
||||
|
||||
A wizard should open which allows to add the new dashboard.
|
||||
|
||||
There you can select a preset. At least the default preset, which is shipped
|
||||
by core should be available. Depending on system configuration further dashboard
|
||||
presets might be available.
|
||||
|
||||
.. figure:: /Images/DashboardWizard.png
|
||||
:align: center
|
||||
|
||||
Wizard to add a new dashboard.
|
||||
|
||||
.. _editing-dashboard:
|
||||
|
||||
Editing Dashboard
|
||||
=================
|
||||
|
||||
Existing dashboards can be edited and deleted.
|
||||
On the right side of the tab bar are the icons which allow deletion and adjusting
|
||||
settings of the currently active dashboard.
|
||||
|
||||
.. figure:: /Images/DashboardTabs.png
|
||||
:align: center
|
||||
|
||||
Icons on the right side of the tab bar allow adjusting settings or deletion of
|
||||
the currently selected dashboard.
|
||||
|
||||
.. _adding-widgets:
|
||||
|
||||
Adding Widgets
|
||||
==============
|
||||
|
||||
Widgets can be added to a dashboard.
|
||||
Dashboards which do not contain any widget yet, offer a dialog in the middle of
|
||||
the screen, which allows to add one or more widgets to the current dashboard.
|
||||
|
||||
All dashboards allow to add further widgets in the lower right corner through the
|
||||
:guilabel:`+` Icon.
|
||||
|
||||
.. figure:: /Images/AddWidget.png
|
||||
:align: center
|
||||
|
||||
Empty dashboard with possibilities to add new widgets.
|
||||
|
||||
Once the action to add a new widget was triggered, a wizard opens which allows to
|
||||
select the widget to add.
|
||||
|
||||
Widgets are grouped in tabs and can be added by clicking on them.
|
||||
|
||||
.. figure:: /Images/WidgetWizard.png
|
||||
:align: center
|
||||
|
||||
Wizard to select a new widget that will be added to the active dashboard.
|
||||
|
||||
.. _widgets-configuration:
|
||||
|
||||
Widget configuration
|
||||
====================
|
||||
|
||||
.. versionadded:: 14.0
|
||||
`Configurable Dashboard Widgets <https://docs.typo3.org/permalink/changelog:feature-107036-1738837673>`_
|
||||
have been introduced with TYPO3 14.0.
|
||||
|
||||
* Dashboard widgets display a settings (cog) icon when they support configuration
|
||||
* Clicking the settings icon opens a modal dialog with configurable options
|
||||
* Settings are applied immediately after saving, with the widget content
|
||||
refreshing automatically
|
||||
* Each widget can be configured independently per user / per instance
|
||||
|
||||
|
||||
.. figure:: /Images/DashboardConfiguration.png
|
||||
:alt: Screenshot of the dashboard widget "RSS Feed" with the location of the settings (cog) icon
|
||||
|
||||
Click the settings (cog) icon to configure a feed
|
||||
|
||||
Extension authors can make their widgets configurable:
|
||||
`Configurable dashboard widget implementation <https://docs.typo3.org/permalink/typo3/cms-dashboard:configurable-widget-implementation>`_.
|
||||
|
||||
.. _moving-widgets:
|
||||
|
||||
Moving Widgets
|
||||
==============
|
||||
|
||||
Widgets can be moved around. Therefore a widget needs to be hovered.
|
||||
If a widget is hovered some icons appear in the upper right corner of the widget.
|
||||
|
||||
To move the widget, click and hold left mouse button on the cross icon.
|
||||
Then move to the target position.
|
||||
|
||||
.. figure:: /Images/WidgetMove.png
|
||||
:align: center
|
||||
|
||||
Widget in hover mode with additional icons in upper right corner.
|
||||
|
||||
.. _deleting-widgets:
|
||||
|
||||
Deleting Widgets
|
||||
================
|
||||
|
||||
To delete a widget, the widget needs to be hovered.
|
||||
If a widget is hovered some icons appear in the upper right corner of the widget.
|
||||
|
||||
Click the trash icon which appears to delete the widget.
|
||||
|
||||
.. figure:: /Images/WidgetMove.png
|
||||
:align: center
|
||||
|
||||
Widget in hover mode with additional icons in upper right corner.
|
||||
|
||||
In order to prevent accidentally deletion, a modal is shown to confirm deletion.
|
||||
Confirm by clicking the :guilabel:`Remove` button.
|
||||
|
||||
.. figure:: /Images/WidgetDelete.png
|
||||
:align: center
|
||||
|
||||
Modal to confirm deletion of widget.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
@@ -0,0 +1 @@
|
||||
.. You can put central messages to display on all pages here
|
||||
@@ -0,0 +1,55 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _start:
|
||||
|
||||
===============
|
||||
TYPO3 Dashboard
|
||||
===============
|
||||
|
||||
:Extension key:
|
||||
dashboard
|
||||
|
||||
:Package name:
|
||||
typo3/cms-dashboard
|
||||
|
||||
:Version:
|
||||
|release|
|
||||
|
||||
:Language:
|
||||
en
|
||||
|
||||
:Author:
|
||||
TYPO3 contributors
|
||||
|
||||
:License:
|
||||
This document is published under the
|
||||
`Open Content License <https://www.openhub.net/licenses/opl>`__.
|
||||
|
||||
:Rendered:
|
||||
|today|
|
||||
|
||||
----
|
||||
|
||||
This TYPO3 backend module is used to configure and create backend widgets.
|
||||
|
||||
----
|
||||
|
||||
**Table of Contents:**
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
Introduction/Index
|
||||
Installation/Index
|
||||
Editor/Index
|
||||
Configuration/Index
|
||||
Developer/Index
|
||||
Widgets/Index
|
||||
|
||||
.. Meta Menu
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Sitemap
|
||||
@@ -0,0 +1,54 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _installation:
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Target group: **Administrators**
|
||||
|
||||
This extension is part of the TYPO3 Core, but not installed by default.
|
||||
|
||||
.. contents:: Table of contents
|
||||
:local:
|
||||
|
||||
.. _installation-composer:
|
||||
|
||||
Installation with Composer
|
||||
==========================
|
||||
|
||||
Check whether you are already using the extension with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
composer show | grep dashboard
|
||||
|
||||
This should either give you no result or something similar to:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
typo3/cms-dashboard v12.4.11
|
||||
|
||||
If it is not installed yet, use the ``composer require`` command to install
|
||||
the extension:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
composer require typo3/cms-dashboard
|
||||
|
||||
The given version depends on the version of the TYPO3 Core you are using.
|
||||
|
||||
.. _installation-no-composer:
|
||||
|
||||
Installation without Composer
|
||||
=============================
|
||||
|
||||
In an installation without Composer, the extension is already shipped. You just have to activate it.
|
||||
Head over to the extension manager and activate the extension.
|
||||
|
||||
.. figure:: /Images/InstallActivate.png
|
||||
:class: with-shadow
|
||||
:alt: Extension manager showing Dashboard extension
|
||||
|
||||
Extension manager showing Dashboard extension
|
||||
@@ -0,0 +1,16 @@
|
||||
:navigation-title: Introduction
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _introduction:
|
||||
|
||||
==============================
|
||||
Introduction: What does it do?
|
||||
==============================
|
||||
|
||||
This extension provides a new TYPO3 backend module "Dashboard".
|
||||
Users can create multiple dashboards visible in this module, and switch between those
|
||||
dashboards.
|
||||
Each of the dashboards can have multiple widgets.
|
||||
|
||||
Developers are able to create new widgets.
|
||||
Integrators and developers are able to register new widgets through configuration.
|
||||
@@ -0,0 +1,13 @@
|
||||
.. note::
|
||||
|
||||
Difference between **registration** of widgets and **implementation** of widgets:
|
||||
|
||||
Widgets provide some functionality, e.g. collect system log errors over a time span.
|
||||
This functionality is provided by the implementation, a PHP class with some code.
|
||||
The registration is done in :file:`Services.yaml`,
|
||||
in order to create the actual widget with provided functionality.
|
||||
During registration options can be set, e.g. the time span.
|
||||
|
||||
Registration is documented at :ref:`register-new-widget`,
|
||||
while implementation is documented at
|
||||
:ref:`implement-new-widget`.
|
||||
@@ -0,0 +1,11 @@
|
||||
:template: sitemap.html
|
||||
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _sitemap:
|
||||
|
||||
=======
|
||||
Sitemap
|
||||
=======
|
||||
|
||||
.. The sitemap.html template will insert here the page tree automatically.
|
||||
@@ -0,0 +1,73 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _bar-chart-widget:
|
||||
|
||||
================
|
||||
Bar Chart Widget
|
||||
================
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
|
||||
Widgets using this class will show a bar chart with the provided data.
|
||||
|
||||
This kind of widgets are useful if you want to show some statistics of for example
|
||||
historical data.
|
||||
|
||||
.. php:class:: TYPO3\CMS\Dashboard\Widgets\BarChartWidget
|
||||
|
||||
.. _bar-chart-widget-example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
|
||||
|
||||
services:
|
||||
dashboard.widget.sysLogErrors:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\BarChartWidget'
|
||||
arguments:
|
||||
$dataProvider: '@TYPO3\CMS\Dashboard\Widgets\Provider\SysLogErrorsDataProvider'
|
||||
$buttonProvider: '@TYPO3\CMS\Dashboard\Widgets\Provider\SysLogButtonProvider'
|
||||
$options:
|
||||
refreshAvailable: true
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
identifier: 'sysLogErrors'
|
||||
groupNames: 'systemInfo'
|
||||
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.sysLogErrors.title'
|
||||
description: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.sysLogErrors.description'
|
||||
iconIdentifier: 'content-widget-chart-bar'
|
||||
height: 'medium'
|
||||
width: 'medium'
|
||||
|
||||
.. _bar-chart-widget-options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. include:: Options/RefreshAvailable.rst.txt
|
||||
|
||||
.. _bar-chart-widget-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
.. confval:: $dataProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\ChartDataProviderInterface`
|
||||
:name: bar-chart-widget-dataProvider
|
||||
|
||||
To add data to a Bar Chart widget, you need to have a DataProvider that implements
|
||||
the interface :php-short:`\TYPO3\CMS\Dashboard\Widgets\ChartDataProviderInterface`.
|
||||
|
||||
See :ref:`graph-widget-implementation` for further information.
|
||||
|
||||
.. confval:: $buttonProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`
|
||||
:name: bar-chart-widget-buttonProvider
|
||||
|
||||
Optionally you can add a button with a link to some additional data.
|
||||
This button should be provided by a ButtonProvider that implements the interface
|
||||
:php-short:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`.
|
||||
|
||||
See :ref:`adding-buttons` for further info and configuration options.
|
||||
@@ -0,0 +1,72 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _cta-button-widget:
|
||||
|
||||
=================
|
||||
CTA Button Widget
|
||||
=================
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
.. php:class:: TYPO3\CMS\Dashboard\Widgets\CtaWidget
|
||||
|
||||
Widgets using this class will show a CTA (=Call to action) button to easily go to
|
||||
a specific page or do a specific action. You can add a button to the widget by
|
||||
defining a button provider.
|
||||
|
||||
You can use this kind of widget to link to for example a manual or to an important
|
||||
website that is used a lot by the users.
|
||||
|
||||
.. _cta-button-widget-example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
|
||||
|
||||
services:
|
||||
dashboard.widget.docGettingStarted:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\CtaWidget'
|
||||
arguments:
|
||||
$buttonProvider: '@dashboard.buttons.docGettingStarted'
|
||||
$options:
|
||||
text: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.documentation.gettingStarted.text'
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
identifier: 'docGettingStarted'
|
||||
groupNames: 'documentation'
|
||||
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.documentation.gettingStarted.title'
|
||||
description: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.documentation.gettingStarted.description'
|
||||
iconIdentifier: 'content-widget-text'
|
||||
height: 'small'
|
||||
|
||||
.. _cta-button-widget-options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. include:: Options/RefreshAvailable.rst.txt
|
||||
|
||||
.. confval:: text
|
||||
:name: cta-button-text
|
||||
:type: string
|
||||
:Example: `LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.documentation.gettingStarted.text`
|
||||
|
||||
Adds an optional text to the widget to give some more background information
|
||||
about what a user can expect when clicking the button.
|
||||
You can either enter a normal string or a translation string.
|
||||
|
||||
.. _cta-button-widget-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
.. confval:: $buttonProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`
|
||||
:name: cta-button-buttonProvider
|
||||
|
||||
Provides the actual button to show within the widget.
|
||||
This button should be provided by a ButtonProvider that implements the interface
|
||||
:php-short:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`.
|
||||
|
||||
See :ref:`adding-buttons` for further info and configuration options.
|
||||
@@ -0,0 +1,70 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _doughnut-chart-widget:
|
||||
|
||||
=====================
|
||||
Doughnut Chart Widget
|
||||
=====================
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
.. php:class:: TYPO3\CMS\Dashboard\Widgets\DoughnutChartWidget
|
||||
|
||||
Widgets using this class will show a doughnut chart with the provided data.
|
||||
|
||||
This kind of widgets are useful if you want to show the relational proportions
|
||||
between data.
|
||||
|
||||
.. _doughnut-chart-widget-example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
|
||||
|
||||
services:
|
||||
dashboard.widget.typeOfUsers:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\DoughnutChartWidget'
|
||||
arguments:
|
||||
$dataProvider: '@TYPO3\CMS\Dashboard\Widgets\Provider\TypeOfUsersChartDataProvider'
|
||||
$options:
|
||||
refreshAvailable: true
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
identifier: 'typeOfUsers'
|
||||
groupNames: 'systemInfo'
|
||||
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.typeOfUsers.title'
|
||||
description: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.typeOfUsers.description'
|
||||
iconIdentifier: 'content-widget-chart-pie'
|
||||
height: 'medium'
|
||||
|
||||
.. _doughnut-chart-widget-options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. include:: Options/RefreshAvailable.rst.txt
|
||||
|
||||
.. _doughnut-chart-widget-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
.. confval:: $dataProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\ChartDataProviderInterface`
|
||||
:name: doughnut-chart-widget-dataProvider
|
||||
|
||||
To add data to a Bar Chart widget, you need to have a DataProvider that implements
|
||||
the interface :php-short:`\TYPO3\CMS\Dashboard\Widgets\ChartDataProviderInterface`.
|
||||
|
||||
See :ref:`graph-widget-implementation` for further information.
|
||||
|
||||
.. confval:: $buttonProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`
|
||||
:name: doughnut-chart-widget-buttonProvider
|
||||
|
||||
Optionally you can add a button with a link to some additional data.
|
||||
This button should be provided by a ButtonProvider that implements the interface
|
||||
:php-short:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`.
|
||||
|
||||
See :ref:`adding-buttons` for further info and configuration options.
|
||||
@@ -0,0 +1,17 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _widgets:
|
||||
|
||||
=======
|
||||
Widgets
|
||||
=======
|
||||
|
||||
The following section will provide information for all provided widgets.
|
||||
For each widget an example registration will be provided,
|
||||
together with all configuration options.
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:titlesonly:
|
||||
|
||||
*Widget
|
||||
@@ -0,0 +1,58 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _list-widget:
|
||||
|
||||
===========
|
||||
List Widget
|
||||
===========
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
.. php:class:: TYPO3\CMS\Dashboard\Widgets\ListWidget
|
||||
|
||||
Widgets using this class will show a simple list of items provided by a data
|
||||
provider.
|
||||
|
||||
.. _list-widget-example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
|
||||
|
||||
services:
|
||||
dashboard.widget.testList:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\ListWidget'
|
||||
arguments:
|
||||
$dataProvider: '@Vendor\Ext\Widgets\Provider\TestListWidgetDataProvider'
|
||||
$options:
|
||||
refreshAvailable: true
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
identifier: 'testList'
|
||||
groupNames: 'general'
|
||||
title: 'List widget'
|
||||
description: 'Description of widget'
|
||||
iconIdentifier: 'content-widget-list'
|
||||
height: 'large'
|
||||
width: 'large'
|
||||
|
||||
.. _list-widget-options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. include:: Options/RefreshAvailable.rst.txt
|
||||
|
||||
.. _list-widget-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
.. confval:: $dataProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\NumberWithIconDataProviderInterface`
|
||||
:name: list-widget-dataProvider
|
||||
|
||||
This class should provide the items to show.
|
||||
This data provider needs to implement the
|
||||
:php-short:`\TYPO3\CMS\Dashboard\Widgets\NumberWithIconDataProviderInterface`.
|
||||
@@ -0,0 +1,84 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _number-widget:
|
||||
|
||||
=======================
|
||||
Number With Icon Widget
|
||||
=======================
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
.. php:class:: TYPO3\CMS\Dashboard\Widgets\NumberWithIconWidget
|
||||
|
||||
Widgets using this class will show a widget with a number, some additional
|
||||
text and an icon.
|
||||
|
||||
This kind of widgets are useful if you want to show some simple stats.
|
||||
|
||||
.. _number-widget-example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: Excerpt from EXT:dashboard/Configuration/Services.yaml
|
||||
|
||||
services:
|
||||
dashboard.widget.failedLogins:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\NumberWithIconWidget'
|
||||
arguments:
|
||||
$dataProvider: '@TYPO3\CMS\Dashboard\Widgets\Provider\NumberOfFailedLoginsDataProvider'
|
||||
$options:
|
||||
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.title'
|
||||
subtitle: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.subtitle'
|
||||
icon: 'content-elements-login'
|
||||
refreshAvailable: true
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
identifier: 'failedLogins'
|
||||
groupNames: 'systemInfo'
|
||||
title: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.title'
|
||||
description: 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.description'
|
||||
iconIdentifier: 'content-widget-number'
|
||||
|
||||
.. _number-widget-options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. include:: Options/RefreshAvailable.rst.txt
|
||||
|
||||
.. confval:: title
|
||||
:type: string
|
||||
:name: number-widget-title
|
||||
:Example: `LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.title`
|
||||
|
||||
The main title that will be shown in the widget as an explanation of the shown number.
|
||||
You can either enter a normal string or a translation string.
|
||||
|
||||
.. confval:: subtitle
|
||||
:type: string
|
||||
:name: number-widget-subtitle
|
||||
:Example: `LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.subtitle`
|
||||
|
||||
The optional subtitle that will give some additional information about the number and title.
|
||||
You can either enter a normal string or a translation string.
|
||||
|
||||
.. confval:: icon
|
||||
:type: string
|
||||
:name: number-widget-icon
|
||||
|
||||
The icon-identifier of the icon that should be shown in the widget.
|
||||
You should register your icon with the :ref:`t3coreapi:icon`.
|
||||
|
||||
.. _number-widget-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
.. confval:: $dataProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\NumberWithIconDataProviderInterface`
|
||||
:name: number-widget-dataProvider
|
||||
|
||||
This class should provide the number to show.
|
||||
This data provider needs to implement the
|
||||
:php-short:`\TYPO3\CMS\Dashboard\Widgets\NumberWithIconDataProviderInterface`.
|
||||
@@ -0,0 +1,9 @@
|
||||
.. confval:: refreshAvailable
|
||||
:type: boolean
|
||||
:default: :yaml:`false`
|
||||
:noindex:
|
||||
|
||||
Boolean value, either :yaml:`false` or :yaml:`true`.
|
||||
|
||||
Provides a refresh button to backend users to refresh the widget.
|
||||
If the option is omitted :yaml:`false` is assumed.
|
||||
@@ -0,0 +1,128 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _rss-widget:
|
||||
|
||||
==========
|
||||
RSS Widget
|
||||
==========
|
||||
|
||||
.. versionchanged:: 14.0
|
||||
The RSS widget was extended to support Atom feeds (commonly used by GitHub,
|
||||
GitLab, and other platforms)
|
||||
|
||||
.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
|
||||
.. php:class:: TYPO3\CMS\Dashboard\Widgets\RssWidget
|
||||
|
||||
Widgets using this class will show a list of items of the configured RSS feed
|
||||
or Atom feed.
|
||||
|
||||
The "RSS Widget" supports both RSS and Atom feeds via automatic detection.
|
||||
|
||||
Widget instances are fully configurable with custom labels, feed URLs, and
|
||||
display limits. Each widget can be configured independently, allowing multiple
|
||||
feeds of different formats on the same dashboard
|
||||
|
||||
Automatic caching ensures optimal performance with configurable cache lifetimes.
|
||||
|
||||
.. contents::
|
||||
|
||||
.. _rss-widget-usage:
|
||||
|
||||
Usage of the RSS Widget in the dashboard
|
||||
----------------------------------------
|
||||
|
||||
You can use this kind of widget to show your own RSS feed
|
||||
or Atom feed.
|
||||
|
||||
#. Navigate to the dashboard where you want to add the widget
|
||||
#. Click "Add widget" and select the RSS widget
|
||||
#. Click the settings (cog) icon to customize the widget
|
||||
#. Configure the feed URL (RSS or Atom), limit, and label as needed
|
||||
#. Save the configuration to apply changes
|
||||
|
||||
.. _rss-widget-format:
|
||||
|
||||
Feed format support
|
||||
-------------------
|
||||
|
||||
The RSS widget now supports both feed formats:
|
||||
|
||||
**RSS Feeds:**
|
||||
|
||||
Item titles
|
||||
Displayed as clickable links
|
||||
Publication dates
|
||||
Used for sorting entries (newest first)
|
||||
Descriptions
|
||||
Displayed as entry content (HTML tags stripped)
|
||||
|
||||
**Atom Feeds:**
|
||||
|
||||
Entry titles
|
||||
Displayed as clickable links
|
||||
Publication dates
|
||||
Used for sorting entries (newest first)
|
||||
Content/Summary
|
||||
Displayed as entry description (HTML tags stripped)
|
||||
Author information
|
||||
Name, email, and URL when provided in the feed
|
||||
|
||||
.. _rss-widget-example:
|
||||
|
||||
Example for RSS widget with Atom feed
|
||||
-------------------------------------
|
||||
|
||||
.. literalinclude:: _codesnippets/_rsswidget-services.yaml
|
||||
:caption: EXT:my_extension/Configuration/Services.yaml
|
||||
|
||||
.. _rss-widget-options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. include:: Options/RefreshAvailable.rst.txt
|
||||
|
||||
The following options are available via :yaml:`services.dashboard.widget.t3news.arguments.$options`:
|
||||
|
||||
.. confval:: label
|
||||
:type: string
|
||||
:name: rss-widget-label
|
||||
|
||||
* Custom title for the widget instance
|
||||
* Optional field that defaults to the widget's default title
|
||||
|
||||
.. confval:: feedUrl
|
||||
:type: string
|
||||
:name: rss-widget-feedUrl
|
||||
|
||||
Defines the URL or file providing the RSS Feed.
|
||||
This is read by the widget in order to fetch entries to show.
|
||||
|
||||
.. confval:: lifeTime
|
||||
:type: int
|
||||
:name: rss-widget-lifeTime
|
||||
:Default: `43200`
|
||||
|
||||
Defines how long to wait, in seconds, until fetching RSS Feed again.
|
||||
|
||||
.. confval:: limit
|
||||
:type: int
|
||||
:name: rss-widget-limit
|
||||
:Default: `5`
|
||||
|
||||
Defines how many RSS items should be shown.
|
||||
|
||||
.. _rss-widget-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
.. confval:: $buttonProvider
|
||||
:type: :php:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`
|
||||
:name: rss-widget-buttonProvider
|
||||
|
||||
Provides an optional button to show which is used to open the source of RSS data.
|
||||
This button should be provided by a ButtonProvider that implements the interface
|
||||
:php-short:`\TYPO3\CMS\Dashboard\Widgets\ButtonProviderInterface`.
|
||||
|
||||
See :ref:`adding-buttons` for further info and configuration options.
|
||||
@@ -0,0 +1,28 @@
|
||||
services:
|
||||
|
||||
# Button provider for external link
|
||||
dashboard.buttons.github_releases:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\Provider\ButtonProvider'
|
||||
arguments:
|
||||
$title: 'View all releases'
|
||||
$link: 'https://github.com/TYPO3/typo3/releases'
|
||||
$target: '_blank'
|
||||
|
||||
# RSS widget with Atom feed URL
|
||||
dashboard.widget.github_releases:
|
||||
class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
|
||||
arguments:
|
||||
$buttonProvider: '@dashboard.buttons.github_releases'
|
||||
$options:
|
||||
feedUrl: 'https://github.com/TYPO3/typo3/releases.atom'
|
||||
lifeTime: 43200
|
||||
limit: 10
|
||||
tags:
|
||||
- name: dashboard.widget
|
||||
identifier: 'github_releases'
|
||||
groupNames: 'general'
|
||||
title: 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:widgets.github_releases.title'
|
||||
description: 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:widgets.github_releases.description'
|
||||
iconIdentifier: 'content-widget-rss'
|
||||
height: 'large'
|
||||
width: 'medium'
|
||||
@@ -0,0 +1,21 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
|
||||
links-are-relative="true">
|
||||
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
|
||||
project-home="https://extensions.typo3.org/extension/dashboard/"
|
||||
project-contact="https://typo3.slack.com/archives/C025BQLFA"
|
||||
project-repository="https://github.com/typo3/typo3"
|
||||
project-issues="https://forge.typo3.org/projects/typo3cms-core/issues"
|
||||
edit-on-github-branch="main"
|
||||
edit-on-github="typo3/typo3"
|
||||
edit-on-github-directory="typo3/sysext/dashboard/Documentation/"
|
||||
typo3-core-preferred="main"
|
||||
interlink-shortcode="typo3/cms-dashboard"
|
||||
/>
|
||||
<project title="Dashboard"
|
||||
release="main (development)"
|
||||
version="main (development)"
|
||||
copyright="since 2020 by the TYPO3 contributors"
|
||||
/>
|
||||
</guides>
|
||||
Reference in New Issue
Block a user