From b1e0dd331a81a8c6381c2ca60dc0f50eec30d1d3 Mon Sep 17 00:00:00 2001 From: Marcel Werk Date: Wed, 13 Nov 2024 14:14:58 +0100 Subject: [PATCH] Add code documentation --- .../lib/action/GridViewFilterAction.class.php | 10 +- .../lib/page/AbstractGridViewPage.class.php | 11 ++ .../core/gridViews/GetRows.class.php | 8 + .../gridView/AbstractGridView.class.php | 155 ++++++++++++++++-- .../gridView/CronjobLogGridView.class.php | 8 + .../gridView/DataSourceGridView.class.php | 26 +++ .../DatabaseObjectListGridView.class.php | 23 +++ .../gridView/ExceptionLogGridView.class.php | 8 + .../system/gridView/GridViewColumn.class.php | 81 ++++++++- .../system/gridView/GridViewRowLink.class.php | 11 ++ .../gridView/UserOptionGridView.class.php | 8 + .../gridView/UserRankGridView.class.php | 8 + .../gridView/action/AbstractAction.class.php | 8 + .../gridView/action/DeleteAction.class.php | 8 + .../gridView/action/EditAction.class.php | 8 + .../gridView/action/IGridViewAction.class.php | 20 +++ .../gridView/action/ToggleAction.class.php | 8 + .../gridView/filter/I18nTextFilter.class.php | 8 + .../gridView/filter/IGridViewFilter.class.php | 20 +++ .../gridView/filter/SelectFilter.class.php | 8 + .../gridView/filter/TextFilter.class.php | 8 + .../gridView/filter/TimeFilter.class.php | 8 + .../renderer/AbstractColumnRenderer.class.php | 9 + .../renderer/DefaultColumnRenderer.class.php | 11 ++ .../renderer/IColumnRenderer.class.php | 14 ++ .../renderer/LinkColumnRenderer.class.php | 9 + .../renderer/NumberColumnRenderer.class.php | 10 ++ .../renderer/PhraseColumnRenderer.class.php | 9 + .../renderer/TimeColumnRenderer.class.php | 10 ++ .../renderer/TitleColumnRenderer.class.php | 9 + 30 files changed, 514 insertions(+), 28 deletions(-) diff --git a/wcfsetup/install/files/lib/action/GridViewFilterAction.class.php b/wcfsetup/install/files/lib/action/GridViewFilterAction.class.php index f3579f8c26..189381e140 100644 --- a/wcfsetup/install/files/lib/action/GridViewFilterAction.class.php +++ b/wcfsetup/install/files/lib/action/GridViewFilterAction.class.php @@ -11,9 +11,17 @@ use wcf\system\exception\IllegalLinkException; use wcf\system\exception\PermissionDeniedException; use wcf\system\exception\UserInputException; use wcf\system\form\builder\Psr15DialogForm; -use wcf\system\view\grid\AbstractGridView; +use wcf\system\gridView\AbstractGridView; use wcf\system\WCF; +/** + * Handles the filter dialog of grid views. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ final class GridViewFilterAction implements RequestHandlerInterface { #[\Override] diff --git a/wcfsetup/install/files/lib/page/AbstractGridViewPage.class.php b/wcfsetup/install/files/lib/page/AbstractGridViewPage.class.php index 46eee81332..b3dd37746d 100644 --- a/wcfsetup/install/files/lib/page/AbstractGridViewPage.class.php +++ b/wcfsetup/install/files/lib/page/AbstractGridViewPage.class.php @@ -6,6 +6,14 @@ use wcf\system\request\LinkHandler; use wcf\system\gridView\AbstractGridView; use wcf\system\WCF; +/** + * Abstract implementation of a page that is rendering a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ abstract class AbstractGridViewPage extends AbstractPage { protected AbstractGridView $gridView; @@ -70,5 +78,8 @@ abstract class AbstractGridViewPage extends AbstractPage $this->gridView->setBaseUrl(LinkHandler::getInstance()->getControllerLink(static::class)); } + /** + * Returns the grid view instance for the rendering of this page. + */ protected abstract function createGridViewController(): AbstractGridView; } diff --git a/wcfsetup/install/files/lib/system/endpoint/controller/core/gridViews/GetRows.class.php b/wcfsetup/install/files/lib/system/endpoint/controller/core/gridViews/GetRows.class.php index dd5b977b83..d1213a60df 100644 --- a/wcfsetup/install/files/lib/system/endpoint/controller/core/gridViews/GetRows.class.php +++ b/wcfsetup/install/files/lib/system/endpoint/controller/core/gridViews/GetRows.class.php @@ -12,6 +12,14 @@ use wcf\system\exception\PermissionDeniedException; use wcf\system\exception\UserInputException; use wcf\system\gridView\AbstractGridView; +/** + * Retrieves the rows for a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ #[GetRequest('/core/gridViews/rows')] final class GetRows implements IController { diff --git a/wcfsetup/install/files/lib/system/gridView/AbstractGridView.class.php b/wcfsetup/install/files/lib/system/gridView/AbstractGridView.class.php index 855dc37427..40e6d56117 100644 --- a/wcfsetup/install/files/lib/system/gridView/AbstractGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/AbstractGridView.class.php @@ -10,6 +10,14 @@ use wcf\system\gridView\action\IGridViewAction; use wcf\system\request\LinkHandler; use wcf\system\WCF; +/** + * Abstract implementation of a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ abstract class AbstractGridView { /** @@ -128,6 +136,25 @@ abstract class AbstractGridView } /** + * Returns all columns that are sortable. + * @return GridViewColumn[] + */ + public function getSortableColumns(): array + { + return \array_filter($this->getColumns(), fn($column) => $column->isSortable()); + } + + /** + * Returns all columns that are filterable. + * @return GridViewColumn[] + */ + public function getFilterableColumns(): array + { + return \array_filter($this->getColumns(), fn($column) => $column->getFilter() !== null); + } + + /** + * Adds the given actions to the grid view. * @param IGridViewAction[] $columns */ public function addActions(array $actions): void @@ -137,12 +164,16 @@ abstract class AbstractGridView } } + /** + * Adds the given action to the grid view. + */ public function addAction(IGridViewAction $action): void { $this->actions[] = $action; } /** + * Returns all actions of the grid view. * @return IGridViewAction[] */ public function getActions(): array @@ -150,17 +181,24 @@ abstract class AbstractGridView return $this->actions; } + /** + * Returns true, if this grid view has actions. + */ public function hasActions(): bool { return $this->actions !== []; } + /** + * Returns true, if this grid view has actions that should be displayed in the dropdown. + */ public function hasDropdownActions(): bool { return $this->getDropdownActions() !== []; } /** + * Returns the actions that should be displayed in the dropdown. * @return IGridViewAction[] */ public function getDropdownActions(): array @@ -169,6 +207,7 @@ abstract class AbstractGridView } /** + * Returns the quick actions. * @return IGridViewAction[] */ public function getQuickActions(): array @@ -176,16 +215,25 @@ abstract class AbstractGridView return \array_filter($this->getActions(), fn($action) => $action->isQuickAction()); } + /** + * Renders the grid view and returns the HTML code. + */ public function render(): string { return WCF::getTPL()->fetch('shared_gridView', 'wcf', ['view' => $this], true); } + /** + * Renders the rows and returns the HTML code. + */ public function renderRows(): string { return WCF::getTPL()->fetch('shared_gridViewRows', 'wcf', ['view' => $this], true); } + /** + * Renders the given grid view column. + */ public function renderColumn(GridViewColumn $column, mixed $row): string { $value = $column->render($this->getData($row, $column->getID()), $row); @@ -197,11 +245,17 @@ abstract class AbstractGridView return $value; } + /** + * Renders the given action. + */ public function renderAction(IGridViewAction $action, mixed $row): string { return $action->render($row); } + /** + * Renders the initialization code for the actions of the grid view. + */ public function renderActionInitialization(): string { return implode( @@ -213,30 +267,41 @@ abstract class AbstractGridView ); } + /** + * Returns the row data for the given identifier. + */ protected function getData(mixed $row, string $identifer): mixed { return $row[$identifer] ?? ''; } - public abstract function getRows(): array; - - public abstract function countRows(): int; - + /** + * Counts the pages of the grid view. + */ public function countPages(): int { return \ceil($this->countRows() / $this->getRowsPerPage()); } + /** + * Returns the class name of this grid view. + */ public function getClassName(): string { return \get_class($this); } + /** + * Returns true, if this grid view is accessible for the active user. + */ public function isAccessible(): bool { return true; } + /** + * Returns the id of this grid view. + */ public function getID(): string { $classNamePieces = \explode('\\', static::class); @@ -244,32 +309,25 @@ abstract class AbstractGridView return \implode('-', $classNamePieces); } + /** + * Sets the base url of the grid view. + */ public function setBaseUrl(string $url): void { $this->baseUrl = $url; } - public function getBaseUrl(): string - { - return $this->baseUrl; - } - /** - * @return GridViewColumn[] + * Returns the base url of the grid view. */ - public function getSortableColumns(): array + public function getBaseUrl(): string { - return \array_filter($this->getColumns(), fn($column) => $column->isSortable()); + return $this->baseUrl; } /** - * @return GridViewColumn[] + * Sets the sort field of the grid view. */ - public function getFilterableColumns(): array - { - return \array_filter($this->getColumns(), fn($column) => $column->getFilter() !== null); - } - public function setSortField(string $sortField): void { if (!\in_array($sortField, \array_map(fn($column) => $column->getID(), $this->getSortableColumns()))) { @@ -279,6 +337,9 @@ abstract class AbstractGridView $this->sortField = $sortField; } + /** + * Sets the sort order of the grid view. + */ public function setSortOrder(string $sortOrder): void { if ($sortOrder !== 'ASC' && $sortOrder !== 'DESC') { @@ -288,41 +349,65 @@ abstract class AbstractGridView $this->sortOrder = $sortOrder; } + /** + * Returns the sort field of the grid view. + */ public function getSortField(): string { return $this->sortField; } + /** + * Returns the sort order of the grid view. + */ public function getSortOrder(): string { return $this->sortOrder; } + /** + * Returns the page number. + */ public function getPageNo(): int { return $this->pageNo; } + /** + * Sets the page number. + */ public function setPageNo(int $pageNo): void { $this->pageNo = $pageNo; } + /** + * Returns the number of rows per page. + */ public function getRowsPerPage(): int { return $this->rowsPerPage; } + /** + * Sets the number of rows per page. + */ public function setRowsPerPage(int $rowsPerPage): void { $this->rowsPerPage = $rowsPerPage; } + /** + * Returns true, if the grid view is filterable. + */ public function isFilterable(): bool { return $this->getFilterableColumns() !== []; } + /** + * Returns the endpoint for the filter action. + */ public function getFilterActionEndpoint(): string { return LinkHandler::getInstance()->getControllerLink( @@ -331,16 +416,25 @@ abstract class AbstractGridView ); } + /** + * Sets the active filter values. + */ public function setActiveFilters(array $filters): void { $this->activeFilters = $filters; } + /** + * Returns the active filter values. + */ public function getActiveFilters(): array { return $this->activeFilters; } + /** + * Returns the label for the given filter. + */ public function getFilterLabel(string $id): string { $column = $this->getColumn($id); @@ -359,21 +453,33 @@ abstract class AbstractGridView return $column->getLabel() . ': ' . $column->getFilter()->renderValue($this->activeFilters[$id]); } + /** + * Gets the additional parameters of the grid view. + */ public function getParameters(): array { return []; } + /** + * Adds the given row link to the grid view. + */ public function addRowLink(GridViewRowLink $rowLink): void { $this->rowLink = $rowLink; } + /** + * Returns the id for the given row. + */ public function getObjectID(mixed $row): mixed { return ''; } + /** + * Fires the initialized event. + */ protected function fireInitializedEvent(): void { $event = $this->getInitializedEvent(); @@ -384,8 +490,21 @@ abstract class AbstractGridView EventHandler::getInstance()->fire($event); } + /** + * Returns the initialized event or null if there is no such event for this grid view. + */ protected function getInitializedEvent(): ?IPsr14Event { return null; } + + /** + * Returns the rows for the active page. + */ + public abstract function getRows(): array; + + /** + * Returns the total number of rows. + */ + public abstract function countRows(): int; } diff --git a/wcfsetup/install/files/lib/system/gridView/CronjobLogGridView.class.php b/wcfsetup/install/files/lib/system/gridView/CronjobLogGridView.class.php index 3c9f634c16..3c3c191a29 100644 --- a/wcfsetup/install/files/lib/system/gridView/CronjobLogGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/CronjobLogGridView.class.php @@ -18,6 +18,14 @@ use wcf\system\gridView\renderer\TitleColumnRenderer; use wcf\system\WCF; use wcf\util\StringUtil; +/** + * Grid view for the cronjob log. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ final class CronjobLogGridView extends DatabaseObjectListGridView { public function __construct() diff --git a/wcfsetup/install/files/lib/system/gridView/DataSourceGridView.class.php b/wcfsetup/install/files/lib/system/gridView/DataSourceGridView.class.php index 99b4acafd9..b606cab280 100644 --- a/wcfsetup/install/files/lib/system/gridView/DataSourceGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/DataSourceGridView.class.php @@ -4,10 +4,19 @@ namespace wcf\system\gridView; use LogicException; +/** + * Abstract implementation of a grid view that uses an array as the data source. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ abstract class DataSourceGridView extends AbstractGridView { protected array $dataSource; + #[\Override] public function getRows(): array { $this->sortRows(); @@ -15,8 +24,12 @@ abstract class DataSourceGridView extends AbstractGridView return $this->getRowsForPage(); } + /** + * Sorts the rows. + */ protected function sortRows(): void { + // Necessary to ensure that dataSource has been initialized. $this->getDataSource(); \uasort($this->dataSource, function (array $a, array $b) { @@ -28,16 +41,23 @@ abstract class DataSourceGridView extends AbstractGridView }); } + /** + * Returns the rows for the active page. + */ protected function getRowsForPage(): array { return \array_slice($this->getDataSource(), ($this->getPageNo() - 1) * $this->getRowsPerPage(), $this->getRowsPerPage()); } + #[\Override] public function countRows(): int { return \count($this->getDataSource()); } + /** + * Returns the data source array. + */ protected function getDataSource(): array { if (!isset($this->dataSource)) { @@ -49,6 +69,9 @@ abstract class DataSourceGridView extends AbstractGridView return $this->dataSource; } + /** + * Applies the active filters. + */ protected function applyFilters(): void { foreach ($this->getActiveFilters() as $key => $value) { @@ -63,5 +86,8 @@ abstract class DataSourceGridView extends AbstractGridView } } + /** + * Loads the data source array. + */ protected abstract function loadDataSource(): array; } diff --git a/wcfsetup/install/files/lib/system/gridView/DatabaseObjectListGridView.class.php b/wcfsetup/install/files/lib/system/gridView/DatabaseObjectListGridView.class.php index d8eacc2e4b..ff013025ea 100644 --- a/wcfsetup/install/files/lib/system/gridView/DatabaseObjectListGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/DatabaseObjectListGridView.class.php @@ -6,11 +6,20 @@ use LogicException; use wcf\data\DatabaseObject; use wcf\data\DatabaseObjectList; +/** + * Abstract implementation of a grid view that uses a database object list as the data source. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ abstract class DatabaseObjectListGridView extends AbstractGridView { protected DatabaseObjectList $objectList; private int $objectCount; + #[\Override] public function getRows(): array { $this->getObjectList()->readObjects(); @@ -18,6 +27,7 @@ abstract class DatabaseObjectListGridView extends AbstractGridView return $this->getObjectList()->getObjects(); } + #[\Override] public function countRows(): int { if (!isset($this->objectCount)) { @@ -27,6 +37,7 @@ abstract class DatabaseObjectListGridView extends AbstractGridView return $this->objectCount; } + #[\Override] protected function getData(mixed $row, string $identifer): mixed { \assert($row instanceof DatabaseObject); @@ -34,6 +45,9 @@ abstract class DatabaseObjectListGridView extends AbstractGridView return $row->__get($identifer); } + /** + * Initializes the database object list. + */ protected function initObjectList(): void { $this->objectList = $this->createObjectList(); @@ -51,6 +65,9 @@ abstract class DatabaseObjectListGridView extends AbstractGridView $this->fireInitializedEvent(); } + /** + * Returns the database object list. + */ public function getObjectList(): DatabaseObjectList { if (!isset($this->objectList)) { @@ -60,6 +77,9 @@ abstract class DatabaseObjectListGridView extends AbstractGridView return $this->objectList; } + /** + * Applies the active filters. + */ protected function applyFilters(): void { foreach ($this->getActiveFilters() as $key => $value) { @@ -80,5 +100,8 @@ abstract class DatabaseObjectListGridView extends AbstractGridView return $row->getObjectID(); } + /** + * Creates the database object list of this grid view. + */ protected abstract function createObjectList(): DatabaseObjectList; } diff --git a/wcfsetup/install/files/lib/system/gridView/ExceptionLogGridView.class.php b/wcfsetup/install/files/lib/system/gridView/ExceptionLogGridView.class.php index c1412afd2e..13bf2f7298 100644 --- a/wcfsetup/install/files/lib/system/gridView/ExceptionLogGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/ExceptionLogGridView.class.php @@ -13,6 +13,14 @@ use wcf\system\WCF; use wcf\util\DirectoryUtil; use wcf\util\ExceptionLogUtil; +/** + * Grid view for the exception log. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ final class ExceptionLogGridView extends DataSourceGridView { private array $availableLogFiles; diff --git a/wcfsetup/install/files/lib/system/gridView/GridViewColumn.class.php b/wcfsetup/install/files/lib/system/gridView/GridViewColumn.class.php index b8108d5746..5542fda3c3 100644 --- a/wcfsetup/install/files/lib/system/gridView/GridViewColumn.class.php +++ b/wcfsetup/install/files/lib/system/gridView/GridViewColumn.class.php @@ -9,6 +9,14 @@ use wcf\system\gridView\renderer\IColumnRenderer; use wcf\system\gridView\renderer\TitleColumnRenderer; use wcf\system\WCF; +/** + * Represents a column of a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ final class GridViewColumn { /** @@ -24,11 +32,17 @@ final class GridViewColumn private function __construct(private readonly string $id) {} + /** + * Creates a new column with the given id. + */ public static function for(string $id): static { return new static($id); } + /** + * Renders the column with the given value. + */ public function render(mixed $value, mixed $context = null): string { if ($this->getRenderers() === []) { @@ -42,6 +56,9 @@ final class GridViewColumn return $value; } + /** + * Returns the css classes of this column. + */ public function getClasses(): string { if ($this->getRenderers() === []) { @@ -56,6 +73,9 @@ final class GridViewColumn )); } + /** + * Sets the renderer of this column. + */ public function renderer(array|IColumnRenderer $renderers): static { if (!\is_array($renderers)) { @@ -70,6 +90,9 @@ final class GridViewColumn return $this; } + /** + * Sets the label of this column. + */ public function label(string $languageItem): static { $this->label = WCF::getLanguage()->get($languageItem); @@ -77,6 +100,9 @@ final class GridViewColumn return $this; } + /** + * Sets the sortable state of this column. + */ public function sortable(bool $sortable = true): static { $this->sortable = $sortable; @@ -84,6 +110,9 @@ final class GridViewColumn return $this; } + /** + * Defines the ID by which this column is to be sorted. + */ public function sortById(string $id): static { $this->sortById = $id; @@ -92,6 +121,7 @@ final class GridViewColumn } /** + * Returns the renderers of this column. * @return IColumnRenderer[] */ public function getRenderers(): array @@ -99,26 +129,41 @@ final class GridViewColumn return $this->renderer; } + /** + * Returns the id of this column. + */ public function getID(): string { return $this->id; } + /** + * Returns the label of this column. + */ public function getLabel(): string { return $this->label; } + /** + * Returns true if this column is sortable. + */ public function isSortable(): bool { return $this->sortable; } + /** + * Returns the ID by which this column is to be sorted. + */ public function getSortById(): string { return $this->sortById; } + /** + * Sets a filter for this column. + */ public function filter(?IGridViewFilter $filter): static { $this->filter = $filter; @@ -126,11 +171,17 @@ final class GridViewColumn return $this; } + /** + * Returns the filter of this column. + */ public function getFilter(): ?IGridViewFilter { return $this->filter; } + /** + * Returns the filter form field of this column. + */ public function getFilterFormField(): AbstractFormField { if ($this->getFilter() === null) { @@ -140,15 +191,9 @@ final class GridViewColumn return $this->getFilter()->getFormField($this->getID(), $this->getLabel()); } - private static function getDefaultRenderer(): DefaultColumnRenderer - { - if (!isset(self::$defaultRenderer)) { - self::$defaultRenderer = new DefaultColumnRenderer(); - } - - return self::$defaultRenderer; - } - + /** + * Returns true if this column is a title column. + */ public function isTitleColumn(): bool { foreach ($this->getRenderers() as $renderer) { @@ -160,6 +205,9 @@ final class GridViewColumn return false; } + /** + * Sets the hidden state of this column. + */ public function hidden(bool $hidden = true): static { $this->hidden = $hidden; @@ -167,8 +215,23 @@ final class GridViewColumn return $this; } + /** + * Returns true if this column is hidden. + */ public function isHidden(): bool { return $this->hidden; } + + /** + * Returns the default renderer for the rendering of columns. + */ + private static function getDefaultRenderer(): DefaultColumnRenderer + { + if (!isset(self::$defaultRenderer)) { + self::$defaultRenderer = new DefaultColumnRenderer(); + } + + return self::$defaultRenderer; + } } diff --git a/wcfsetup/install/files/lib/system/gridView/GridViewRowLink.class.php b/wcfsetup/install/files/lib/system/gridView/GridViewRowLink.class.php index 5031df3602..518916a733 100644 --- a/wcfsetup/install/files/lib/system/gridView/GridViewRowLink.class.php +++ b/wcfsetup/install/files/lib/system/gridView/GridViewRowLink.class.php @@ -6,6 +6,14 @@ use wcf\data\DatabaseObject; use wcf\system\request\LinkHandler; use wcf\util\StringUtil; +/** + * Represents a row link of a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class GridViewRowLink { public function __construct( @@ -14,6 +22,9 @@ class GridViewRowLink private readonly string $cssClass = '' ) {} + /** + * Renders the row link. + */ public function render(mixed $value, mixed $context = null, bool $isPrimaryColumn = false): string { $href = ''; diff --git a/wcfsetup/install/files/lib/system/gridView/UserOptionGridView.class.php b/wcfsetup/install/files/lib/system/gridView/UserOptionGridView.class.php index 5e5d06c417..092228cc24 100644 --- a/wcfsetup/install/files/lib/system/gridView/UserOptionGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/UserOptionGridView.class.php @@ -17,6 +17,14 @@ use wcf\system\gridView\renderer\TitleColumnRenderer; use wcf\system\WCF; use wcf\util\StringUtil; +/** + * Grid view for the list of user options. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ final class UserOptionGridView extends DatabaseObjectListGridView { public function __construct() diff --git a/wcfsetup/install/files/lib/system/gridView/UserRankGridView.class.php b/wcfsetup/install/files/lib/system/gridView/UserRankGridView.class.php index 30d20935e8..11ea17e9eb 100644 --- a/wcfsetup/install/files/lib/system/gridView/UserRankGridView.class.php +++ b/wcfsetup/install/files/lib/system/gridView/UserRankGridView.class.php @@ -19,6 +19,14 @@ use wcf\system\gridView\renderer\TitleColumnRenderer; use wcf\system\WCF; use wcf\util\StringUtil; +/** + * Grid view for the list of user ranks. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ final class UserRankGridView extends DatabaseObjectListGridView { public function __construct() diff --git a/wcfsetup/install/files/lib/system/gridView/action/AbstractAction.class.php b/wcfsetup/install/files/lib/system/gridView/action/AbstractAction.class.php index 169f6678f6..e975908d53 100644 --- a/wcfsetup/install/files/lib/system/gridView/action/AbstractAction.class.php +++ b/wcfsetup/install/files/lib/system/gridView/action/AbstractAction.class.php @@ -4,6 +4,14 @@ namespace wcf\system\gridView\action; use Closure; +/** + * Provides an abstract implementation of a grid view action. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ abstract class AbstractAction implements IGridViewAction { public function __construct( diff --git a/wcfsetup/install/files/lib/system/gridView/action/DeleteAction.class.php b/wcfsetup/install/files/lib/system/gridView/action/DeleteAction.class.php index 0f52c3d8b8..a71d6b6add 100644 --- a/wcfsetup/install/files/lib/system/gridView/action/DeleteAction.class.php +++ b/wcfsetup/install/files/lib/system/gridView/action/DeleteAction.class.php @@ -11,6 +11,14 @@ use wcf\system\request\LinkHandler; use wcf\system\WCF; use wcf\util\StringUtil; +/** + * Represents a delete action. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class DeleteAction extends AbstractAction { public function __construct( diff --git a/wcfsetup/install/files/lib/system/gridView/action/EditAction.class.php b/wcfsetup/install/files/lib/system/gridView/action/EditAction.class.php index aa9029bf09..73fae2c482 100644 --- a/wcfsetup/install/files/lib/system/gridView/action/EditAction.class.php +++ b/wcfsetup/install/files/lib/system/gridView/action/EditAction.class.php @@ -8,6 +8,14 @@ use wcf\system\gridView\AbstractGridView; use wcf\system\request\LinkHandler; use wcf\system\WCF; +/** + * Represents an edit action. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class EditAction extends AbstractAction { public function __construct( diff --git a/wcfsetup/install/files/lib/system/gridView/action/IGridViewAction.class.php b/wcfsetup/install/files/lib/system/gridView/action/IGridViewAction.class.php index fdcc0b197a..3ca6c33397 100644 --- a/wcfsetup/install/files/lib/system/gridView/action/IGridViewAction.class.php +++ b/wcfsetup/install/files/lib/system/gridView/action/IGridViewAction.class.php @@ -4,13 +4,33 @@ namespace wcf\system\gridView\action; use wcf\system\gridView\AbstractGridView; +/** + * Represents an action of a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ interface IGridViewAction { + /** + * Renders the action. + */ public function render(mixed $row): string; + /** + * Renders the initialization code for this action. + */ public function renderInitialization(AbstractGridView $gridView): ?string; + /** + * Returns true if this is a quick action. + */ public function isQuickAction(): bool; + /** + * Returns true if this action is available for the given row. + */ public function isAvailable(mixed $row): bool; } diff --git a/wcfsetup/install/files/lib/system/gridView/action/ToggleAction.class.php b/wcfsetup/install/files/lib/system/gridView/action/ToggleAction.class.php index 27d9fe9349..57f8224479 100644 --- a/wcfsetup/install/files/lib/system/gridView/action/ToggleAction.class.php +++ b/wcfsetup/install/files/lib/system/gridView/action/ToggleAction.class.php @@ -10,6 +10,14 @@ use wcf\system\request\LinkHandler; use wcf\system\WCF; use wcf\util\StringUtil; +/** + * Represents a toggle action. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class ToggleAction extends AbstractAction { public function __construct( diff --git a/wcfsetup/install/files/lib/system/gridView/filter/I18nTextFilter.class.php b/wcfsetup/install/files/lib/system/gridView/filter/I18nTextFilter.class.php index e70eb2c085..244c8b26c1 100644 --- a/wcfsetup/install/files/lib/system/gridView/filter/I18nTextFilter.class.php +++ b/wcfsetup/install/files/lib/system/gridView/filter/I18nTextFilter.class.php @@ -5,6 +5,14 @@ namespace wcf\system\gridView\filter; use wcf\data\DatabaseObjectList; use wcf\system\WCF; +/** + * Filter for text columns that are using i18n phrases. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class I18nTextFilter extends TextFilter { #[\Override] diff --git a/wcfsetup/install/files/lib/system/gridView/filter/IGridViewFilter.class.php b/wcfsetup/install/files/lib/system/gridView/filter/IGridViewFilter.class.php index 43ef851258..f9a6c2649c 100644 --- a/wcfsetup/install/files/lib/system/gridView/filter/IGridViewFilter.class.php +++ b/wcfsetup/install/files/lib/system/gridView/filter/IGridViewFilter.class.php @@ -5,13 +5,33 @@ namespace wcf\system\gridView\filter; use wcf\data\DatabaseObjectList; use wcf\system\form\builder\field\AbstractFormField; +/** + * Represents a filter of a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ interface IGridViewFilter { + /** + * Returns the form field for the input of this filter. + */ public function getFormField(string $id, string $label): AbstractFormField; + /** + * Applies the filter to the given database object list. + */ public function applyFilter(DatabaseObjectList $list, string $id, string $value): void; + /** + * Returns true if the given filter value matches the row. + */ public function matches(string $filterValue, string $rowValue): bool; + /** + * Renders the filter value in a human readable format. + */ public function renderValue(string $value): string; } diff --git a/wcfsetup/install/files/lib/system/gridView/filter/SelectFilter.class.php b/wcfsetup/install/files/lib/system/gridView/filter/SelectFilter.class.php index e595547365..b6b6179bd6 100644 --- a/wcfsetup/install/files/lib/system/gridView/filter/SelectFilter.class.php +++ b/wcfsetup/install/files/lib/system/gridView/filter/SelectFilter.class.php @@ -7,6 +7,14 @@ use wcf\system\form\builder\field\AbstractFormField; use wcf\system\form\builder\field\SelectFormField; use wcf\system\WCF; +/** + * Allows a column to be filtered on the basis of a select dropdown. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class SelectFilter implements IGridViewFilter { public function __construct(private readonly array $options) {} diff --git a/wcfsetup/install/files/lib/system/gridView/filter/TextFilter.class.php b/wcfsetup/install/files/lib/system/gridView/filter/TextFilter.class.php index 5201439a02..cb737a538b 100644 --- a/wcfsetup/install/files/lib/system/gridView/filter/TextFilter.class.php +++ b/wcfsetup/install/files/lib/system/gridView/filter/TextFilter.class.php @@ -6,6 +6,14 @@ use wcf\data\DatabaseObjectList; use wcf\system\form\builder\field\AbstractFormField; use wcf\system\form\builder\field\TextFormField; +/** + * Filter for text columns. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class TextFilter implements IGridViewFilter { #[\Override] diff --git a/wcfsetup/install/files/lib/system/gridView/filter/TimeFilter.class.php b/wcfsetup/install/files/lib/system/gridView/filter/TimeFilter.class.php index b00cca1480..a5184ad52d 100644 --- a/wcfsetup/install/files/lib/system/gridView/filter/TimeFilter.class.php +++ b/wcfsetup/install/files/lib/system/gridView/filter/TimeFilter.class.php @@ -7,6 +7,14 @@ use wcf\system\form\builder\field\AbstractFormField; use wcf\system\form\builder\field\DateRangeFormField; use wcf\system\WCF; +/** + * Filter for time columns. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class TimeFilter implements IGridViewFilter { #[\Override] diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/AbstractColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/AbstractColumnRenderer.class.php index 6540c87680..5400204e34 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/AbstractColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/AbstractColumnRenderer.class.php @@ -2,8 +2,17 @@ namespace wcf\system\gridView\renderer; +/** + * Provides an abstract implementation of a column renderer. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ abstract class AbstractColumnRenderer implements IColumnRenderer { + #[\Override] public function getClasses(): string { return ''; diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/DefaultColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/DefaultColumnRenderer.class.php index 90f4ea1a0d..c951075dad 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/DefaultColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/DefaultColumnRenderer.class.php @@ -4,13 +4,24 @@ namespace wcf\system\gridView\renderer; use wcf\util\StringUtil; +/** + * The default column renderer is automatically applied to all columns if no other renderers have been set. + * It converts special characters to HTML entities. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class DefaultColumnRenderer extends AbstractColumnRenderer { + #[\Override] public function render(mixed $value, mixed $context = null): string { return StringUtil::encodeHTML($value); } + #[\Override] public function getClasses(): string { return 'gridView__column--text'; diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/IColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/IColumnRenderer.class.php index acf0eb3ef0..eda6c61af6 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/IColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/IColumnRenderer.class.php @@ -2,9 +2,23 @@ namespace wcf\system\gridView\renderer; +/** + * Represents a column renderer of a grid view. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ interface IColumnRenderer { + /** + * Renders the content of a column with the given value. + */ public function render(mixed $value, mixed $context = null): string; + /** + * Returns the css classes of a column. + */ public function getClasses(): string; } diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/LinkColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/LinkColumnRenderer.class.php index 05aa62d1ff..0cd43611e3 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/LinkColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/LinkColumnRenderer.class.php @@ -6,6 +6,14 @@ use wcf\data\DatabaseObject; use wcf\system\request\LinkHandler; use wcf\system\WCF; +/** + * Allows the setting of a link to a column. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class LinkColumnRenderer extends AbstractColumnRenderer { public function __construct( @@ -14,6 +22,7 @@ class LinkColumnRenderer extends AbstractColumnRenderer private readonly string $titleLanguageItem = '' ) {} + #[\Override] public function render(mixed $value, mixed $context = null): string { \assert($context instanceof DatabaseObject); diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/NumberColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/NumberColumnRenderer.class.php index 845c91fc79..17cebe1bfc 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/NumberColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/NumberColumnRenderer.class.php @@ -4,13 +4,23 @@ namespace wcf\system\gridView\renderer; use wcf\util\StringUtil; +/** + * Formats the content of a column as a number. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class NumberColumnRenderer extends AbstractColumnRenderer { + #[\Override] public function render(mixed $value, mixed $context = null): string { return StringUtil::formatNumeric($value); } + #[\Override] public function getClasses(): string { return 'gridView__column--digits'; diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/PhraseColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/PhraseColumnRenderer.class.php index 3d4ccaba41..c240a4e919 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/PhraseColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/PhraseColumnRenderer.class.php @@ -5,8 +5,17 @@ namespace wcf\system\gridView\renderer; use wcf\system\WCF; use wcf\util\StringUtil; +/** + * Formats the content of a column as a phrase. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class PhraseColumnRenderer extends DefaultColumnRenderer { + #[\Override] public function render(mixed $value, mixed $context = null): string { return StringUtil::encodeHTML(WCF::getLanguage()->get($value)); diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/TimeColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/TimeColumnRenderer.class.php index 7784d9e5ee..3028847f6b 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/TimeColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/TimeColumnRenderer.class.php @@ -4,8 +4,17 @@ namespace wcf\system\gridView\renderer; use wcf\system\WCF; +/** + * Renders a unix timestamp into a human readable format. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class TimeColumnRenderer extends AbstractColumnRenderer { + #[\Override] public function render(mixed $value, mixed $context = null): string { $timestamp = \intval($value); @@ -36,6 +45,7 @@ class TimeColumnRenderer extends AbstractColumnRenderer ); } + #[\Override] public function getClasses(): string { return 'gridView__column--date'; diff --git a/wcfsetup/install/files/lib/system/gridView/renderer/TitleColumnRenderer.class.php b/wcfsetup/install/files/lib/system/gridView/renderer/TitleColumnRenderer.class.php index 60d91546c8..d120f58742 100644 --- a/wcfsetup/install/files/lib/system/gridView/renderer/TitleColumnRenderer.class.php +++ b/wcfsetup/install/files/lib/system/gridView/renderer/TitleColumnRenderer.class.php @@ -2,8 +2,17 @@ namespace wcf\system\gridView\renderer; +/** + * Formats the content of a column as a title. + * + * @author Marcel Werk + * @copyright 2001-2024 WoltLab GmbH + * @license GNU Lesser General Public License + * @since 6.2 + */ class TitleColumnRenderer extends DefaultColumnRenderer { + #[\Override] public function getClasses(): string { return 'gridView__column--title'; -- 2.20.1