Dashboard

Overview #

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

use koolreport\dashboard\Application;
class App extends Application
{
    ...
    protected function sidebar()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale"=>SaleBoard::create(),
        ];
    }
    ...
}

Dashboard is also be able to added to Page like this:

use koolreport\dashboard\pages\Main;
class App extends Main
{
    ...
    protected function sidebar()
    {
        return [
            "Home"=>HomeBoard::create(),
            "Sale"=>SaleBoard::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"
onClientLoadingstringnullSet a javascript to be run before dashboard is loaded
onClientLoadedstringnullSet a javascript to be run after dashboard is loaded

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 sidebar()
    {
        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 content()
    {
        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 content()
    {
        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 content()
    {
        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 content()
    {
        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 sidebar()
    {
        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 sidebar()
    {
        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 sidebar()
    {
        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 content() {
        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");

    }
}

Events #

Dashboard emits events during its process and we can catch those events to customize how dashboard behaves.

Learn more about Dashboard's events

Client events #

Dashboard supports following client events

Namedescription
onClientLoadingSet a javascript to be run before Dashboard is loaded
onClientLoadedSet a javascript to be run after dashboard is loaded

Example:

use \koolreport\dashboard\Dashboard;

class MyDashboard extends Dashboard
{
    protected function onCreated()
    {
        $this
        ->onClientLoading("alert('About to be loaded')")
        ->onClientLoaded("alert('Dashboard has been loaded')");
    }
}
use \koolreport\dashboard\Dashboard;

class MyDashboard extends Dashboard
{
    protected function onCreated()
    {
        $this
        ->onClientLoading(function(){
            return "alert('About to be loaded')";
        })
        ->onClientLoaded(function(){
            return "alert('Dashboard has been loaded')";
        });
    }
}

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.