diff --git a/Documentation/ApiOverview/Backend/PageTree.rst b/Documentation/ApiOverview/Backend/PageTree.rst index c1bb65bb5..9c8c9e908 100644 --- a/Documentation/ApiOverview/Backend/PageTree.rst +++ b/Documentation/ApiOverview/Backend/PageTree.rst @@ -32,6 +32,9 @@ PSR-14 events to influence the functionality of the page tree :ref:`AfterRawPageRowPreparedEvent` Allows to modify the populated properties of a page and children records before the page is displayed in a page tree. +:ref:`BeforePageTreeIsFilteredEvent` + Allows developers to extend the page trees filter's functionality and + process the given search phrase in more advanced ways. .. _page-tree-tsconfig: diff --git a/Documentation/ApiOverview/Events/Events/Backend/BeforePageTreeIsFilteredEvent.rst b/Documentation/ApiOverview/Events/Events/Backend/BeforePageTreeIsFilteredEvent.rst new file mode 100644 index 000000000..3bf143ab8 --- /dev/null +++ b/Documentation/ApiOverview/Events/Events/Backend/BeforePageTreeIsFilteredEvent.rst @@ -0,0 +1,60 @@ +.. include:: /Includes.rst.txt +.. index:: Events; BeforePageTreeIsFilteredEvent +.. _BeforePageTreeIsFilteredEvent: + +============================= +BeforePageTreeIsFilteredEvent +============================= + +.. versionadded:: 14.0 + This PSR-14 event was introduced to add custom functionality and advanced + evaluations to the the page tree filter. + +The PSR-14 :php:`\TYPO3\CMS\Backend\Tree\Repository\BeforePageTreeIsFilteredEvent` +allows developers to extend the page trees filter's functionality and process the +given search phrase in more advanced ways. + +The page tree is one of the central components in the TYPO3 backend, +particularly for editors. However, in large installations, the page tree can +quickly become overwhelming and difficult to navigate. To maintain a clear +overview, the page tree can be filtered using basic terms, such as the page +title or ID. + +.. _BeforePageTreeIsFilteredEvent-example: + +Example: Add evaluation of document types to the page tree search filter +======================================================================== + +The event listener class, using the PHP attribute :php:`#[AsEventListener]` for +registration, adds additional conditions to the filter. + +.. literalinclude:: _BeforePageTreeIsFilteredEvent/_MyEventListener.php + :caption: EXT:my_extension/Classes/Backend/EventListener/MyEventListener.php + +.. _BeforePageTreeIsFilteredEvent-api: + +BeforePageTreeIsFilteredEvent API +================================= + +The event provides the following member properties: + +`$searchParts`: + The search parts to be used for filtering +`$searchUids`: + The uids to be used for filtering by a special search part, which + is added by Core always after listener evaluation +`$searchPhrase` + The complete search phrase, as entered by the user +`$queryBuilder`: + The current :php-short:`\TYPO3\CMS\Core\Database\Query\QueryBuilder` + +.. important:: + + The :php-short:`\TYPO3\CMS\Core\Database\Query\QueryBuilder` instance is provided solely + for context and to simplify the creation of + search parts by using the :php-short:`\TYPO3\CMS\Core\Database\Query\Expression\ExpressionBuilder` + via :php:`QueryBuilder->expr()`. The instance itself **must not** be modified by listeners and + is not considered part of the public API. TYPO3 reserves the right to change the instance at + any time without prior notice. + +.. include:: /CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt diff --git a/Documentation/ApiOverview/Events/Events/Backend/_BeforePageTreeIsFilteredEvent/_MyEventListener.php b/Documentation/ApiOverview/Events/Events/Backend/_BeforePageTreeIsFilteredEvent/_MyEventListener.php new file mode 100644 index 000000000..9f05b1a2a --- /dev/null +++ b/Documentation/ApiOverview/Events/Events/Backend/_BeforePageTreeIsFilteredEvent/_MyEventListener.php @@ -0,0 +1,30 @@ +searchUids[] = 123; + + // Adds evaluation of doktypes to the filter + if (preg_match('/doktype:([0-9]+)/i', $event->searchPhrase, $match)) { + $doktype = $match[1]; + $event->searchParts = $event->searchParts->with( + $event->queryBuilder->expr()->eq( + 'doktype', + $event->queryBuilder->createNamedParameter($doktype, Connection::PARAM_INT), + ), + ); + } + } +} diff --git a/Documentation/CodeSnippets/Config/Api/Events/EventsBackend.php b/Documentation/CodeSnippets/Config/Api/Events/EventsBackend.php index 14d9515b1..7583f0f8e 100644 --- a/Documentation/CodeSnippets/Config/Api/Events/EventsBackend.php +++ b/Documentation/CodeSnippets/Config/Api/Events/EventsBackend.php @@ -279,4 +279,10 @@ 'targetFileName' => 'CodeSnippets/Events/Backend/PasswordHasBeenResetEvent.rst.txt', 'withCode' => false, ], + [ + 'action' => 'createPhpClassDocs', + 'class' => \TYPO3\CMS\Backend\Tree\Repository\BeforePageTreeIsFilteredEvent::class, + 'targetFileName' => 'CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt', + 'withCode' => false, + ], ]; diff --git a/Documentation/CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt b/Documentation/CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt new file mode 100644 index 000000000..f9bb40b30 --- /dev/null +++ b/Documentation/CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt @@ -0,0 +1,20 @@ +.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets +.. php:namespace:: TYPO3\CMS\Backend\Tree\Repository + +.. php:class:: BeforePageTreeIsFilteredEvent + + Listeners to this event will be able to modify the search parts, to be used to filter the page tree + + .. php:attr:: searchParts + :public: + + .. php:attr:: searchUids + :public: + + .. php:attr:: searchPhrase + :readonly: + :public: + + .. php:attr:: queryBuilder + :readonly: + :public: