Traits

TName #

TName trait allows object to get or set name with name() method. The Dashboard and Widget are implemented this trait.

Example:

class MyClass
{
    use \koolreport\dashboard\TName;
}

$obj = new MyClass();
echo $obj->name();
// Output "MyClass"

$obj->name("this is my class");
echo $obj->name();
//Output "this is my class"

TProps #

TProps facilitate object to get/set property for an object.

Example:

// Example of using object with TProps trait

$object
    ->hidden(true)
    ->width(1/2)
    ->cssClass("bold")
    ->cssStyle(function(){
        return "text-align:right";
    });

echo $object->hidden(); //true
echo $object->width(); //1/2
echo $object->cssClass(); //bold

//Anynomous function
$func = $object->cssStyle(); // Object() function
echo $object->_cssStyle(); // "text-align:right"

Methods #

When TProps is implemented in an object, object has below methods

Nametypedescription
props(array $list)Set the properties available, $list is an associate array with name of property and its default value
props()arrayUsing props() without parameter will return the list of properties in associate array
hasProp(string $propName)Return true if the property is existed
removeProps(array $ksys)Remove some properties, for example ->removeProps(["width","height"])
getProps(array $keys)Return raw value some of props only ->getProps(["width","height"])
_getProps(array $keys [,array $params])Return value of some of props only ->_getProps(["width","height"]), if a prop is anonymous function, the function will be executed to get value, the $params is options parameters for the anonymous function
_getProp(string $name [,array $params])Return value of a property, if the property is anonymous function, it will be executed and return value. The $params is optional to be passed to anonymous function

Example:

use \koolreport\dashboard\TProps;
use \koolreport\dashboard\TConstructServices;

class MyClass
{
    use TProps;
    use TConstructServices;

    public function __construct()
    {
        $this->constructServices();

        $this->props([
            "width"=>120,
            "height"=>240,
            "color"=>"red",
        ]);
    }
}

$obj = new MyClass;

$obj
->width(240)
->height(360)
->color("blue")
->title(function($text){
    return "Title ".$text;
});

echo $obj->width(); //240
echo $obj->color(); //"blue"

echo $obj->getProp("width"); //240
echo json_encode ($object->extractProps(["width","height"])); // {"width":240,"height":360}

echo $obj->hasProp("width")?"yes":"no"; // "yes"

$obj->removeProps(["width","height"]); // Now there is only "color" property

$a = $obj->getProps(["color","title"]); //$a = ["blue", object{}];

$a = $obj->_getProps(["color","title"],["text"=>"abc"]); // $a = ["blue","Title abc"];

$title = $obj->_getProp("title",["text"=>"abc"]); //$title = "Title abc";

$title = $obj->_title(["text"=>"abc"]); //$title = "Title abc";

TAppLink trait contains app() function which allows get/set the application object. Dashboard, Widget, Request are implemented this trait.

Example:

$this->app(); //Get the app object

$this->app($app); //Set the app object

TDashboardLink trait contains dashboard() function which allows get/set the dashboard object. Widget is implemented this trait.

Example:

$this->dashboard(); //Get the dashboard object

$this->dashboard($dashboard); //Set the dashboard object

TWidgetLink trait contains widget() function which allows get/set the widget object. Field is implemented this trait.

Example:

$this->widget(); //Get the widget object

$this->widget($widget); //Set the dashboard object

TParams #

TParams provides params() method to object. Dashboard and Widget are implemented this trait.

Example:

//Set parameters
$this->params([
    "year"=>2020,
    "productId"=>30,
    "features"=>[
        "size"=>20,
        "color"=>"blue"
    ]
]);

//Set parameter with function
$this->params(function(){
    return [
        "year"=>2020,
        "productId"=>30,
    ];
})

$this->params(); //Get all params

echo $this->params("year"); // Get only year parameter

//Mutate value
$this->params("market","asia"); // Add a new parameter "market" with value "asia"

$this->params("market,function(){
    return "asia";
})

TParamsPersisted #

The TParamsPersisted often goes with TParams inside Widget and Dashboard. That makes parameters set via TParams will be value persisted.

TWidgetState #

If a widget is equipped with TWidgetState, it will be able to get/set state value via state() method

//Set state
$this->state([
    "pageSize"=>10,
    "pageIndex"=>1
]);

$this->state(function(){
    return [
        "pageSize"=>10,
        "pageIndex"=>1
    ];    
})

//Get whole state
$state = $this->state();

// Get a value
$pageSize = $this->state("pageSize");

//Set a key value
$this->state("pageSize",10);

$this->state("pageSize",function(){
    return 10;
});

TStatePersisted #

This trait if used inside your dashboard will make your dashboard state persisted. That means when you navigate to other dashboard and come back to the dashboard, the UI components will stay the same. All parameters or what you have selected will be preserved.

<?php
use \koolreport\dashboard\Dashboard;

class MyDashboard extends Dashboard
{
    use \koolreport\dashboard\TStatePersisted;
    ...
}

TEnabledPermit #

TEnabledPermit provides methods enabled() and enabledWhen() method to object. Dashboard, Widget and Field are implemented this trait.

enabled() #

Get or set the availability of object

Example:

$this->enabled(false); // Disable the object

// Set by function
$this->enabled(function($request) {
    return $request->user()->hasRole("admin");
});

// Get status
$enabled = $this->enabled();

enabledWhen() #

If your application is provided with Permit object then you can use enabledWhen()

Example:

$this->enabledWhen("beAdmin");

//The "beAdmin" is define like this

class Permit extends \koolreport\dashboard\Permit
{
    protected function beAdmin($request, $sender)
    {
        return $request->user()->hasRole("admin");
    }
}

//The Permit will be provided to Application like this:

class App extends \koolreport\dashboard\Application
{
    protected function permission()
    {
        return Permit::create();
    }
}

TDetailAction #

TDetailAction provides hosted class with ability to open detail modal. The object created by class will have a showDetail property to allow detail modal to be open. The hosted class also need to provide a custom detailModal() to define the content of modal.

For example, Google Chart's ColumnChart is included with TDetailAction so you can do:

class MyDashboard extends Dashboard
{
    protected function content()
    {
        return [
            ColumnChart::create("myChart")
                ->detailShowable(true),
            Button::create()->text("Show detail")
                ->onClick(
                    Client::widget("myChart")->showDetail()
                )
        ];
    }
}

Code explanation:

  1. You allow ColumnChart to show detail data by setting ->detailShowable(true)
  2. On button click at client-side, myChart will open detail modal and show its data

Customize detail modal #

You can change the detail modal content by overwriting the detailModal() method and return your own Modal:


use \koolreport\dashboard\containers\Modal;

class MyChart extends ColumnChart
{
    protected function detailModal($params=[])
    {
        return Modal::create()
                ->title("My Own Modal")
                ->sub([
                    //Anything
                ]);
    }
}

Parameters #

As you notice from above example, the detailModal() method receives an array as parameters. This is the parameters sent from trigger method showDetail() for example:

Client::widget("myChart")->showDetail([
    "key"=>"value"
])

TExportable #

TExportable is used inside Widget and Dashboard class. It provide exporting capability for the hosted class. Below are properties and methods added:

Properties #

Namedescription
->pdfExportable(mixed $params)Turn on PDF exportable for widget, the parameters could be Boolean or an extra export settings for that widget
->pngExportable(mixed $params)Turn on PNG exportable for widget, the parameters could be Boolean or an extra export settings for that widget
->jpgExportable(mixed $params)Turn on JPG exportable for widget, the parameters could be Boolean or an extra export settings for that widget
->xlsxExportable(mixed $params)Turn on XLSX exportable for widget, the parameters could be Boolean or an extra export settings for that widget
->csvExportable(mixed $params)Turn on CSV exportable for widget, the parameters could be Boolean or an extra export settings for that widget

Methods #

Namedescription
exportedView(array $params)If you need to customize the view of exported content, you can overwrite this method to provide custom content for your exported file

TDataSource #

TDataSource provides hosted class with dataSource() method which will be used to provide different type of datasource to hosted class.

TFields #

TFields provides hosted class with fields() method which will be used to fetch list of fields and their configuration for hosted class.

TEvent #

TEvent will add to hosted class ability to register an event and trigger an event.

Methods #

Namedescription
registerEvent(string $name, func $handler)Register a function handler to an event with a name
fireEvent(string $name, [array $params])Fire an event and call all handlers that registered on this event

Example:

//Register an event
$this->registerEvent("Init",function(){
    echo "Init occur";
});

//Fire an event when somthing happens
$this->fireEvent("Init");

TAction #

TAction are used inside Dashboard and Widget so that they can receive action request from client-side.

When a object has TAction traits, you will be able to create actions by two ways:

First way: Inside class

class MyObject
{
    protected function actionAnyAction($request,$response)
    {
        //Do something
    }
}

Second way: On the object

MyObject::create()
    ->action("anyAction",function($request, $response){
        // Do something
    })

Action return #

Within the handling function of action, we can trigger javascript to run at clientside or open an notification:

Javascript: Some javacript to run at client-side

class MyObject
{
    protected function actionAnyAction($request,$response)
    {
        //Response with some javascript code

        return "alert('something to notice')";

        return Client::app()->changeLanguage("ES"); // Javacript to change language

        return Client::logout();

        return "console.log('what a good day');";
    }
}

Notification: Show notification of success or failure

use koolreport\dashboard\notifications\Alert;
use koolreport\dashboard\notifications\Note;
use koolreport\dashboard\notifications\Confirm;
class MyObject
{
    protected function actionAnyAction($request,$response)
    {
        //Response with some javascript code

        return Alert::danger("The process has failed");

        return Note::success("The process has done");

        return Confirm::info("Please confirm your action");
    }
}

To understand more about $request and $response in action, please visit Request & Response.

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.