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 #
Name | type | default | description |
---|---|---|---|
default | boolean | false | Whether dashboard is default |
title | string | Title of dashboard, which will appear in the menu | |
hidden | boolean | false | Whether the dashboard is hidden, could not access from menu |
icon | string | The icon of dashboard | |
badge | string/array | Add badge to menu | |
updateEffect | string | "fade" | Visual effect when dashboard is updated, whether "fade" or "none" |
onClientLoading | string | null | Set a javascript to be run before dashboard is loaded |
onClientLoaded | string | null | Set 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 #
Name | type | description |
---|---|---|
widget($name) | Widget | Return widget inside dashboard by its widget's name |
hasWidget($name) | boolean | Return 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:
- TAppLink: Able to refer to application with
app()
method - TEnabledPermit: Use
enabled()
andenabledWhen()
to set permission - TParams: Able to get/set parameters with
params()
method - TExportable: Able to export dashboard to PDF and other formats
- TProps: Able to set property
- TEvent: Able to register and handle an event
- 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
Name | description |
---|---|
onClientLoading | Set a javascript to be run before Dashboard is loaded |
onClientLoaded | Set 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.