Commit ddb362f8 authored by Oliver Bartsch's avatar Oliver Bartsch Committed by Georg Ringer
Browse files

[TASK] Clean up of ext:dashboard

Before the final release of the dashboard some clean up is done.
Among others following tasks are performed:

* Add missing PHPDocs
* Remove unused methods
* Remove superfluous properties
* Unify namespace format
* Fix some typos
* Fix some formatting
* Make closures static
* NoDashboardAvailableException is removed as it is never be thrown
* Extend documentation for missing widget groups

Resolves: #90524
Releases: master
Change-Id: Ia0f7d71def358bf0ee8ab42d97f012c14cdede1c
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/63407


Tested-by: default avatarTYPO3com <noreply@typo3.com>
Tested-by: Susanne Moog's avatarSusanne Moog <look@susi.dev>
Tested-by: Georg Ringer's avatarGeorg Ringer <georg.ringer@gmail.com>
Reviewed-by: Susanne Moog's avatarSusanne Moog <look@susi.dev>
Reviewed-by: Georg Ringer's avatarGeorg Ringer <georg.ringer@gmail.com>
parent 13c67c45
......@@ -45,14 +45,14 @@ 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.
* AbstractWidget: a basic abstract that can be used as the start of simple widgets
* AbstractRssWidget: with this abstract it is easy to create a widget showing a RSS feed
* AbstractListWidget: this abstract will give you an easy start to show a list of items
* AbstractCtaButtonWidget: when you want to show a Call-To-Action button, this is the right abstract
* AbstractChartWidget: the base of all chart widgets
* AbstractBarChartWidget: when you want to show a widget with a bar-chart you can extend this class
* AbstractDoughnutChartWidget: this abstract gives you the possibility to create a doughnut-chart widget
* AbstractNumberWithIconWidget: this abstract will give you the possibility to show a title, number and an icon
* `AbstractWidget`: a basic abstract that can be used as the start of simple widgets
* `AbstractRssWidget`: with this abstract it is easy to create a widget showing a RSS feed
* `AbstractListWidget`: this abstract will give you an easy start to show a list of items
* `AbstractCtaButtonWidget`: when you want to show a Call-To-Action button, this is the right abstract
* `AbstractChartWidget`: the base of all chart widgets
* `AbstractBarChartWidget`: when you want to show a widget with a bar-chart you can extend this class
* `AbstractDoughnutChartWidget`: this abstract gives you the possibility to create a doughnut-chart widget
* `AbstractNumberWithIconWidget`: this abstract will give you the possibility to show a title, number and an icon
By extending one of those abstracts, and provide it with the right data, you are able to
have a new widget quite fast. The only thing that is left is to register the widget.
......@@ -91,8 +91,10 @@ modal when adding a new widget to your dashboard. In this way you can group the
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-typo3: Widgets with information regarding the TYPO3 product or community
* `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.
......
......@@ -30,7 +30,6 @@ use TYPO3\CMS\Dashboard\Dashboard;
use TYPO3\CMS\Dashboard\DashboardPreset;
use TYPO3\CMS\Dashboard\DashboardPresetRegistry;
use TYPO3\CMS\Dashboard\DashboardRepository;
use TYPO3\CMS\Dashboard\Exception\NoDashboardAvailableException;
use TYPO3\CMS\Dashboard\WidgetGroupRegistry;
use TYPO3\CMS\Dashboard\WidgetRegistry;
use TYPO3\CMS\Dashboard\Widgets\Interfaces\AdditionalCssInterface;
......@@ -69,13 +68,19 @@ class DashboardController extends AbstractController
protected $requireJsModules = [];
/** @var Dashboard */
/**
* @var Dashboard
*/
protected $currentDashboard;
/** @var Dashboard[] */
/**
* @var Dashboard[]
*/
protected $dashboardsForCurrentUser;
/** @var DashboardPreset[] */
/**
* @var DashboardPreset[]
*/
protected $availableDashboardPresets;
/**
......@@ -121,9 +126,6 @@ class DashboardController extends AbstractController
$this->initializeDashboardsForCurrentUser();
}
/**
* @throws NoDashboardAvailableException
*/
protected function initializeDashboardsForCurrentUser(): void
{
$this->dashboardsForCurrentUser = $this->getDashboardsForCurrentUser();
......
......@@ -27,7 +27,7 @@ class DashboardRepository
private const TABLE = 'be_dashboards';
/**
* @var array
* @var string[]
*/
protected $allowedFields = ['title'];
......
<?php
declare(strict_types = 1);
namespace TYPO3\CMS\Dashboard\Exception;
/*
* This file is part of the TYPO3 CMS project.
*
* It is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License, either version 2
* of the License, or any later version.
*
* For the full copyright and license information, please read the
* LICENSE.txt file that was distributed with this source code.
*
* The TYPO3 project - inspiring people to share!
*/
use TYPO3\CMS\Core\Exception;
/**
* Exception is thrown if no dashboard is available for the current user
*/
class NoDashboardAvailableException extends Exception
{
}
......@@ -18,15 +18,24 @@ namespace TYPO3\CMS\Dashboard\Widgets;
/**
* The AbstractBarChartWidget class is the basic widget class for bar charts.
* It is possible to extend this class for custom widgets.
* In your class you have to store the data to display in $this->chartData
* In your class you have to store the data to display in $this->chartData.
* More information can be found in the documentation.
*/
abstract class AbstractBarChartWidget extends AbstractChartWidget
{
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-chart-bar';
/**
* @inheritDoc
*/
protected $chartType = 'bar';
/**
* @inheritDoc
*/
protected $chartOptions = [
'maintainAspectRatio' => false,
'legend' => [
......
......@@ -20,7 +20,7 @@ use TYPO3\CMS\Dashboard\Widgets\Interfaces\EventDataInterface;
use TYPO3\CMS\Dashboard\Widgets\Interfaces\RequireJsModuleInterface;
/**
* The AbstractChartWidget class is the basic widget class for all chart widgets
* The AbstractChartWidget class is the basic widget class for all chart widgets.
* It is possible to extend this class for custom widgets. EXT:dashboard also provides
* more special chart types for widgets (bar chart and doughnut chart).
*/
......@@ -41,7 +41,7 @@ abstract class AbstractChartWidget extends AbstractWidget implements AdditionalC
protected $chartType = '';
/**
* This array should contain the data for the graph. The data and options you have depend on the type
* This property should contain the data for the 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.
*
* @link https://www.chartjs.org/docs/latest/charts/bar.html#data-structure
......@@ -65,7 +65,7 @@ abstract class AbstractChartWidget extends AbstractWidget implements AdditionalC
/**
* This property can be used to pass data to the JavaScript that will handle the content rendering. For
* charts, the only property necessary for charts is the graphConfig element. This will be set in the
* getEventData method of this class. Setting this property manual is therefore not needed.
* getEventData method of this class. Setting this property manually is therefore not needed.
*
* @see getEventData
*
......@@ -76,13 +76,13 @@ abstract class AbstractChartWidget extends AbstractWidget implements AdditionalC
/**
* The default colors that will be used for the graphs.
*
* @var array
* @var string[]
*/
protected $chartColors = ['#ff8700', '#a4276a', '#1a568f', '#4c7e3a', '#69bbb5'];
/**
* If you want to show a button below the graph, you need to set the title and the link to the button. This text
* can be a fixed string or can contain a translatable string.
* If you want to show a button below the graph, you need to set the title and the link to the button.
* This text can be a fixed string or can contain a translatable string.
*
* @var string
*/
......@@ -105,7 +105,7 @@ abstract class AbstractChartWidget extends AbstractWidget implements AdditionalC
protected $buttonTarget = '';
/**
* This CSS-class is used so the JavaScript can identify the widgets containing graphs. Overriding this
* This CSS class is used so the JavaScript can identify the widgets containing graphs. Overriding this
* property could lead to the widget not working.
*
* @internal
......@@ -125,8 +125,8 @@ abstract class AbstractChartWidget extends AbstractWidget implements AdditionalC
protected $templateName = 'ChartWidget';
/**
* This method is used to define the data that will be shown in the graph. This method should be implemented and
* should set the data in the chartData property
* This method is used to define the data that will be shown in the graph. This method should be implemented
* and should set the data in the chartData property.
*
* @see chartData
*/
......
......@@ -22,11 +22,42 @@ namespace TYPO3\CMS\Dashboard\Widgets;
*/
abstract class AbstractCtaButtonWidget extends AbstractWidget
{
/**
* This link will be the main data in the widget
*
* @var string
*/
protected $link = '';
/**
* When filled, this is used as the button label
*
* @var string
*/
protected $label = '';
/**
* When filled, a text is shown above the link
*
* @var string
*/
protected $text = '';
/**
* This property contains the identifier of the icon that should be shown in the widget
*
* @var string
*/
protected $icon;
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-calltoaction';
/**
* @inheritDoc
*/
protected $templateName = 'CtaWidget';
public function __construct(string $identifier)
......
......@@ -18,15 +18,24 @@ namespace TYPO3\CMS\Dashboard\Widgets;
/**
* The AbstractDoughnutChartWidget class is the basic widget class for doughnut charts.
* It is possible to extend this class for custom widgets.
* In your class you have to store the data to display in $this->chartData
* In your class you have to store the data to display in $this->chartData.
* More information can be found in the documentation.
*/
abstract class AbstractDoughnutChartWidget extends AbstractChartWidget
{
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-chart-pie';
/**
* @inheritDoc
*/
protected $chartType = 'doughnut';
/**
* @inheritDoc
*/
protected $chartOptions = [
'maintainAspectRatio' => false,
'legend' => [
......@@ -36,7 +45,5 @@ abstract class AbstractDoughnutChartWidget extends AbstractChartWidget
'cutoutPercentage' => 60
];
protected $width = 2;
protected $height = 4;
}
......@@ -22,22 +22,54 @@ namespace TYPO3\CMS\Dashboard\Widgets;
*/
abstract class AbstractListWidget extends AbstractWidget
{
/**
* This property should contain the items to be displayed
*
* @var array
*/
protected $items = [];
protected $iconIdentifier = 'dashboard-bars';
/**
* Limit the amount of items to be displayed
*
* @var int
*/
protected $limit = 5;
protected $totalItems = 0;
protected $templateName = 'ListWidget';
protected $height = 4;
protected $width = 2;
/**
* Link to e.g. an external resource with the full items list
*
* @var string
*/
protected $moreItemsLink = '';
/**
* This should be the text for the more items link
*
* @var string
*/
protected $moreItemsText = '';
/**
* @inheritDoc
*/
protected $height = 4;
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-list';
/**
* @inheritDoc
*/
protected $templateName = 'ListWidget';
public function renderWidgetContent(): string
{
$this->view->assign('items', $this->items);
$this->view->assign('moreItemsLink', $this->moreItemsLink);
$this->view->assign('moreItemsText', $this->moreItemsText);
$this->view->assign('totalNumberOfItems', $this->totalItems);
return $this->view->render();
}
}
<?php
declare(strict_types = 1);
namespace TYPO3\CMS\Dashboard\Widgets;
/*
......@@ -17,22 +16,12 @@ namespace TYPO3\CMS\Dashboard\Widgets;
*/
/**
* The AbstractTextWidget class is the basic widget class for simple text content.
* The AbstractNumberWithIconWidget class is the basic widget class to display a number next to an icon.
* It is possible to extend this class for own widgets.
* In your class you have to set $this->text with the text to display.
* Simply overwrite $this->subtitle, $this->number and $this->icon to make use of this widget type.
*/
abstract class AbstractNumberWithIconWidget extends AbstractWidget
{
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-number';
/**
* @inheritDoc
*/
protected $templateName = 'NumberWithIconWidget';
/**
* When filled, a subtitle is shown below the title
*
......@@ -54,6 +43,16 @@ abstract class AbstractNumberWithIconWidget extends AbstractWidget
*/
protected $icon;
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-number';
/**
* @inheritDoc
*/
protected $templateName = 'NumberWithIconWidget';
protected function initializeView(): void
{
parent::initializeView();
......
<?php
declare(strict_types = 1);
namespace TYPO3\CMS\Dashboard\Widgets;
/*
......@@ -28,17 +27,40 @@ use TYPO3\CMS\Core\Utility\GeneralUtility;
*/
abstract class AbstractRssWidget extends AbstractListWidget
{
/**
* The rss file (resource) the data should be fetched from
*
* @var string
*/
protected $rssFile = '';
/**
* Lifetime of the items cache
*
* @var int
*/
protected $lifeTime = 900;
protected $iconIdentifier = 'dashboard-rss';
protected $templateName = 'RssWidget';
/**
* @inheritDoc
*/
protected $height = 6;
/**
* @inheritDoc
*/
protected $width = 4;
/**
* @inheritDoc
*/
protected $iconIdentifier = 'content-widget-rss';
/**
* @inheritDoc
*/
protected $templateName = 'RssWidget';
/**
* @var FrontendInterface
*/
......@@ -52,11 +74,6 @@ abstract class AbstractRssWidget extends AbstractListWidget
$this->loadRssFeed();
}
public function setRssFile(string $rssFile): void
{
$this->rssFile = $rssFile;
}
protected function loadRssFeed(): void
{
$cacheHash = md5($this->rssFile);
......@@ -64,7 +81,6 @@ abstract class AbstractRssWidget extends AbstractListWidget
return;
}
/** @var \SimpleXMLElement $rssFeed */
$rssContent = GeneralUtility::getUrl($this->rssFile);
if ($rssContent === false) {
throw new RuntimeException('RSS URL could not be fetched', 1573385431);
......
......@@ -25,54 +25,78 @@ use TYPO3Fluid\Fluid\View\ViewInterface;
* The AbstractWidget class is the basic widget class for all widgets.
* It is possible to extend this class for custom widgets, but EXT:dashboard provides
* some more specific types of widgets to extend from. For more details, please check:
*
* @see AbstractBarChartWidget
* @see AbstractChartWidget
* @see AbstractCtaButtonWidget
* @see AbstractDoughnutChartWidget
* @see AbstractListWidget
* @see AbstractNumberWithIconWidget
* @see AbstractRssWidget
*/
abstract class AbstractWidget implements WidgetInterface
{
/**
* The unique identifier of the widget
*
* @var string
*/
protected $identifier;
/**
* The title is used for the widget selector
*
* @var string
*/
protected $title;
/**
* The description is used for the widget selector
*
* @var string
*/
protected $description = '';
/**
* The height of the widget in rows (1-6)
*
* @var int
*/
protected $height = 2;
/**
* The width of the widget in rows (1-4)
*
* @var int
*/
protected $width = 2;
/**
* The icon identifier is used for the widget selector
*
* @var string
*/
protected $iconIdentifier = '';
/**
* The template name of the widget
*
* @var string
*/
protected $templateName = 'Widget';
/**
* Additional CSS classes which should be added to the rendered widget
*
* @var string
*/
protected $additionalClasses = '';
/**
* @var ViewInterface
*/
protected $view;
protected $additionalClasses = '';
public function __construct(string $identifier)
{
$this->identifier = $identifier;
......
<?php
declare(strict_types = 1);
namespace TYPO3\CMS\Dashboard\Widgets;
/*
......@@ -23,6 +22,9 @@ use TYPO3\CMS\Core\SysLog\Error as SystemLogErrorClassification;
use TYPO3\CMS\Core\SysLog\Type as SystemLogType;
use TYPO3\CMS\Core\Utility\GeneralUtility;
/**
* This widget will show the number of failed logins during a given period
*/
class FailedLoginsWidget extends AbstractNumberWithIconWidget
{
protected $title = 'LLL:EXT:dashboard/Resources/Private/Language/locallang.xlf:widgets.failedLogins.title';
......@@ -36,39 +38,32 @@ class FailedLoginsWidget extends AbstractNumberWithIconWidget
parent::initializeView();
}
/**
* Get number of failed logins during a period
*
* @param int $secondsBack
*
* @return int
*/
public function getNumberOfFailedLogins(int $secondsBack = 86400): int
{
$connectionPool = GeneralUtility::makeInstance(ConnectionPool::class);
$queryBuilder = $connectionPool->getQueryBuilderForTable('sys_log');
return (int)$queryBuilder->count('uid')
->from('sys_log')
->where(
$queryBuilder->expr()->eq(
'type',
$queryBuilder->createNamedParameter(SystemLogType::LOGIN, Connection::PARAM_INT)
),
$queryBuilder->expr()->eq(
'action',
$queryBuilder->createNamedParameter(SystemLogLoginAction::ATTEMPT, Connection::PARAM_INT)
),
$queryBuilder->expr()->neq(
'error',
$queryBuilder->createNamedParameter(SystemLogErrorClassification::MESSAGE, Connection::PARAM_INT)
),
$queryBuilder->expr()->gt(
'tstamp',
$queryBuilder->createNamedParameter($GLOBALS['EXEC_TIME'] - $secondsBack, Connection::PARAM_INT)
)
->from('sys_log')
->where(
$queryBuilder->expr()->eq(
'type',
$queryBuilder->createNamedParameter(SystemLogType::LOGIN, Connection::PARAM_INT)
),
$queryBuilder->expr()->eq(
'action',
$queryBuilder->createNamedParameter(SystemLogLoginAction::ATTEMPT, Connection::PARAM_INT)