Implement new widget¶

PHP class¶

Each Widget has to be a PHP class. This class has to implement the WidgetInterface and could look like this:

class RssWidget implements WidgetInterface
{
    /**
     * @var WidgetConfigurationInterface
     */
    private $configuration;

    /**
     * @var StandaloneView
     */
    private $view;

    /**
     * @var Cache
     */
    private $cache;

    /**
     * @var array
     */
    private $options;

    /**
     * @var ButtonProviderInterface|null
     */
    private $buttonProvider;

    public function __construct(
        WidgetConfigurationInterface $configuration,
        Cache $cache,
        StandaloneView $view,
        ButtonProviderInterface $buttonProvider = null,
        array $options = []
    ) {
        $this->configuration = $configuration;
        $this->view = $view;
        $this->cache = $cache;
        $this->options = [
            'limit' => 5,
        ] + $options;
        $this->buttonProvider = $buttonProvider;
    }

    public function renderWidgetContent(): string
    {
        $this->view->setTemplate('Widget/RssWidget');
        $this->view->assignMultiple([
            'items' => $this->getRssItems(),
            'options' => $this->options,
            'button' => $this->getButton(),
            'configuration' => $this->configuration,
        ]);
        return $this->view->render();
    }

    protected function getRssItems(): array
    {
        $items = [];

        // Logic to populate $items array

        return $items;
    }
}

The class should always provide documentation how to use in Services.yaml. The above class is documented at 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.

<<<<<<< HEAD (a598d0 [TASK] Allow execution of acceptance tests with local chrome) The difference between $options and $configuration in above example is the following: $options are the options for this implementation which can be provided through Services.yaml. $configuration is an instance of holding all internal configuration, like icon identifier. ======= The difference between $options and $configuration in above example is the following: $options are the options for this implementation which can be provided through Services.yaml. $configuration is an instance of WidgetConfigurationInterface holding all internal configuration, like icon identifier. >>>>>>> CHANGE (1bf527 [DOCS] Switch Dashboard documentation to PHP-based rendering)

Using Fluid¶

Most widgets will need a template. Therefore each widget can define StandaloneView as requirement for DI in constructor, like done in RSS example. In order to provide a common configured instance to all widgets, the following service can be used in Services.yaml to provide the instance:

dashboard.widget.t3news:
  class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
  arguments:
    $view: '@dashboard.views.widget'

The instance will be pre configured with paths, see Adjust template of widgets, and can be used as shown in RSS widget example above.

Providing custom JS¶

There are two ways to add JavaScript for an widget:

<<<<<<< HEAD (a598d0 [TASK] Allow execution of acceptance tests with local chrome) RequireJS AMD module Implement :: ======= JavaScript module Implement \TYPO3\CMS\Dashboard\Widgets\JavaScriptInterface: >>>>>>> CHANGE (1bf527 [DOCS] Switch Dashboard documentation to PHP-based rendering)

class RssWidget implements WidgetInterface, RequireJsModuleInterface { public function getRequireJsModules(): array { return [ 'TYPO3/CMS/MyExtension/ModuleName', 'TYPO3/CMS/MyExtension/Module2Name', ]; } }

.. seealso:

:ref:`t3coreapi:requirejs` for more info about RequireJS in TYPO3 Backend.

Plain JS files <<<<<<< HEAD (a598d0 [TASK] Allow execution of acceptance tests with local chrome) Implement :: ======= Implement AdditionalJavaScriptInterface: >>>>>>> CHANGE (1bf527 [DOCS] Switch Dashboard documentation to PHP-based rendering)

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', ]; } }

<<<<<<< HEAD (a598d0 [TASK] Allow execution of acceptance tests with local chrome) Both ways can also be combined. ======= 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 \TYPO3\CMS\Dashboard\Widgets\JavaScriptInterface:

class ExampleChartWidget implements JavaScriptInterface
{
    // ...
    public function getJavaScriptModuleInstructions(): array
    {
        return [
            JavaScriptModuleInstruction::create(
                '@typo3/dashboard/chart-initializer.js'
            )->invoke('initialize'),
        ];
    }
}

Copied!

All ways can be combined.

>>>>>>> CHANGE (1bf527 [DOCS] Switch Dashboard documentation to PHP-based rendering)

Providing custom CSS¶

It is possible to add custom Css to style widgets.

Implement AdditionalCssInterface:

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',
         ];
      }
}