From 379288fbdf0e53fc605ae6c70feae170f2ec08a4 Mon Sep 17 00:00:00 2001
From: Daniel Siepmann <daniel.siepmann@typo3.org>
Date: Thu, 7 May 2020 18:03:08 +0200
Subject: [PATCH] [DOCS] ext:dashboard presets feature
The system extension ext:dashboard provides a way to register presets of
dashboards.
These presets can be configured via User TSconfig, if the user doesn't
have a dashboard yet.
Resolves: #91341
Releases: master
Change-Id: I174d6ee4a931bbe32f0cbed87db1545ee2785946
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/64435
Tested-by: Richard Haeser <richard@maxserv.com>
Tested-by: Koen Wouters <koen.wouters@maxserv.com>
Tested-by: Daniel Siepmann <coding@daniel-siepmann.de>
Reviewed-by: Richard Haeser <richard@maxserv.com>
Reviewed-by: Koen Wouters <koen.wouters@maxserv.com>
Reviewed-by: Daniel Siepmann <coding@daniel-siepmann.de>
---
.../Documentation/Configuration/Index.rst | 1 +
.../Configuration/WidgetPresets.rst | 96 +++++++++++++++++++
.../dashboard/Documentation/Settings.cfg | 2 +-
3 files changed, 98 insertions(+), 1 deletion(-)
create mode 100644 typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst
diff --git a/typo3/sysext/dashboard/Documentation/Configuration/Index.rst b/typo3/sysext/dashboard/Documentation/Configuration/Index.rst
index c4576196329f..dd225c884af3 100644
--- a/typo3/sysext/dashboard/Documentation/Configuration/Index.rst
+++ b/typo3/sysext/dashboard/Documentation/Configuration/Index.rst
@@ -14,6 +14,7 @@ Target group: **Developers** and **Integrators**
WidgetRegistration
WidgetGroupCreation
+ WidgetPresets
WidgetSettings
WidgetTemplate
PermissionHandlingOfWidgets
diff --git a/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst b/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst
new file mode 100644
index 000000000000..5c383c089804
--- /dev/null
+++ b/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst
@@ -0,0 +1,96 @@
+.. include:: ../Includes.txt
+
+.. highlight:: php
+
+.. _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 via :file:`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'],
+ '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:
+
+.. program:: TYPO3\CMS\Dashboard\DashboardPreset
+
+.. option:: title
+
+ The title used for the preset. E.g. a ``LLL:EXT:`` reference..
+
+.. option:: description
+
+ The description used for the preset. E.g. a ``LLL:EXT:`` reference..
+
+.. option:: iconIdentifier
+
+ The identifier of the icon to use.
+
+.. option:: defaultWidgets
+
+ An array of widget identifiers, 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.
+
+.. option:: 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.
+
+.. highlight:: typoscript
+.. _configure-preset-for-user:
+
+Configure preset for user
+-------------------------
+
+To define the default preset for a backend user, the following User TSconfig can be added::
+
+ options.dashboard.dashboardPresetsForNewUsers = default
+
+Where ``default`` is the identifier of the preset.
+Even a comma separated list of identifiers is possible::
+
+ options.dashboard.dashboardPresetsForNewUsers = default, companyDefault
+
+It is also possible to add another dashboard to the set of dashboards::
+
+ options.dashboard.dashboardPresetsForNewUsers := addToList(anotherOne)
+
+If nothing is configured, ``default`` will be used as identifier.
+
+.. seealso::
+
+ :ref:`t3tsconfig:userthetsconfigfield` section of TSconfig manual
+ explains how to set or register TSconfig for user.
+
+ :ref:`t3coreapi:typoscript-syntax-syntax-value-modification` explains the usage of
+ :ts:`:=` TypoScript operator.
diff --git a/typo3/sysext/dashboard/Documentation/Settings.cfg b/typo3/sysext/dashboard/Documentation/Settings.cfg
index 4bcea8006658..39a72aa88c9c 100644
--- a/typo3/sysext/dashboard/Documentation/Settings.cfg
+++ b/typo3/sysext/dashboard/Documentation/Settings.cfg
@@ -43,6 +43,6 @@ t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us
# t3tca = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
# t3templating = https://docs.typo3.org/m/typo3/tutorial-templating/master/en-us/
# t3ts45 = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/master/en-us/
-# t3tsconfig = https://docs.typo3.org/m/typo3/reference-tsconfig/master/en-us/
+t3tsconfig = https://docs.typo3.org/m/typo3/reference-tsconfig/master/en-us/
# t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
# linkvalidator = https://docs.typo3.org/c/typo3/cms-linkvalidator/master/en-us/
--
GitLab