Merge pull request #427 from WoltLab/acp-dashboard-boxes

Document admin dashboard boxes

docs/php/api/acp_dashboard_boxes.md

@@ -0,0 +1,55 @@
+# ACP Dashboard Boxes
+
+ACP Dashboard Boxes are displayed on the landing page of the admin panel and can provide the user with useful information. A box consists of an internal identifier, a name and the content of the box. The content can contain HTML code.
+
+## Create a Custom Box
+
+A custom box can be created with a custom PHP class that needs to implement the [`wcf\system\acp\dashboard\box\IAcpDashboardBox`](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/acp/dashboard/box/IAcpDashboardBox.class.php) interface.
+It is recommended to extend the class [`wcf\system\acp\dashboard\box\AbstractAcpDashboardBox`](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/acp/dashboard/box/AbstractAcpDashboardBox.class.php), which already provides a basic implementation of the interface.
+
+Example:
+
+```php
+<?php
+namespace wcf\system\acp\dashboard\box;
+
+use wcf\system\event\EventHandler;
+use wcf\system\acp\dashboard\event\AcpDashboardCollecting;
+
+final class FooBox extends AbstractAcpDashboardBox {
+    public function getTitle(): string
+    {
+        return 'title of the box';
+    }
+
+    public function getContent(): string
+    {
+        return 'content of the box';
+    }
+
+    public function getName(): string
+    {
+        return 'com.foo.bar'; // identifier of the box; must be unique
+    }
+}
+```
+
+## Register a Custom Box
+
+You can attach an event listener to the `wcf\system\acp\dashboard\event\AcpDashboardCollecting` event inside a bootstrap script to lazily register custom boxes.
+The class name of the box is registered using the event’s `register()` method:
+
+```php title="files/lib/bootstrap/com.example.bar.php"
+<?php
+
+use wcf\system\event\EventHandler;
+use wcf\system\acp\dashboard\event\AcpDashboardCollecting;
+
+return static function (): void {
+    $eventHandler = EventHandler::getInstance();
+
+    $eventHandler->register(AcpDashboardCollecting::class, static function (AcpDashboardCollecting $event) {
+        $event->register(\wcf\system\acp\dashboard\box\FooBox::class);
+    });
+};
+```

mkdocs.yml

@@ -24,6 +24,7 @@ nav:
       - 'Database Access': 'php/database-access.md'
       - 'Exceptions': 'php/exceptions.md'
       - 'API':
+          - 'ACP Dashboard Boxes': 'php/api/acp_dashboard_boxes.md'
           - 'Caches':
               - 'Overview': 'php/api/caches.md'
               - 'Persistent Caches': 'php/api/caches_persistent-caches.md'