Dashboard

Overview #

Dashboard is a group of similar information organized in a page. We normally adds Dashboard into Application like following:

class App extends Application
{
    ...
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale"=>HomeBoard::create(),
        ];
    }
    ...
}

Properties #

Nametypedefaultdescription
defaultbooleanfalseWhether dashboard is default
titlestringTitle of dashboard, which will appear in the menu
hiddenbooleanfalseWhether the dashboard is hidden, could not access from menu
iconstringThe icon of dashboard
badgestring/arrayAdd badge to menu
updateEffectstring"fade"Visual effect when dashboard is updated, whether "fade" or "none"

Note: Those above properties following this code rules.

You can set those properties for dashboard from Application

<?php
//App.php
class App extends Application
{
    ...
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create()
                    ->default(true)
                    ->title("Home")
                    ->hidden(false)
                    ->icon("fa fa-home")
                    ->badge("NEW") // Or full version ->badge(["NEW","danger"])
                    ->updateEffect("fade")
        ];
    }
    ...
}

or inside Dashboard class

<?php
//HomeBoard.php
use \koolreport\dashboard\Dashboard;

class HomeBoard extends Dashboard
{
    protected function onInit()
    {
        $this->default(true)
            ->title("Home")
            ->hidden(false)
            ->icon("fa fa-home")
            ->updateEffect("fade");
    }
}

Methods #

Nametypedescription
widget($name)WidgetReturn widget inside dashboard by its widget's name
update()Ask a dashboard to update/refresh

Traits #

Dashboard has been provided with following traits:

  1. TAppLink: Able to refer to application with app() method
  2. TEnabledPermit: Use enabled() and enabledWhen() to set permission
  3. TParams: Able to get/set parameters with params() method

Widget listing #

Basic #

Basically, we need to provide list of widgets inside widgets() method of dashboard

use \koolreport\dashboard\Dashboard;

class SaleBoard extends Dashboard
{
    protected function widgets()
    {
        return [
            WeekSaleChart::create(),
            MonthSaleChart::create(),
            DetailSaleTable::create()
        ];
    }
}

Learn more about Widget

Advanced layouts #

With above basic layout above, we would like to show you the basic concept of adding widgets into a dashboard. For better layout of widgets within dashboard, we should look at Container Widgets. The Container Widgets help to organize widgets. There are 3 most-used containers: Row, Panel and Tabs.

Row #

Row layouts sub widgets in a row, one will be put next to another.

use \koolreport\dashboard\Dashboard;
use \koolreport\dashboard\containers\Row;

class SaleBoard extends Dashboard
{
    protected function widgets()
    {
        return [
            Row::create()->sub([
                SaleValueMetric::create(),
                SaleTrendMetric::create(),
                SaleCategoryMetric::create(),
            ]),
            DetailSaleTable::create()
        ];
    }
}

Learn more about Row container.

Panel #

If you would like to create separate section to hold widgets, you may use Panel

use \koolreport\dashboard\Dashboard;
use \koolreport\dashboard\containers\Panel;

class SaleBoard extends Dashboard
{
    protected function widgets()
    {
        return [
            Panel::create()
            ->showHeader(true)
            ->headerText("Detail Sale Table")
            ->sub([
                DetailSaleTable::create()
            ])
        ];
    }
}

In above example, we created a Panel wrapping around DetailSaleTable. Learn more about Panel container.

Tabs #

You may organize widgets into Tab to save space if you would like:

use \koolreport\dashboard\Dashboard;
use \koolreport\dashboard\containers\Tabs;

class SaleBoard extends Dashboard
{
    protected function widgets()
    {
        return [
            Tabs::create()
            ->addTab("Order",[
                SaleChart::create()->title("Sale Chart"),    
            ])
            ->addTab("<i class='icon-users'></i> Customer",[
                CustomerTable::create()
            ]),
        ];
    }
}

In above example, we will have SaleChart and CustomerTable on 2 tabs. Learn more about Tabs container

Permission #

Since Dashboard use TEnabledPermit trait, it is able to use enabled() and enabledWhen() to set permission based on user and user's request.

enabled #

You may authorize an user to access a dashboard.

<?php
//App.php
class App extends Application
{
    ...
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create()->enabled(true),
            "Sale"=>SaleBoard::create()->enabled(false),
        ];
    }
    ...
}

The enabled() method can receive anonymous function as well

...
"Sale"=>SaleBoard::create()
            ->enabled(function($request){
                $user = $request->user();
                if($user->hasRole("admin"))
                {
                    return true;
                }
                return false;
            })
...

enabledWhen #

The enabledWhen() method is used when you have Permit class

//Permit.php

use \koolreport\dashboard\Permit;

class Permit extends Permit
{
    protected function beAdmin($request, $sender) 
    {
        return $request->user()->hasRole("admin");
    }
}
//App.php

class App extends Application
{
    protected function permission()
    {
        return Permit::create();
    }

    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale"=>SaleBoard::create()->enabledWhen("beAdmin"),
        ];
    }
}

Parameters #

It is possible to set parameters for a dashboard

Set parameter for dashboard #

//App.php

class App extends Application
{
    ...
    protected function dashboards()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale"=>SaleBoard::create()
                    ->params([
                        "year"=>2020,
                        "category"=>"Laptop & Tablet"
                    ]),
        ];
    }
}

Get parameters #

In order to retrieve parameters inside Dashboard

//SaleBoard.php
use \koolreport\dashboard\Dashboard;

class SaleBoard extends Dashboard
{
    protected function onInit()
    {
        $params = $this->params();
        //Get all parameters, return {"year"=>2020,"category"=>"Laptop & Tablet"}

        //Get a single value within params
        $year = $this->params("year");
        $category = $this->params("category");

    }
}

Get started with KoolReport

KoolReport will help you to construct good php data report by gathering your data from multiple sources, transforming them into valuable insights, and finally visualizing them in stunning charts and graphs.