Fields

Overview #

Field is special item provided inside fields() methods of Widget. Base on the fields provided, Widget will have the list of required data fields and their settings to act accordingly. Here is the common settings of fields inside Widget that you will see:

Example:

<?php

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

class SaleTable extends Table
{
    ...
    protected function fields()
    {
        return [
            Text::create("customerName"),
            Text::create("productName"),
            Number::create("quantity"),
            Currency::create("priceEach")->USD()->symbol(),
            Calculated::create("total",function($row){
                return '$'.number_format($row["quanity"]*$row["priceEach"],2);
            });
        ];
    }
}

Properties #

Following are common properties that all field types have

Namedescription
nameGet/set name of fields
colNameGet/set column name from datasource that field applied settings to
labelGet/set label of the field
sortGet/set sorting, accept "desc" and "asc"
valueTypeGet/set native type of data, accept "string", "int", "float", "boolean"
resolveUsingSet/get function used to resolve value from original value
formatUsingSet/get function used to format the value
rowGet/set data row
emptyValueGet/set to set alternative display for empty value
nullDisplayGet/set the display when value is null
customRenderGet/set the custom rendering for field

Note: Those above properties follows this code rules.

Methods #

Namedescription
value()Get the value
originalValue()Get the original value
formattedValue()Get value after formatted
formatValue(mixed $value[, array $row])Format value according to the rule of field, taking into account the custom formatting from formatUsing
defaultFormatValue(mixed $value[, array $row])Default format value according to the rule of field

Traits #

Field is implemented following traits:

  1. TWidgetLink: Link with widget that contains the field
  2. TEnabledPermit: Set field availability by permission

Permission #

Because Field contains the TEnabledPermit so we are able to set permission to the fields of widget. It is very useful to make customized fields for each group of user. For example, a table will have extra detail fields for admin only or chart will show detail revenue for sale team but not others.

Example:

class SaleTable extends Table
{
    ...
    provided function fields()
    {
        return [
            Text::create("customerName"),
            Text::create("productName"),
            Number::create("quantity")->enabled(function($request){
                return $request->user()->hasRole("sale") 
                        ||$request->user()->hasRole("admin");
            }),
        ];
    }
}

Types #

Text #

Text field deals with string data from database.

Properties #

Namedescription
prefixGet/set prefix used to format value
suffixGet/set suffix used to format value
stringCaseGet/set case type, accept "lower", "upper", "lcfirst" (lowercase first character), "ucfirst" (uppercase first character)
htmlGet/set whether the field is rendered in html, default value is false

Note: Those above properties follows this code rules.

Number #

Number field deal with number data type. It is derived from Text field so it has all methods from Text with following additional methods

Namedescription
decimalsGet/set number of decimals after decimal point
thousandSeparatorGet/set the thousand separator character
decimalPointGet/set decimal point character
useRawGet/set whether value should be formatted, accept true or false

Note: Those above properties follows this code rules.

Percent #

Percent is derived from Number and all its does it prefix the formatted number with percent sign (%).

Currency #

Currency deals with currency data. It derived from Number so you can use all methods from Number. The great thing of Currency is that it contains all most popular currencies.

Methods #

Namedescription
full()Use full name of currency
symbol()Use currency symbol

You can format value to any currency with ISO 4217 Currency Code. For example, ->USD() to format to US Dollar or ->EUR() will format to Euro currency.

Example:

Currency::create("amount")->USD(); // USD1234.56

Currency::create("amount")->USD()->symbol(); // $1234.56

Currency::create("amount")->USD()->full(); // 1234.56 US Dollar

Currency::create("amount")->USD()->symbol()->decimals(0); // $1234

DateTime #

DateTime deals with datetime data. It derived from Text so it has all methods from Text. It is provided following methods to deal with datetime.

Namedescription
baseFormatGet/set the base format. Base format is the format of original datetime data, default format is Y-m-d H:i:s
displayFormatThe format that you want datetime to be shown to users

Note: Those above properties follows this code rules.

Example:

DateTime::create("paymentTime")->baseFormat("Y-m-d H:i:s")->displayFormat("F j, Y")

Date #

Date is derived from DateTime to deal with date only. Its baseFormat is Y-m-d.

Time #

Time is derived from DateTime to deal with time only. Its baseFormat is H:i:s.

TimeAgo #

TimeAgo is derived from DateTime, it has baseFormat "Y-m-d H:i:s" which is the same as original DateTime. However when it will display in format of 1hour ago or 2 days ago.

Calculated #

Calculated column is special column which is generated by calculation.

Calculated::create("saleInDollar",function($row){
    return $row["price"]*$row["quantity"];
})

Link column is able to create custom <a> link tag.

Link::create()->label("View details")
    ->href(function($value, $row){
        return "https://example.com/items/".$row["id"];
    })
    ->cssStyle("font-weight:bold;")
    ->cssClass("link-class")

Link::create()->label("View details")
    ->onClick("alert('link clicks')")


Link::create()->label("View details")
    ->onClick(function($value, $row){
        return "alert('link click'.$row["id"])
    })

Link::create()->label("View details")
    ->href("https://anylink.com")

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.