TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:14 +02:00
commit ff4622ba97
138 changed files with 9045 additions and 0 deletions
@@ -0,0 +1,195 @@
+.. include:: /Includes.rst.txt
+
+..  _implement-new-widget:
+
+====================
+Implement new widget
+====================
+
+..  versionadded:: 14.0
+    `Configurable Dashboard Widgets <https://docs.typo3.org/permalink/changelog:feature-107036-1738837673>`_
+    have been introduced with TYPO3 14.0.
+
+    See also
+
+.. php:namespace:: TYPO3\CMS\Dashboard\Widgets
+
+.. seealso::
+
+   For information regarding registration of widgets, see: :ref:`register-new-widget`.
+   This section describes the implementation of new widgets for developers.
+
+Each extension can provide multiple Widgets.
+ext:dashboard already ships with some widget implementations.
+
+Each widget has to be implemented as a PHP class.
+The PHP class defines the concrete implementation and features of a widget,
+while registration adds necessary options for a concrete instance of a widget.
+
+For example a TYPO3.org RSS Widget would consist of an :php:`RssWidget` PHP class.
+This class would provide the implementation to fetch rss news and display them.
+The concrete registration will provide the URL to RSS feed.
+
+..  _widget-php-class:
+
+PHP class
+---------
+
+Each Widget has to be a PHP class.
+This class has to implement the :php:`WidgetInterface` and could look like this:
+
+..  code-block:: php
+
+    class RssWidget implements WidgetInterface, RequestAwareWidgetInterface
+    {
+        private ServerRequestInterface $request;
+
+        public function __construct(
+            private readonly WidgetConfigurationInterface $configuration,
+            private readonly Cache $cache,
+            private readonly BackendViewFactory $backendViewFactory,
+            private readonly ?ButtonProviderInterface $buttonProvider = null,
+            private readonly array $options = []
+        ) {
+        }
+
+        public function setRequest(ServerRequestInterface $request): void
+        {
+            $this->request = $request;
+        }
+
+        public function renderWidgetContent(): string
+        {
+            $view = $this->backendViewFactory->create($this->request);
+            $view->assignMultiple([
+                'items' => $this->getRssItems(),
+                'options' => $this->options,
+                'button' => $this->getButton(),
+                'configuration' => $this->configuration,
+            ]);
+            return $view->render('Widget/RssWidget');
+        }
+
+        protected function getRssItems(): array
+        {
+            $items = [];
+            // Logic to populate $items array
+            return $items;
+        }
+
+        public function getOptions(): array
+        {
+            return $this->options;
+        }
+    }
+
+The class should always provide documentation how to use in :file:`Services.yaml`.
+The above class is documented at :ref:`rss-widget`.
+The documentation should provide all possible options and an concrete example.
+It should make it possible for integrators to register new widgets using the implementation.
+
+The difference between :php:`$options` and :php:`$configuration` in above example is the following:
+:php:`$options` are the options for this implementation which can be provided through :file:`Services.yaml`.
+:php:`$configuration` is an instance of :php:`WidgetConfigurationInterface`
+holding all internal configuration, like icon identifier.
+
+..  _implement-new-widget-fluid:
+
+Using Fluid
+-----------
+
+Most widgets will need a template.
+Therefore each widget can define :php:`BackendViewFactory` as requirement for DI in
+constructor, like done in RSS example.
+
+
+..  _implement-new-widget-custom-js:
+
+Providing custom JS
+-------------------
+
+There are two ways to add JavaScript for an widget:
+
+JavaScript module
+    Implement :php:`\TYPO3\CMS\Dashboard\Widgets\JavaScriptInterface`:
+
+    ..  code-block:: php
+
+
+        class ExampleChartWidget implements JavaScriptInterface
+        {
+            // ...
+            public function getJavaScriptModuleInstructions(): array
+            {
+                return [
+                    JavaScriptModuleInstruction::create(
+                        '@myvendor/my-extension/module-name.js'
+                    )->invoke('initialize'),
+                    JavaScriptModuleInstruction::create(
+                        '@myvendor/my-extension/module-name2.js'
+                    )->invoke('initialize'),
+                ];
+            }
+        }
+
+    ..  seealso::
+
+        :ref:`t3coreapi:backend-javascript-es6` for more info about JavaScript in TYPO3 Backend.
+
+Plain JS files
+    Implement :php:`AdditionalJavaScriptInterface`:
+
+    .. code-block:: php
+
+       class RssWidget implements WidgetInterface, AdditionalJavaScriptInterface
+       {
+           public function getJsFiles(): array
+           {
+               return [
+                   'EXT:my_extension/Resources/Public/JavaScript/file.js',
+                   'EXT:my_extension/Resources/Public/JavaScript/file2.js',
+               ];
+           }
+       }
+
+JavaScript
+    Implement :php:`\TYPO3\CMS\Dashboard\Widgets\JavaScriptInterface`:
+
+    .. code-block:: php
+
+        class ExampleChartWidget implements JavaScriptInterface
+        {
+            // ...
+            public function getJavaScriptModuleInstructions(): array
+            {
+                return [
+                    JavaScriptModuleInstruction::create(
+                        '@typo3/dashboard/chart-initializer.js'
+                    )->invoke('initialize'),
+                ];
+            }
+        }
+
+All ways can be combined.
+
+..  _custom-css:
+
+Providing custom CSS
+--------------------
+
+It is possible to add custom Css to style widgets.
+
+Implement :php:`AdditionalCssInterface`:
+
+..  code-block:: php
+
+    class RssWidget implements WidgetInterface, AdditionalCssInterface
+    {
+          public function getCssFiles(): array
+          {
+             return [
+                 'EXT:my_extension/Resources/Public/Css/widgets.css',
+                 'EXT:my_extension/Resources/Public/Css/list-widget.css',
+             ];
+          }
+    }