nextcloud-docs/developer_manual/digging_deeper/dashboard.rst

=========
Dashboard
=========

The dashboard app aims to provide the user with a general overview of their
Nextcloud and shows information that is currently important.

App developers can integrate into the dashboard app and provide their own widgets.


Register a dashboard widget
---------------------------

A dashboard widget is represented by a class implementing the `OCP\\Dashboard\\IWidget`
interface. This class will be instantiated whenever the dashboard is loaded.
Any bootstrap code that is needed for the widget can be implemented inside
of the `load` method and will be called when the dashboard is loaded.

.. code-block:: php

    <?php

    namespace OCA\MyApp\Dashboard;

    use OCP\Dashboard\IWidget;
    use OCP\IInitialStateService;
    use OCP\IL10N;
    use OCP\IURLGenerator;
    use OCP\IUserSession;

    class MyAppWidget implements IWidget {

        public function __construct(
            IInitialStateService $initialStateService,
            IL10N $l10n,
            IURLGenerator $urlGenerator
        ) {
            $this->initialStateService = $initialStateService;
            $this->l10n = $l10n;
            $this->urlGenerator = $urlGenerator;
        }

        /**
         * @return string Unique id that identifies the widget, e.g. the app id
         * @since 20.0.0
         */
        public function getId(): string {
            return 'myappwidgetid';
        }

        /**
         * @return string User facing title of the widget
         * @since 20.0.0
         */
        public function getTitle(): string {
            return $this->l10n->t('My app');
        }

        /**
         * @return int Initial order for widget sorting
         *   in the range of 10-100, 0-9 are reserved for shipped apps
         * @since 20.0.0
         */
        public function getOrder(): int {
            return 0;
        }

        /**
         * @return string css class that displays an icon next to the widget title
         * @since 20.0.0
         */
        public function getIconClass(): string {
            return 'icon-class';
        }

        /**
         * @return string|null The absolute url to the apps own view
         * @since 20.0.0
         */
        public function getUrl(): ?string {
            return $this->urlGenerator->linkToRouteAbsolute('myapp.view.index');
        }

        /**
         * Execute widget bootstrap code like loading scripts and providing initial state
         */
        public function load(): void {
            $initialStateService->provideInitialState('myapp', 'myData', []);
            \OCP\Util::addScript('myapp', 'dashboard');
        }
    }


The class needs to be registered during the :ref:`app bootstrap<Bootstrapping>`.

.. code-block:: php

    <?php

    declare(strict_types=1);

    namespace OCA\MyApp\AppInfo;

    use OCP\AppFramework\App;
    use OCP\AppFramework\Bootstrap\IBootContext;
    use OCP\AppFramework\Bootstrap\IBootstrap;
    use OCP\AppFramework\Bootstrap\IRegistrationContext;
    use OCA\MyApp\Dashboard\MyAppWidget;

    class Application extends App implements IBootstrap {

        public const APP_ID = 'myapp';

        public function __construct(array $urlParams = []) {
            parent::__construct(self::APP_ID, $urlParams);
        }

        public function register(IRegistrationContext $context): void {
            $context->registerDashboardWidget(MyAppWidget::class);
        }

        public function boot(IBootContext $context): void {
        }
    }

For compatibility reasons the widget registration can also be performed by
listening to the `OCP\\Dashboard\\RegisterWidgetEvent` for apps that still
need to support older versions where the new app boostrap flow is not available,
however this method is deprecated and will be removed once Nextcloud 19 is EOL.

.. code-block:: php

    use OCP\Dashboard\RegisterWidgetEvent;
    use OCP\EventDispatcher\IEventDispatcher;

    class Application extends App {
        public function __construct(array $urlParams = []) {
            parent::__construct(self::APP_ID, $urlParams);
            $container = $this->getContainer();

            /** @var IEventDispatcher $dispatcher */
            $dispatcher = $container->getServer()->query(IEventDispatcher::class);
            $dispatcher->addListener(RegisterWidgetEvent::class, function (RegisterWidgetEvent $event) use ($container) {
                    \OCP\Util::addScript('myapp', 'dashboard');
                    $event->registerWidget(MyAppWidget::class);
            });
        }
    }


Provide a user interface
------------------------

The user interface can be registered through the public `OCA.Dashboard.register`
JavaScript method. The first parameter represents the widget id that has already
been specified in the `IWidget` implementation. The callback parameter will be
called to render the widget in the frontend. The user interface can be added to
the provided DOM element `el`.

The following example shows how a Vue.js component could be used to render the
widget user interface, however this approach works for any other framework as well
as plain JavaScript:


.. code-block:: javascript

    import Dashboard from './components/Dashboard.vue'

    document.addEventListener('DOMContentLoaded', () => {
        OCA.Dashboard.register('myappwidgetid', (el) => {
            const View = Vue.extend(Dashboard)
            const vm = new View({
                propsData: {},
                store,
            }).$mount(el)
        })
    })