Tutorial: Extending the QUIQQER Dashboard by yourself

In the next weeks release 1.3 of QUIQQER is planned and this release also includes the new Dashboard. Today we show you how to extend the dashboard with your own cards even as a hard-working developer.

Repository

• https://github.com/QUIQQER/dashboard

What Will I Learn?

• Creating a card for the dashboard
• Add a card to the dashboard

Requirements

• A QUIQQER System
• Your own QUIQQER Module
• Some PHP, HTML, JavaScript experience
• AMD JavaScript knowledge

Difficulty

• Advanced

Tutorial Contents

Creating a card for the dashboard

General

Dashboard-Cards are basically JavaScript controls that extend the Card-JavaScript-Control (package/quiqqer/dashboard/bin/backend/controls/Card).

define('package/mygroup/mypackage/bin/MyCard', [
    'package/quiqqer/dashboard/bin/backend/controls/Card',
], function (QUICard) {
    "use strict";

    return new Class({
        Extends: QUICard,
        Type   : 'package/quiqqer/dashboard/bin/backend/controls/cards/BlogEntry',
    });
});

Basic skeleton for a Dashboard-Card

Attributes

Every Card has the following attributes:

• id: The card's (HTML-)ID
• icon: The icon to display in the top left corner
• title: The title at the top of the card
• content: The card's HTML-content
• footer: The footer in HTML-format at the bottom of the card
• styles: The card's CSS style
• size: The card's width in percent (10, 16, 20, 25, 30, 33, 40, 50, 60, 70, 80, 90 or 100)

These attributes can be overwritten in the initialize method:

initialize: function (options) {
    this.parent(options);

    this.setAttributes({
        id     : 'my-dashboard-card',
        icon   : 'fa fa-rocket',
        title  : 'My First Dashboard Card'
        content: '<h1>Hello World!</h1>',
        footer : 'This is an interesting footer'
        size   : 25,
    });
},

Setting attributes in the initialize-method

To access these attributes there are certain methods. Check the Card-JavaScript-Control to see all of them.

Displaying Content

To display your card's content you have to overwrite the refresh-method of the card-control.
There for example you're able to call Ajax-methods to query further content, add buttons, etc.:

refresh: function () {
    var self = this;
    QUIAjax.get('package_mygroup_mypackage_ajax_myajaxfunction', function (result) {
        self.setContent(result);

        self.getElm().addEvent('click', function () {
            console.log('You clicked my card!');
        });
    }, {
        'package': 'mygroup/mypackage',
        onError  : console.error
    });
}

Overwriting the refresh-method

Add a card to the dashboard

Now that we have our first card, we have to make it available.

Creating a Dashboard-Provider

To create a Dashboard-Provider you need to create a PHP-class that implements the DashboardProvider-Interface (QUI\Ḑashboard\DashboardProviderInterface):

class MyDashboardProvider implements QUI\Ḑashboard\DashboardProviderInterface {}

Class implementing the DashboardProvider-Interface

The interface requires you to overwrite the getCards-method. This method has to return an array containing strings or sub-arrays of strings.
These strings are the names of the JavaScript-Card-controls that should be added to the dashboard. If a sub-array of strings is returned it represents a complete row, which no other cards will be added to.

class MyDashboardProvider implements QUI\Ḑashboard\DashboardProviderInterface {
    public static function getCards()
    {
        return [
            'package/mygroup/mypackage/bin/MyFirstCard',
            [                
                'package/mygroup/mypackage/bin/Row1/FirstCardInRow1',
                'package/mygroup/mypackage/bin/Row2/SecondsCardInRow1',
            ]
        ];
    }
}

Examplary getCards()-method

Registering the Dashboard-Provider

To have the Dashboard use your Dashboard-Provider you need to register it. This is done by adding your Provider-Class to your package's package.xml:

<provider>
    <dashboard src="\My\Dashboard\Provider"/>
</provider>

Registering the Dashboard-Provider via package.xml

After running the setup once, your Card is now displayed in the dashboard, yay!

Proof of Work Done

Good examples of how to create cards can be found in the dashboard itself:

• https://github.com/QUIQQER/dashboard/tree/master/bin/backend/controls/cards
• https://github.com/QUIQQER/dashboard/blob/master/src/QUI/Dashboard/DashboardProvider.php

We hope we could bring you a little closer to you how you can extend the new dashboard with your module.
We wish you a lot of fun with QUIQQER

Thanks for reading,
Hen and Jan, for PCSG Developers