Inputs

Overview #

Inputs are basically widget which is designed to receive inputs from users. For example, your dashboard contain a DateRangePicker which allows user to insert range of date and dashboard will show all metrics, charts, table within that period of time.

Common Settings #

Nametypedefaultdescription
valueGet/set the value of input
defaultValueGet/set the default value, this value will be shown when user have not provided any value
dataSourceGet/set the dataSource
fieldsGet/set list of fields

Note: Those above properties follows this code rules.

Events #

When user takes an action on inputs widget, it will trigger action to send to server. At server-side, we can handle that event in widget handler. For example, on date range change, we update those related charts.

actionChange #

Each input widget has different set of event handlers but most of them will have the same change event.

Example:

<?php
//CustomerSelect.php --------------------
use \koolreport\dashboard\inputs\Select;

class CustomerSelect extends Select
{
    protected function dataSource()
    {
        return AutoMaker::table("customers")
                ->select("customerNumber","customerName");
    }

    //By adding this function, you will catch event change of Select
    protected function actionChange($request, $response)
    {
        //This code will be execute when user select a customer
        //It will ask PaymentTable to update
        $this->dashboard()->widget("PaymentTable")->update();
    }
}

\\PaymentTable.php ---------------------
use \koolreport\dashboard\widgets\Table;

class PaymentTable extends Table
{
    protected function dataSource()
    {
        // PaymentTable will get the customerNumber from CustomerSelect widget
        // and perform query
        $customerNumber = $this->dashboard()->widget("CustomerSelect")->value();
        return AutoMaker::table("payments")
                ->where("customerNumber",$customerNumber);
    }
}

Components #

Button #

Nametypedefaultdescription
textstring"Submit"Get/set the text inside button
typestring"primary"Get/set the button type, accept "primary", "info", "danger", "success", "secondary"
cssStylestringGet/set css style for Button
cssClassstringGet/set css class for Button
sizestring"md"Get/set the size of button, accept "sm", "md", "lg"
outlinebooleanfalseGet/set the whether button is outline
onClickmixedGet/set client action on click event, more details
disabledbooleanfalseGet/set whether button is disabled
blockLevelbooleanfalseGet/set whether button take full size of available space
laddaOnActionbooleanfalseGet/set whether button using ladda loading effect
laddaStylestring"zoom-out"Get/set the effect of ladda loading, accept "zoom-out", "zoom-in", "slide-left", "slide-right", "slide-up", "slide-down".
attributesarrayGet/set the extra attributes to <button> element

Note: Those above properties follows this code rules.

Examples #

Basic settings

<?php
use \koolreport\dashboard\inputs\Button;

class MyButton extends Button
{
    protected functon onInit()
    {
        $this
            ->text("Update")
            ->type("success")
            ->size("sm")
            ->outline(true)
            ->disabled(false)
            ->blockLevel(false)
            ->laddaOnAction(true)
            ->laddaStyle("zoom-out")
            ->attributes([
                "style"=>"margin-left:10px"
            ])
    }
}

Action on user 's submission

<?php

use \koolreport\dashboard\inputs\Button;

class MyButton extends Button
{
    ...
    // Adding the actionSubmit function will allow us to handler the client submit event
    protected function actionSubmit($request, $response)
    {
        //Update CustomerTable on button click
        $this->sibling("CustomerTable")->update();
    }
}

Customize client on click action

<?php

use \koolreport\dashboard\Client;

class CustomerDetailButton extends Button
{
    protected functon onInit()
    {
        $this
            ->onClick(function(){
                //Loading the CustomerBoard on Button click
                return Client::dashboard("CustomerBoard")->load(); 
            })
    }
}

Short hard Button created with type

Button::primary("Submit")
Button::secondary("Submit")
Button::success("Submit");
Button::danger("Submit")
Button::warning("Submit")
Button::info("Submit")

Toggle #

Nametypedefaultdescription
valueintGet/set value of Toggle, accept 0 or 1
defaultValueint0Get/set default value , accept 0 or 1
is3DboolfalseGet/set whether Toggle show 3D button
showTextboolfalseGet/set whether Toggle use text label for Toggle state
onTextstring"on"Get/set the text when Toggle is on
offTextstring"off"Get/set the text when Toggle is off
typestring"primary"Get/set type of Toggle, accept "primary","secondary","danger","success","warning"
outlineboolfalseGet/set whether Toggle show outline color only
pillbooltrueGet/set whether Toggle show pill shape
sizestring"md"Get/set size of Toggle, accept "sm","md","lg"
cssClassstringnullGet/set extra css class
cssStylestringnullGet/set extra css style
onClickstringnullGet/set javascript to be run when Toggle is clicked

Example 1:

class MyDashboard extends Dashboard 
{
    protected function content()
    {
        return [
            Toggle::create("myToggle")
                ->defaultValue(0)
                ->is3D(true)
                ->showText(true)
                ->onText("on")
                ->offText("off")
                ->type("primary")
                ->pill(false)
                ->size("md")
                ->cssClass("extra-class")
                ->cssStyle("margin-left:10px;")
                ->onClick("alert('toggle')")
                ->action("change",function($request, $response) {
                    $this->sibling("ResultTable")
                        ->params([
                            "showPageSize"=>$this->value()
                        ])
                        ->update();
                }),
                ResultTable::create()
        ];
    }
}

Example 2:

use \koolreport\dashboard\inputs\Toggle;

class MyToggle extends Toggle
{
    protected function onCreated()
    {
        $this
        ->defaultValue(0)
        ->is3D(true)
        ->showText(true)
        ->onText("on")
        ->offText("off")
        ->type("primary")
        ->pill(false)
        ->size("md")
        ->cssClass("extra-class")
        ->cssStyle("margin-left:10px;")
        ->onClick("alert('toggle')");    
    }

    protected function actionChange($request, $reponse)
    {
        $this->sibling("ResultTable")
            ->params([
                "showPageSize"=>$this->value()
            ])
            ->update();
    }
}

CheckBoxList #

Nametypedefaultdescription
verticalbooleantrueGet/set whether list of checkbox will appear vertically

Note: Those above properties follows this code rules.

Example:

<?php

use \koolreport\dashboard\inputs\CheckBoxList;

class OfficeCheckList extends CheckBoxList
{
    protected function onInit()
    {
        $this->vertical(false);
    }
    protected function dataSource()
    {
        return AutoMaker::table("offices")->select("addressLine1");
    }
}

RadioList #

Nametypedefaultdescription
verticalbooleantrueGet/set whether list of radio list will appear vertically

Note: Those above properties follows this code rules.

Example:

<?php

use \koolreport\dashboard\inputs\RadioList;

class OfficeCheckList extends RadioList
{
    protected function onInit()
    {
        $this->vertical(false);
    }
    protected function dataSource()
    {
        return AutoMaker::table("offices")->select("addressLine1");
    }
}

DateRangePicker #

DateRangePicker is an input widget that allows you to pick a range of date. This is very helpful to build dashboard when information is built based on period of time.

Nametypedefaultdescription
formatstring"MMM Do, YYYY"Get/set date format, more details
valuearrayGet/set the range value of DateRangePicker
languagestringGet/set language of DateRangePicker
minDatestringGet/set min date
maxDatestringGet/set max date
iconstring"fa fa-calendar-alt"Get/set icon class
caretstring"fa fa-caret-down"Get/set the caret icon
rangesarrayGet/set the list of range options

Note: Those above properties follows this code rules.

Example:

<?php
use \koolreport\dashboard\inputs\DateRangePicker;

class MyRangePicker extends DateRangePicker
{
    protected function onInit()
    {
        $this->format("MMM Do, YYYY")
            ->value(["2020-01-01 00:00:00","2020-03-01 00:00:00"])
            ->language("en")
            ->minDate("2020-01-01 00:00:00")
            ->maxDate("2020-04-01 00:00:00")
            ->icon("fa fa-calendar-alt")
            ->caret("fa fa-caret-down")
            ->ranges([
                "Today"=>DateRangePicker::today(),
                "Yesterday"=>DateRangePicker::yesterday(),
                "Last 7 days"=>DateRangePicker::last7days(),
                "Last 30 days"=>DateRangePicker::last30days(),
                "This month"=>DateRangePicker::thisMonth(),
                "Last month"=>DateRangePicker::lastMonth(),
            ]);
    }
}

Events #

To register and handle the change event of DateRangePicker, you do:

<?php
use \koolreport\dashboard\inputs\DateRangePicker;

class MyRangePicker extends DateRangePicker
{
    //Provide actionChange, this function will be called when user make change to DateRangePicker
    protected function actionChange($request, $respose)
    {
        //Update the SaleTable
        $this->sibling("SaleTable")->update();
    }
}

DateTimePicker #

DateTimePicker allow you to pick a date or time.

Nametypedefaultdescription
formatstring"MMM Do, YYYY"Get/set date format, more details
localestringGet/set the locale
disableDatesarrayGet/set list of disabled dates
minDatestringGet/set min date
maxDatestringGet/set max date
iconstringGet/set icon class
optionsarrayGet/set extra options for DateTimePicker

Note: Those above properties follows this code rules.

Events #

DateTimePicker also support change event.

MultiSelect #

MultiSelect allows user to select list of items.

Nametypedefaultdescription
defaultOptionarrayGet/set the array of default options)
cssStylestringGet/set extra style
cssClassstring"form-control"Get/set css class
sizestring"md"Get/set the size of multiselect, "sm", "md", "lg"

Note: Those above properties follows this code rules.

Examples:

<?php
use \koolreport\dashboard\inputs\MultiSelect;

class OfficeList extends MultiSelect
{
    protected function onInit()
    {
        $this
            ->defaultOption([0,1]) //Select the first two offices
            ->cssStyle("margin-left:10px")
            ->cssClass("form-control")
            ->size("lg");
    }   

    //Provide datasource
    protected function dataSource()
    {
        return AutoMaker::table("offices")
                ->select("officeCode","addressLine1");
    }

    //Provide list of fields to act as value and text for MultiSelect
    protected function fields()
    {
        return [
            Number::create("officeCode"),
            Text::create("addressLine1")
        ];
    }

    //Update the EmployeeTable when user select values
    protected function actionChange($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }

}

RangeSlider #

RangeSlider allows you to setup a value range which user can drag to change the range

Example:

<?php>

use \koolreport\dashboard\inputs\RangeSlider;

class MyRange extends RangeSlider
{
    protected function onInit()
    {
        $this
            ->value([20,80])
            ->range([
                "min"=>0,
                "max"=>100,
            ])
            ->scale(5)
            ->step(10)
            ->format([
                "prefix"=>"$",
                "decimals"=>2,
            ])
            ->rtl(false)
            ->vertical(false);
    }

    protected function onChange($request,$response)
    {
        $this->sibling("SaleTable")->update();
    }
}

More information, please check.

Select #

Nametypedefaultdescription
defaultOptionarrayGet/set the array of default options)
cssStylestringGet/set extra style
cssClassstring"form-control"Get/set css class
sizestring"md"Get/set the size of multiselect, "sm", "md", "lg"

Note: Those above properties follows this code rules.

Examples:

<?php
use \koolreport\dashboard\inputs\Select;

class OfficeList extends MultiSelect
{
    protected function onInit()
    {
        $this
            ->defaultOption(0) //Select the first office
            ->cssStyle("margin-left:10px")
            ->cssClass("form-control")
            ->size("lg");
    }   

    //Provide datasource
    protected function dataSource()
    {
        return AutoMaker::table("offices")
                ->select("officeCode","addressLine1");
    }

    //Provide list of fields to act as value and text for MultiSelect
    protected function fields()
    {
        return [
            Number::create("officeCode"),
            Text::create("addressLine1")
        ];
    }

    //Update the EmployeeTable when user select values
    protected function actionChange($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }

}

Select2 #

Nametypedefaultdescription
defaultOptionarrayGet/set the array of default options
cssStylestringGet/set extra style
cssClassstring"form-control"Get/set css class
sizestring"md"Get/set the size of select2, "sm", "md", "lg"
multiplebooleanfalseGet/set whether mode multiple is turned on
placeHolderstringGet/set the place holder text for Select2
optionsarrayGet/set extra options for Select2

Note: Those above properties follows this code rules.

More information, please check.

Examples:

<?php
use \koolreport\dashboard\inputs\Select2;

class OfficeList extends Select2
{
    protected function onInit()
    {
        $this
            ->defaultOption(0) //Select the first office
            ->cssStyle("margin-left:10px")
            ->cssClass("form-control")
            ->size("lg")
            ->multiple(false)
            ->placeHolder("Select list of offices");
    }   

    //Provide datasource
    protected function dataSource()
    {
        return AutoMaker::table("offices")
                ->select("officeCode","addressLine1");
    }

    //Provide list of fields to act as value and text for MultiSelect
    protected function fields()
    {
        return [
            Number::create("officeCode"),
            Text::create("addressLine1")
        ];
    }

    //Update the EmployeeTable when user select values
    protected function actionChange($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }

}

BSelect #

BSelect is another alternatives for selecting. The best feature of BSelect lie in its compact mode where all multiple selections are compacted into number of items selected.

Nametypedefaultdescription
multipleboolfalseGet/set whether user can select multiple options
attributesarray[]Get/set the attributes of raw select html tag
optionsarray[]Get/set extra options for BSelect, here is full list
cssClassstringnullGet/set extra css class
cssStylestringnullGet/set extra css style

Dropdown #

Dropdown acts like a small menu contains custom items

Nametypedefaultdescription
iconstringnullGet/set icon of dropdown
titlestring"Menu"Get/set the title of dropdown
typestring"primary"Get/set the type of dropdown, options are "default", "primary", "secondary", "warning", "danger", "success"
outlinebooleanfalseGet/set whether outline button is applied
sizestring"md"Set size of dropdown button "lg", "md", "sm"
disabledbooleanfalseGet/set whether dropdown is disabled
alignstring"left"Get/set dropdown menu alignment, accepting "left" or "right"
blockLevelbooleanfalseGet/set whether expand full 100% in width
itemsarray[]Get/set list of menu items

Note: Those above properties follows this code rules.

Example:

use \koolreport\dashboard\inputs\Dropdown;

...

Dropdown::create("myDropdown") // If you create DropDown inside Dashboard, you should provide name for it
->icon("fa fa-cog")
->title("Settings")
->type("default")
->outline(false)
->size("sm")
->align("right")
->disabled(false)
->blockLevel(true)
->items([
    "Simple link"=>MenuItem::create()
        ->href("https://www.anywebsite.com")
        ->target("_blank"),

    "With Icon and Badge"=>MenuItem::create()
        ->href("https://www.example.com")
        ->icon("fa fa-book")
        ->badge(["NEW","danger"]),
    
    "Execute javascript"=>MenuItem::create()
        ->onClick("alert('hola')"),
    
    "Load Dashboard"=>MenuItem::create()
        ->onClick(Client::dashboard("SaleBoard")->load()),

    "Disabled Item"=>MenuItem::create()->disabled(true),
])

Alternatively, you create your own dropdown by derived from DropDown:

class MyDropDown extends \koolreport\dashboard\inputs\DropDown
{
    protected function onCreated()
    {
        $this->->icon("fa fa-cog")
                ->title("Settings")
                ->type("default")
                ->outline(false)
                ->size("sm")
                ->disabled(false)
                ->blockLevel(true);
    }

    protected function items()
    {
        return [
            "Simple link"=>MenuItem::create()
                ->href("https://www.anywebsite.com")
                ->target("_blank"),

            "With Icon and Badge"=>MenuItem::create()
                ->href("https://www.example.com")
                ->icon("fa fa-book")
                ->badge(["NEW","danger"]),
            
            "Execute javascript"=>MenuItem::create()
                ->onClick("alert('hola')"),
            
            "Load Dashboard"=>MenuItem::create()
                ->onClick(Client::dashboard("SaleBoard")->load())
        ];
    }
}

TextBox #

TextBox show text box for user to input.

Nametypedefaultdescription
valuearrayGet/set value of text bpx
cssStylestringGet/set extra style
cssClassstring"form-control"Get/set css class
sizestring"md"Get/set the size of textbox, "sm", "md", "lg"
trimValueboolGet/set if the value of textbox will be trim space
frontTextstringGet/set the text in front of textbox
backTextstringGet/set the text at back of textbox
processValuefunctionGet/get function that receive value as parameter and return the processed value

Note: Those above properties follows this code rules.

Events #

TextBox support blur, focus, click, dbclick events

use \koolreport\dashboard\inputs\TextBox;

class MyTextBox extends TextBox
{
    //When user focus on textbox
    protected function actionFocus($request, $response)
    {
        $this->sibling("EmployeeTable")->update();    
    }

    //When user leave textbox
    protected function actionBlur($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }
    
    //When user click to textbox
    protected function actionClick($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }
    
    //When user double click on textbox
    protected function actionDbclick($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }
}

TextArea #

TextArea use textarea html element for user input

Nametypedefaultdescription
valuearrayGet/set value of text bpx
cssStylestringGet/set extra style
cssClassstring"form-control"Get/set css class
placeHolderstringGet/set placeholder
trimValueboolGet/set if the value of textarea will be trim space
processValuefunctionGet/get function that receive value as parameter and return the processed value

Note: Those above properties follows this code rules.

Events #

TextArea support blur, focus, click, dbclick events

use \koolreport\dashboard\inputs\TextBox;

class MyTextBox extends TextBox
{
    //When user focus on textbox
    protected function actionFocus($request, $response)
    {
        $this->sibling("EmployeeTable")->update();    
    }

    //When user leave textbox
    protected function actionBlur($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }
    
    //When user click to textbox
    protected function actionClick($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }
    
    //When user double click on textbox
    protected function actionDbclick($request, $response)
    {
        $this->sibling("EmployeeTable")->update();
    }
}

FileUploader #

FileUploader is used to upload any file to your dashboard application.

Properties #

Nametypedefaultdescription
typestring"secondary"Get/set the color theme of file uploader, accept primary, secondary, success, danger, warning, info
saveToFolderstringGet/set the path to folder that used to save files
acceptarrayList of accepted file extensions
notAcceptarray["php"]List of not-accepted file extensions
maxFileSizeintGet/set the max file size in bytes
imagePreviewboolfalseGet/set whether the image preview is shown
showDownloadLinkboolGet/set whether download link is available
previewWidthstringGet/set the preview box width
previewHeightstringGet/set the preview box height
errorMessagestringGet/set the error message to be shown
fileNamefunction($name,$ext)Set the function to return the file name from parameter name and extendsion
fileHandlefunction($file)Set the function which received $file information and you can alternate the way to handle file
resolveValuefunction($file)Set the function which received $file information and return value
resolveUrlfunction($value)Set the function that resolve url from value
fileNotAllowedErrorstringGet/set error message when file is not allowed
fileSizeLmitErrorstringGet/set the error message when file size is over limit
unknownErrorstringGet/set error message when unknown error happens
noFileErrorstringGet/set error message when no file is selected
noFileSelectedTextstringGet/set status when no file is selected
selectFileTextstringGet/set the "Selected file.." text
valuestringGet the value of file uploader

Example:

FileUploader::create("myFileUploader")
    ->type("primary")
    ->accept(["jpg","png"])
    ->notAccept(["php"])
    ->maxFileSize(200000)
    ->imagePreview(true)
    ->showDownloadLink(true)
    ->previewWidth("150px")
    ->previewHeight("150px")
    ->fileName(function($name,$ext){
        return $name.".".$ext;
    })
    ->fileHandle(function($file){
        $name = $file["name"];
        $tmp = $file["tmp_name"];
        //You can do any thing to handle your file here
    })
    ->resolveValue(function($file){
        return $file["name"];
    })
    ->resolveUrl(function($value){
        return "https://examples.com/images/$value";
    })
    ->fileNotAllowedError("Not allowed")
    ->fileSizeLmitError("Oversized")
    ->unknownError("So mysterious")
    ->noFileError("No file was selected")
    ->noFileSelectedText("No file was selected")
    ->selectFileText("Select a file..")

Events #

Namedescription
onFileHanldingTo be called before file is handled, return true to approve default handling, return false to cancel default handling
onFileHandledTo be called after file is handled

Example:

class MyFileUploader extends FileUploader
{
    protected function onFileHandling($params)
    {
        $file = $params["file"];

        return true; //Approve
        //return false; Disapprove
    }

    protected function onFileHandled($params)
    {
        $file = $params["file"];
        //Do anything after file is handled
    }
}

CheckBox #

CheckBox is different from CheckBoxList which have multiple selected options, the CheckBox only have single option.

Nametypedefaultdescription
textstringGet/set the text goes along with the checkbox
inlineboolfalseGet/set whether the checkbox is display inline
onChangestringGet/set the js function to execute when checkbox changes
cssStylestringGet/set the css style for checkbox
cssClassstringGet/set the css class for checkbox

Example:

CheckBox::create("checkboxAutoUpdate")
->text("Auto Update")
->inline(false)
->onChange("console.log('do something at client-side')")
->action("change",function($request, $response){
    //Do something at server-side
})
->cssStyle("margin-left:5px;")
->cssClass("my-checkbox-css-class")

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.