Implement new widget

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 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.

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;
    }
}
Copied!

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.

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.

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'
Copied!

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:

RequireJS AMD module

Implement \TYPO3\CMS\Dashboard\Widgets\RequireJsModuleInterface :

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

Implement \TYPO3\CMS\Dashboard\Widgets\AdditionalJavaScriptInterface :

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

Both ways can also be combined.

Providing custom CSS

It is possible to add custom Css to style widgets.

Implement \TYPO3\CMS\Dashboard\Widgets\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',
         ];
      }
}
Copied!