188 lines
8.2 KiB
ReStructuredText
188 lines
8.2 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _feature-90333:
|
|
|
|
===========================
|
|
Feature: #90333 - Dashboard
|
|
===========================
|
|
|
|
See :issue:`90333`
|
|
|
|
Description
|
|
===========
|
|
|
|
A dashboard is introduced into TYPO3 to show relevant information to
|
|
the current logged in user.
|
|
|
|
Every user with access to this backend module can now have one or more personal
|
|
dashboards. Each dashboard can contain several widgets. Which widgets and in which
|
|
order the widgets are shown is up to the users themselves.
|
|
|
|
As an integrator, you have the possibility to create dashboard templates. You can
|
|
mark the template as a default template so it will be created by default for every
|
|
new user.
|
|
|
|
As a developer, you can create your own widgets. Just use one of the available
|
|
abstracts, which will be extended in the future, and extend it with your own
|
|
information.
|
|
|
|
You can find the new dashboard in the toolbar in the top of your window.
|
|
|
|
|
|
Available widgets
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
The following widgets are shipped by core extensions now:
|
|
|
|
* TYPO3 news: A widget showing the latest 5 news items from typo3.org (EXT:dashboard)
|
|
* TYPO3 security advisories: A widget showing the latest 5 security advisories from typo3.org (EXT:dashboard)
|
|
* TYPO3: This widget will show you some background information about TYPO3 and shows the current version of TYPO3 installed (EXT:dashboard)
|
|
* Getting started with TYPO3: This widget will provide a link to the Getting Started Tutorial (EXT:dashboard)
|
|
* TypoScript Template Reference: This widget will provide a link to the TypoScript Template Reference (EXT:dashboard)
|
|
* TSconfig Reference: This widget will provide a link to the TSconfig Reference (EXT:dashboard)
|
|
* Number of errors in system log: Shows the number of errors in the sys_log grouped by day for the last month (EXT:dashboard)
|
|
* Type of backend users: A widget to show the different types of backend users (EXT:dashboard)
|
|
* Failed Logins: This widget will show you the number of failed logins during the last 24 hours (EXT:dashboard)
|
|
|
|
|
|
Creating your own widget
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Besides the widgets shipped with TYPO3 core, you can also write your own widget. To
|
|
do so, you can extend one of the WidgetAbstracts available in EXT:dashboard.
|
|
|
|
* :php:`AbstractWidget`: a basic abstract that can be used as the start of simple widgets
|
|
* :php:`AbstractRssWidget`: with this abstract it is easy to create a widget showing a RSS feed
|
|
* :php:`AbstractListWidget`: this abstract will give you an easy start to show a list of items
|
|
* :php:`AbstractCtaButtonWidget`: when you want to show a Call-To-Action button, this is the right abstract
|
|
* :php:`AbstractChartWidget`: the base of all chart widgets
|
|
* :php:`AbstractBarChartWidget`: when you want to show a widget with a bar-chart you can extend this class
|
|
* :php:`AbstractDoughnutChartWidget`: this abstract gives you the possibility to create a doughnut-chart widget
|
|
* :php:`AbstractNumberWithIconWidget`: this abstract will give you the possibility to show a title, number and an icon
|
|
|
|
|
|
By extending one of those abstracts, and providing it with the needed data, you are able to
|
|
have a new widget quite fast. The only thing that is left is to register the widget.
|
|
|
|
Tag your widget in :file:`EXT:your_extension/Configuration/Services.yaml`:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Variant 1, widget identifier as attribute
|
|
Vendor\Extension\Widgets\MyFirstWidget:
|
|
arguments: ['widget-identifier-1']
|
|
tags:
|
|
- name: dashboard.widget
|
|
identifier: widget-identifier-1
|
|
widgetGroups: 'general'
|
|
|
|
# Variant 2, custom service name, allows multiple widget identifiers
|
|
# to share the same class
|
|
widget.identifier:
|
|
class: Vendor\Extension\Widgets\MySecondWidget
|
|
arguments: ['widget-identifier-1']
|
|
tags:
|
|
- name: dashboard.widget
|
|
# If omitted, the identifier would be the service name, thus 'widget.identifier'
|
|
identifier: widget-identifier-2
|
|
widgetGroups: 'general, typo3'
|
|
|
|
|
|
Every widget needs a unique identifier, the implementing class and at least one
|
|
associated widget group. Multiple widget groups are separated by comma.
|
|
|
|
|
|
Configuring Widget Groups
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Every widget is attached to one or more widget groups. Those groups are shown in the
|
|
modal when adding a new widget to your dashboard. In this way you can group the available
|
|
widgets to get a clear overview for your users. By default the following widget groups are
|
|
available:
|
|
|
|
* `widgetGroup-general`: Widgets with a more generic purpose
|
|
* `widgetGroup-systemInfo`: Widgets which provide system related information
|
|
* `widgetGroup-typo3`: Widgets with information regarding the TYPO3 product or community
|
|
* `widgetGroup-documentation`: Widgets with links to TYPO3 documentation
|
|
|
|
You can also configure your own widget groups. To do so, you create a file :file:`EXT:your_extension/Configuration/Backend/DashboardWidgetGroups.php`.
|
|
In that file you specify the information of the groups.
|
|
|
|
.. code-block:: php
|
|
|
|
return [
|
|
'widgetGroup-myOwnGroup' => [
|
|
'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:widget_group.myOwnGroup',
|
|
],
|
|
];
|
|
|
|
First you have the identifier as the key. This identifier is used to map widgets to this
|
|
group. You only have one property and that is the title. You can add a simple text, or a
|
|
translation string like in the example above.
|
|
|
|
|
|
Defining Dashboard Presets
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
You have the possibility to create dashboard presets. Those
|
|
presets are used when a user is creating a new dashboard. He can choose one of the available presets.
|
|
In a preset you can define which widgets and in which order those widgets will be added to the dashboard when created.
|
|
|
|
So for example, if you want to give editors the possibility to add a dashboard with several
|
|
SEO related widgets, you can create a dashboard preset and add all the useful widgets on that.
|
|
When a user creates a dashboard based on that preset, all those widgets will be initially added to
|
|
that dashboard.
|
|
|
|
To define those dashboard presets, you can create a file :file:`EXT:your_extension/Configuration/Backend/DashboardPresets.php`.
|
|
In that file you specify the information of the presets.
|
|
|
|
.. code-block:: php
|
|
|
|
return [
|
|
'dashboardPreset-myOwnPreset' => [
|
|
'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:dashboard.myOwnPreset',
|
|
'description' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:dashboard.myOwnPreset.description',
|
|
'iconIdentifier' => 'content-dashboard',
|
|
'defaultWidgets' => ['widget-identifier-1', 'widget-identifier-2'],
|
|
'showInWizard' => true
|
|
],
|
|
];
|
|
|
|
You start again with the dashboard preset identifier which should be unique. Every preset needs a title, description, iconIdentifier, some widgets and a flag if the
|
|
preset should be shown in the wizard to create a new dashboard. This last setting is to make it possible to not show it as a preset, but it can be used to
|
|
create this dashboard preset by default for new users.
|
|
|
|
|
|
Automatically create a dashboard for new users
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If you have a new user in your backend, you might want to kickstart that user and provide a
|
|
basic dashboard. You can do this by defining which dashboard presets should be created by default
|
|
when a user gets created or when a user deletes all his dashboards.
|
|
|
|
You can define which dashboards will be created automatically by using the following TSconfig setting:
|
|
|
|
.. code-block:: typoscript
|
|
|
|
options.dashboard.dashboardPresetsForNewUsers = default, dashboardPreset-myOwnPreset
|
|
|
|
You can add the identifiers of multiple presets in a comma separated list.
|
|
|
|
|
|
Permissions
|
|
^^^^^^^^^^^
|
|
|
|
As widgets might contain sensitive information, it is also possible to define the permissions
|
|
of the widgets on a group base. In the backend group settings you have the possibility to allow
|
|
specific widgets. Only those widgets will be available for users in that group. Admin users
|
|
have access to all widgets by default.
|
|
|
|
|
|
Impact
|
|
======
|
|
|
|
This is a new backend module and will not replace any old features. If the dashboard
|
|
extension is installed, it will be the default startup page in TYPO3 Backend.
|
|
|
|
.. index:: Backend, ext:dashboard
|