TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,101 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-103211-1709036591:
+
+=============================================
+Feature: #103211 - Introduce tree node labels
+=============================================
+
+See :issue:`103211`
+
+Description
+===========
+
+We've upgraded the backend tree component by extending tree nodes to
+incorporate labels, offering enhanced functionality and additional
+information.
+
+Before the implementation of labels, developers and integrators
+relied on :typoscript:`pageTree.backgroundColor.<pageid>` for visual cues,
+which has been :ref:`deprecated <deprecation-103211-1709038752>` with TYPO3 v13.
+However, these background colors lacked accessibility and meaningful context,
+catering only to users with perfect eyesight and excluding those
+dependent on screen readers or contrast modes.
+
+With labels, we now cater to all editors. These labels not only offer
+customizable color markings for tree nodes but also require an
+associated label for improved accessibility.
+
+Each node can support multiple labels, sorted by priority, with the
+highest priority label taking precedence over others. Users can
+assign a label to a node via user TSconfig, noting that only one label
+can be set through this method.
+
+..  code-block:: typoscript
+    :caption: EXT:my_extension/Configuration/user.tsconfig
+
+    options.pageTree.label.<pageid> {
+        label = Campaign A
+        color = #ff8700
+    }
+
+Labels also support locallang keys:
+
+..  code-block:: typoscript
+    :caption: EXT:my_extension/Configuration/user.tsconfig
+
+    options.pageTree.label.<pageid> {
+        label = LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:labels.pageTree.campaign
+        color = #ff8700
+    }
+
+The labels can also be added by using the event
+:php:`\TYPO3\CMS\Backend\Controller\Event\AfterPageTreeItemsPreparedEvent`.
+
+..  code-block:: php
+    :caption: EXT:my_extension/Classes/Backend/EventListener/ModifyPageTreeItems.php
+    :emphasize-lines: 22-26
+
+    <?php
+
+    declare(strict_types=1);
+
+    namespace MyVendor\MyExtension\Backend\EventListener;
+
+    use TYPO3\CMS\Backend\Controller\Event\AfterPageTreeItemsPreparedEvent;
+    use TYPO3\CMS\Backend\Dto\Tree\Label\Label;
+    use TYPO3\CMS\Core\Attribute\AsEventListener;
+
+    #[AsEventListener(
+        identifier: 'my-extension/backend/modify-page-tree-items',
+    )]
+    final readonly class ModifyPageTreeItems
+    {
+        public function __invoke(AfterPageTreeItemsPreparedEvent $event): void
+        {
+            $items = $event->getItems();
+            foreach ($items as &$item) {
+                // Add special label for all pages with parent page ID 123
+                if (($item['_page']['pid'] ?? null) === 123) {
+                    $item['labels'][] = new Label(
+                        label: 'Campaign B',
+                        color: '#00658f',
+                        priority: 1,
+                    );
+                }
+            }
+            $event->setItems($items);
+        }
+    }
+
+Please note that only the marker for the label with the highest priority is
+rendered. All additional labels will only be added to the title of the node.
+
+
+Impact
+======
+
+Labels are now added to the node and their children, significantly
+improving the clarity and accessibility of the tree component.
+
+.. index:: Backend, JavaScript, TSConfig, ext:backend