From 624b10bf3cac8db2b343a17d29151bcf38da4ca5 Mon Sep 17 00:00:00 2001
From: Lina Wolf <112@linawolf.de>
Date: Fri, 6 Sep 2024 17:12:22 +0200
Subject: [PATCH] [DOCS] Remove all highlight directives from dashboard docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
These directives are currently causing errors in opening rst
files in PHP storm.
Also it is best practice to only use explicit code blocks or
literalincludes.
Resolves: #104848
Releases: main, 12.4
Change-Id: I1271b6e4f5e032a1f0d5835e141334e263b30169
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/85916
Reviewed-by: Stefan Bürk <stefan@buerk.tech>
Reviewed-by: Garvin Hicking <gh@faktor-e.de>
Tested-by: core-ci <typo3@b13.com>
Tested-by: Garvin Hicking <gh@faktor-e.de>
Tested-by: Stefan Bürk <stefan@buerk.tech>
---
.../Configuration/WidgetPresets.rst | 19 +-
.../Documentation/Developer/AddingButtons.rst | 56 ++--
.../Developer/GraphWidgetImplementation.rst | 265 +++++++++---------
.../Documentation/Developer/Interfaces.rst | 25 +-
.../Developer/MakeRefreshable.rst | 1 -
.../Developer/WidgetImplementation.rst | 34 ++-
.../Documentation/Installation/Index.rst | 1 -
7 files changed, 207 insertions(+), 194 deletions(-)
diff --git a/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst b/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst
index e84af6820f92..437c2e386f80 100644
--- a/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst
+++ b/typo3/sysext/dashboard/Documentation/Configuration/WidgetPresets.rst
@@ -77,24 +77,29 @@ Each preset consists of the following options:
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::
+To define the default preset for a backend user, the following User TSconfig can be added:
- options.dashboard.dashboardPresetsForNewUsers = default
+.. code-block:: typoscript
+
+ options.dashboard.dashboardPresetsForNewUsers = default
Where ``default`` is the identifier of the preset.
-Even a comma separated list of identifiers is possible::
+Even a comma separated list of identifiers is possible:
+
+.. code-block:: typoscript
+
+ options.dashboard.dashboardPresetsForNewUsers = default, companyDefault
- options.dashboard.dashboardPresetsForNewUsers = default, companyDefault
+It is also possible to add another dashboard to the set of dashboards:
-It is also possible to add another dashboard to the set of dashboards::
+.. code-block:: typoscript
- options.dashboard.dashboardPresetsForNewUsers := addToList(anotherOne)
+ options.dashboard.dashboardPresetsForNewUsers := addToList(anotherOne)
If nothing is configured, ``default`` will be used as identifier.
diff --git a/typo3/sysext/dashboard/Documentation/Developer/AddingButtons.rst b/typo3/sysext/dashboard/Documentation/Developer/AddingButtons.rst
index 8e22cf331c8b..1b15bd6dd64a 100644
--- a/typo3/sysext/dashboard/Documentation/Developer/AddingButtons.rst
+++ b/typo3/sysext/dashboard/Documentation/Developer/AddingButtons.rst
@@ -1,6 +1,5 @@
.. include:: /Includes.rst.txt
-.. highlight:: php
.. _adding-buttons:
@@ -76,30 +75,31 @@ Implementation
An example implementation could look like this:
-:file:`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;
- }
- }
+.. 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;
+ }
+ }
diff --git a/typo3/sysext/dashboard/Documentation/Developer/GraphWidgetImplementation.rst b/typo3/sysext/dashboard/Documentation/Developer/GraphWidgetImplementation.rst
index d2b99a1f337b..5b38fd6c5695 100644
--- a/typo3/sysext/dashboard/Documentation/Developer/GraphWidgetImplementation.rst
+++ b/typo3/sysext/dashboard/Documentation/Developer/GraphWidgetImplementation.rst
@@ -1,6 +1,5 @@
.. include:: /Includes.rst.txt
-.. highlight:: php
.. _graph-widget-implementation:
@@ -22,54 +21,57 @@ To make the dashboard aware of this workflow, some interfaces come together:
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`::
-
- 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;
- }
- }
+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`:
@@ -88,85 +90,86 @@ Together with :file:`Services.yaml`:
The configuration adds necessary CSS classes, as well as the ``dataProvider`` to use.
The provider implements :php:`ChartDataProviderInterface` and could look like the following.
-:file:`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'];
- }
- }
+.. 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'];
+ }
+ }
diff --git a/typo3/sysext/dashboard/Documentation/Developer/Interfaces.rst b/typo3/sysext/dashboard/Documentation/Developer/Interfaces.rst
index 51a7d79ea647..1129501f7997 100644
--- a/typo3/sysext/dashboard/Documentation/Developer/Interfaces.rst
+++ b/typo3/sysext/dashboard/Documentation/Developer/Interfaces.rst
@@ -1,6 +1,5 @@
.. include:: /Includes.rst.txt
-.. highlight:: php
.. _interfaces:
@@ -97,12 +96,14 @@ For up to date information, please check the source code.
.. php:method:: getJsFiles()
- Returns a list of JavaScript file names that should be included, e.g.::
+ Returns a list of JavaScript file names that should be included, e.g.:
- return [
- 'EXT:my_extension/Resources/Public/JavaScript/file.js',
- 'EXT:my_extension/Resources/Public/JavaScript/file2.js',
- ];
+ .. 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.
@@ -114,12 +115,14 @@ For up to date information, please check the source code.
.. php:method:: getCssFiles()
- Returns a list of Css file names that should be included, e.g.::
+ 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',
- ];
+ 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.
diff --git a/typo3/sysext/dashboard/Documentation/Developer/MakeRefreshable.rst b/typo3/sysext/dashboard/Documentation/Developer/MakeRefreshable.rst
index 6c3c64365241..821f92509646 100644
--- a/typo3/sysext/dashboard/Documentation/Developer/MakeRefreshable.rst
+++ b/typo3/sysext/dashboard/Documentation/Developer/MakeRefreshable.rst
@@ -1,6 +1,5 @@
.. include:: /Includes.rst.txt
-.. highlight:: php
.. _make-refreshable:
diff --git a/typo3/sysext/dashboard/Documentation/Developer/WidgetImplementation.rst b/typo3/sysext/dashboard/Documentation/Developer/WidgetImplementation.rst
index 0916cf17d58c..aea3fa40e297 100644
--- a/typo3/sysext/dashboard/Documentation/Developer/WidgetImplementation.rst
+++ b/typo3/sysext/dashboard/Documentation/Developer/WidgetImplementation.rst
@@ -1,6 +1,5 @@
.. include:: /Includes.rst.txt
-.. highlight:: php
.. _implement-new-widget:
@@ -30,7 +29,9 @@ PHP class
---------
Each Widget has to be a PHP class.
-This class has to implement the :php:`WidgetInterface` and could look like this::
+This class has to implement the :php:`WidgetInterface` and could look like this:
+
+.. code-block:: php
class RssWidget implements WidgetInterface, RequestAwareWidgetInterface
{
@@ -73,7 +74,7 @@ This class has to implement the :php:`WidgetInterface` and could look like this:
{
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`.
@@ -107,6 +108,7 @@ JavaScript module
.. code-block:: php
+
class ExampleChartWidget implements JavaScriptInterface
{
// ...
@@ -169,15 +171,17 @@ Providing custom CSS
It is possible to add custom Css to style widgets.
-Implement :php:`AdditionalCssInterface`::
-
- 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',
- ];
- }
- }
+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',
+ ];
+ }
+ }
diff --git a/typo3/sysext/dashboard/Documentation/Installation/Index.rst b/typo3/sysext/dashboard/Documentation/Installation/Index.rst
index 8d81eadd68a1..02e766b707a3 100644
--- a/typo3/sysext/dashboard/Documentation/Installation/Index.rst
+++ b/typo3/sysext/dashboard/Documentation/Installation/Index.rst
@@ -1,5 +1,4 @@
.. include:: /Includes.rst.txt
-.. highlight:: bash
.. _installation:
--
GitLab