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 follows 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
hasWidget($name)booleanReturn true if dashboard has widget with specified name
update()Ask a dashboard to update/refresh
state(array $params)Set state with params
state(function $func)Set state with a function returning array
state(string $key, mixed $value)Set state for $key
state(string $key, function $func)Set state for $key with function return value
state(string $key)Get state with $key
state()Get all state

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
  4. TExportable: Able to export dashboard to PDF and other formats
  5. TProps: Able to set property
  6. TEvent: Able to register and handle an event
  7. TAction: Able to receive action from client-side and handle within class

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"
                    ]),
        ];
    }
}

Load dashboard with parameters #

To load dashboard from client you use Client class

use \koolreport\dashboard\Client;

class ExampleDashboard extends Dashboard
{
    protected function widgets() {
        return [
            Button::create()
                ->text("Load dashboard with params")
                ->onClick(Client::dashboard("OtherBoard")->load(["key"=>"value"]))
        ];
    }
}


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.