Skip to main content

Dashboards Developer Guide

This module adds the following resources:

  • Dashboards
  • Screens
  • Themes

Installation​

To install this module:​

This module uses the Pinia Store library for store management, make sure to install it See documentation.

composer require qore/dashboards

You can install all the necessary files, database tables and configurations with the following command:

php artisan qore:dashboards:install
warning

The module saves you a lot of time with this auto installer, but you have to do one more thing manually:

In the router/routes.js you have to add 2 lines of code:

import { middleware } from 'vue-router-middleware'

import qoreRoutes from 'qore/routes'
import { dashboardsModuleRoutes } from 'vendor/dashboards/routes' // Add this line
  {
    path: '*',
    component: () => import('pages/error/Error404.vue')
  },

  ...dashboardsModuleRoutes // Add this line

And now your module is installed!

Validate installation​

If you want to validate your installation you can run the following command:

php artisan qore:dashboards:validate

User Dashboards​

User dashboards are dashboards that can be created by the users of the application. Users have the option to create dashboards in a drag and drop interface.

For more information about the user dashboards check the User Dashboards documentation.

Developer Dashboards​

Creating a dashboard​

The dashboards is built to make it easy to create dashboards for your users and developers.

Developers can use a simple command to create a new dashboard:

php artisan qore:dashboards:create

After running this command you will be asked for the name of the dashboard and if you want to add the dashboard automatically to the menu.

When the command is finished the new Dashboard will be available in the dashboard list and can be found in the App/Dashboards/DeveloperDashboards folder.

note

Dashboards will be registered automatically by Qore when they are placed in the App/Dashboards/DeveloperDashboards folder.

Adding content to a dashboard​

To add content to a dashboard you can use the content() method in the Dashboard class.

The make() method will return a new instance of the DeveloperDashboardBuilder class.

public function content(): DeveloperDashboardBuilder
{
    return $this->make();
}

To add a row to the dashboard you can call the row() method on the $this->make() method. The row method accepts an array of widgets.

public function content(): DeveloperDashboardBuilder
{
    return $this->make()
        ->row([]);
}

To add a widget to the row you can use a widget that extends the BaseCard class

public function content(): DeveloperDashboardBuilder
{
    return $this->make()
        ->row([
           (new iFrameComponent('https://nl.wikipedia.org/wiki/Software')),
        ]);
}
info

By default the Dashboards module comes with a few basic widgets that can be used. If you want to create your own widget check the Widgets documentation.

Styling a dashboard​

You have multiple options to style a dashboard:

For a widget you have the following options:

Width​

You can set the width of a widget by using the ->setWidth() method on the widget. A width can be a number between 1 and 12:

->row([
    (new iFrameComponent('...'))->setWidth(6),
    (new iFrameComponent('...'))->setWidth(6),
]);
warning

The sum of the width of the widgets in a row should not exceed 12. Otherwise the layout will break.

Classes​

You can add classes to a widget by using the ->setClasses() method on the widget:

->row([
    (new iFrameComponent('...'))->setClasses('bg-blue-500 text-white'),
]);

Styling​

You can add inline styling to a widget by using the ->setStyling() method on the widget:

->row([
    (new iFrameComponent('...'))->setStyling('background-color: blue; color: white;'),
]);

Dashboard visibility​

Developer dashboards can be used by other users in the application to create their own dashboards.

Show in menu​

Developer dashboards can also be used in the menu of the application.

Show in index dropdown​

By default only the dashboards created in the resource can be used in the dashboard index dropdown. But developer dashboards can also placed directly in the dropdown list, by this you don't have to create a resource for the dashboard before you can use it in the dropdown.

Add the following property to the dashboard class:

public bool $showInIndexDropdown = true;

Hide from dashboard creating​

If you don't want to give a user the option to create a dashboard resource from the developer dashboard you can hide it by adding the following property:

public bool $hideFromDashboardCreating = true;

Show global filters​

If you want to show the global filters where you can adjust the time period of the dashboard you can add the following property:

public bool $show_global_filters = true;
note

Filters will only apply on metric widgets

Permissions​

Developer dashboards can only be seen by users who has the view developer dashboards in menu permission.

But if you want to add more permissions to a dashboard you can do this by adding the following method to your dashboard class:

public function addPermission(): array
{
    return [
        'user can view invoicing data',
        'user can view sales data',
    ];
}

Widgets​

Widgets are the building blocks of a dashboard. By default the Dashboards module comes with a few widgets that can be used in a dashboard:

Using a widget​

To use a widget you can create a new instance of the widget and add it to the row of the dashboard.

Creating a widget​

Create​

To create a new widget you can run the following command:

php artisan qore:dashboards:create:widget

This will create a class in the App/Dashboards/Widgets folder.

Customize​

A widget contains the following methods & properties:

Giving a name to the widget​
public function name(): string
{
    return 'My First Widget';
}
Setting the options​

Every widget has a set of options you can define your own by adding those to the constructor of the widget:

// Example of a source option for an iFrame widget
public function __construct(string $source = '')
{
    $this->options['source'] = $source;
}

All of the options will be sent to the view of the widget.

warning

Pay attention that the parameters of the source are optional, this is because the widget will also be used in the user dashboard builder where the options also can be set.

Using the options in the view​

First you have to retrieve the options as props:

import { defineProps } from 'vue'

const { options } = defineProps({
  options: Object
})

Then you can use the options like this:

<iframe :src="options?.source"></iframe>

Properties for user dashboard builder​

If you want to give the user the possibility to change fields of your widget you have to define properties.

Defining properties​

You can define properties for a widget by adding the following method to the widget class:

public function props(): PropertiesCollection
{
    return new PropertiesCollection([
        TextProperty::make('source', 'Source'),
    ]);
}

in here you can define multiple properties for the widget. The first parameter is the name of the property and the second parameter is the label of the property.

warning

The name of the property has to match the name of the property in the options array otherwise it doesn't know which property to change.

Available properties​

There are a few properties available to use in a widget. Some widgets have extra options to use. They can be called on the Property class:

TextProperty::make('content', 'Content')->wysiwyg()

TextProperty​

Where users can fill in a text field

Extra options:

  • ->wysiwyg() - Makes the text field a wysiwyg editor
SelectProperty​

Where users can select an option from a list

Extra options:

  • ->options({options}) - The options that can be selected from the list.
info

The options array should be an associative array where the key is the value that will be saved and the value is the label that will be shown in the dropdown.

public function props(): PropertiesCollection
{
    return new PropertiesCollection([
        SelectProperty::make('metric', 'Metric')
            ->options($this->makeOptions()),
    ]);
}

private function makeOptions(): array
{
    return metrics()->all()->map(function ($metric) {
        return [
            'value' => $metric->name(),
            'label' => $metric->title(),
        ];
    })->toArray();
}

List of widgets​

iFrame​

(new iFrameComponent({source}))

Text​

(new TextComponent({text}))

Image​

(new ImageComponent({source}))

Metrics​

The Qore Dashboards module can be expanded with the Qore Metrics module to have the possibility to show metrics in the dashboards. Those metrics has to be registered before they can be used.

For more info about the Qore Metrics module check the Metrics documentation.

Metric​

(new ExampleMetric())

Adding to menu​

You can add dashboards to your menu so users can easily navigate to it. You can do this by two ways:

Automatically​

php artisan qore:dashboards:menu:add {the name of your dashboards class}
warning

This method will edit content in the GlobalsController.php file. It's recommended to make a backup of this file before running this command. Dashboards are added on top of the menu by default, you are free to change this.

You can validate your menu by running the following command:

php artisan qore:dashboards:validate
info

When using the command to create a dashboard:

php artisan qore:dashboards:create:dashboard

you will asked if you want to add the dashboard to the menu.

Manually​

You can add a dashboard to the menu by adding the following code to the GlobalsController.php file:

$tab->addMenuableItem(new MyNewDashboard(), function (MenuItem $item) {
    $item->setIcon('home'); // <-- Overides the default icon of the dashboard
});