Widget

Overview #

Widget is single self-contained component which can work independently to provide data visualization. Widget is normally added into Dashboard.

Properties #

Below are the most common properties for any widgets

Nametypedefaultdescription
autoUpdateintWhether widget is refreshed/updated after period of time
widthfloatThe proportion of widgets inside container
heightstringThe height of widget
cacheintThe number of seconds that data source will be cached for this widget
lazyLoadingboolfalseWhether the widget perform lazy loading
updateEffectstringnoneThe update effect when content of widget is updated
showLoaderOnActionboolfalseWhether the loader will show when this widget is updated content

Note: Those above properties follows this code rules.

We can set those settings inside onInit() method of Widget

use \koolreport\dashboard\widgets\Table;
class MyWidget extends Table
{
    protected function onInit()
    {
        $this->width(1/3)
        ->lazyLoading(true)
        ->showLoaderOnAction(true)
        ->cache(5000);
    }
}

or from outside of widget

MyWidget::create()
    ->width(1/3)
    ->lazyLoading(true)
    ->showLoaderOnAction(true)
    ->cache(5000);

Methods #

Nametypedescription
sibling($name)WidgetReturn sibling widget inside the same dashboard
update()Ask widget to update

Example:

<?php 
//ProductLineSelector.php
use \koolreport\dashboard\inputs\Select;
class ProductLineSelector extends Select
{
    ...
    protected function actionChange($request,$response)
    {
        //When user select a product line, ask sibling widget [ProductTable] to update
        $this->sibling("ProductTable")->update();
    }
    ...
}
<?php
//ProductTable.php

use \koolreport\dashboard\widgets\Table;
class ProductTable extends Table
{
    ...
    protected function dataSource()
    {
        //Get the ProductLineSelector value, and query product belongs to that product line
        $productLine = $this->sibling("ProductLineSelector")->value();
        return AutoMaker::table("products")
                ->where("productLine",$productLine);
    }
    ...
}

Traits #

Widget has been provided with following traits:

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

Permission #

Because Widget has equipped with TEnabledPermit, so we can set permission for Widget with enabled() and enabledWhen() methods. Please refer to TEnabledPermit documentation for further details.

enabled() #

You may authorize an user to access a widget.

<?php
//App.php
class MyDashboard extends Dashboard
{
    ...
    protected function widgets()
    {
        return [
            SrecretWidget::create()->enabled(false)
        ];
    }
    ...
}

The enabled() method can receive anonymous function as well

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

enabledWhen() #

The enabledWhen() method is used when you have Permit class provided to Application. Learn more about Permission.

//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();
    }
    ...
}
class MyDashboard extends Dashboard
{
    protected function widgets()
    {
        return [
            SecretWidget::create()->enabledWhen("beAdmin");
        ];
    }
}

Display widgets #

Display widgets serves main purpose of visualizing data from source. It could be table or chart.

Table #

You can create custom data table by deriving from Table class:

<?php
//EmployeeTable.php

use \koolreport\dashboard\widgets\Table;
use \koolreport\dashboard\fields\Number;
use \koolreport\dashboard\fields\Text;
use \koolreport\dashboard\fields\Calculated;


class EmployeeTable extends Table
{
    protected function onInit()
    {
        $this->pageSize(10);
    }

    protected function dataSource()
    {
        return AutoMaker::table("employees")
                ->select("employeeNumber","firstName","lastName","jobTitle");
    }

    protected function fields()
    {
        return [
            Number::create("employeeNumber"),
            Calculated::create("name",function($data){
                return $data["firstName"]." ".$data["lastName"];
            }),
            Text::create("jobTitle")
        ];
    }
}

Learn more about Table widget.

Google Chart #

Google Charts is group of excellent charts to visualize your data. Below is sample of using ColumnChart. More details, you may visit Google Charts widgets.

<?php


use \koolreport\dashboard\widgets\google\ColumnChart;

use \koolreport\dashboard\fields\Text;
use \koolreport\dashboard\fields\Number;

class ProductLineInStock extends ColumnChart
{
    protected function dataSource()
    {
        return AutoMaker::table("product")
                ->groupBy("productLine")
                ->select("productLine")
                ->sum("quantityInStock")->alias("quantity");
    }

    protected function fields()
    {
        return [
            Text::create("productLine"),
            Number::create("quantity"),
        ];
    }
}

KWidget #

KWidget is an special widget which can wrap any KoolReport. Here is an example of using ChartJs ColumnChart

use \koolreport\dashboard\Dashboard;
use \koolreport\dashboard\widgets\KWidget;

class MyDashboard extends Dashboard
{
    protected function dashboard()
    {
        return [
            KWidget::create()
                ->use(\koolreport\chartjs\ColumnChart::class)
                ->dataSource(
                    AutoMaker::table("product")
                        ->groupBy("productLine")
                        ->select("productLine")
                        ->sum("quantityInStock")->alias("quantity")
                )
                ->settings([
                    "title"=>"Product Line In Stock"
                ]);
        ];
    }
}

or another way that you create your own chart derived from KWidget

use \koolreport\dashboard\widgets\KWidget;

class ProductLineInStock extends KWidget
{
    protected function onInit()
    {
        $this->use(\koolreport\chartjs\ColumnChart::class)
            ->settings([
                "title"=>"Product Line In Stock"
            ]);
    }

    protected function dataSource()
    {
        return AutoMaker::table("product")
            ->groupBy("productLine")
            ->select("productLine")
            ->sum("quantityInStock")->alias("quantity");
    }
}

More information of KWidget.

Metric widgets #

Metric widgets allow you to gain the business key indicators for your application. For example, you can get define metrics to show sale amount per day or number of users registered per week. There are 3 types of metrics:

  1. Value metric
  2. Trend metric
  3. Category metric

Inputs widgets #

Inputs allow user to control over the data shown on dashboard, for example date range selection, category selection. Here is the list input widgets:

  1. Button
  2. CheckBoxList
  3. DateRangePicker
  4. DateTimePicker
  5. MultiSelect
  6. RadioList
  7. RangeSlider
  8. Select
  9. Select2
  10. TextBox

Container widgets #

Container widgets act as containers for main widgets and provide main widgets a layout. Below are list of container widgets that you may be interested in further details:

  1. Row
  2. Panel
  3. Tabs
  4. Modal

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.