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
namestringGet/set name of widget
autoUpdateintWhether widget is refreshed/updated after period of time
widthfloatThe proportion of widgets inside container
heightstringThe height of widget
hiddenbooleanfalseGet/set whether widget should be hidden
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
hasSibling($name)Return true if widget has sibling with specified name
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. TExportable: Able to export widget to different 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

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

D3 #

D3 is an excellent alternative solution for Google Chart. The advantage of D3 over GoogleCharts is that it does not require loading library from internet like Google Charts does. More details, you may visit D3 Charts.

ChartJs #

ChartJs is also an powerful chart library for your consideration. More details, you may visit ChartJs.

Pivot #

We provide PivotMatrix and PivotTable widgets for Dashboard. More details, you may visit Pivot in Dashboard.

DrillDown #

DrillDown is an great widget for data exploration. The data will be summarized at overview levels and can be broken down at lower levels. More details, you may visit How to make DrillDown in Dashboard.

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. Dropdown
  3. Toggle
  4. CheckBoxList
  5. DateRangePicker
  6. DateTimePicker
  7. MultiSelect
  8. RadioList
  9. RangeSlider
  10. Select
  11. Select2
  12. 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
  5. Inline
  6. Html

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.