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;

class SaleTable extends Table
{
    ...
    provided 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);
            });
        ];
    }
}

Methods #

Following are common methods that all field types have

Namedescription
name([string $value])Get/set name of fields
colName([string $colName])Get/set column name from datasource that field applied settings to
label([string $label])Get/set label of the field
sort([string $direction])Get/set sorting, accept "desc" and "asc"
valueType([string $nativeType])Get/set native type of data, accept "string", "int", "float", "boolean"
resolveUsing([function $func])Set/get function used to resolve value from original value
formatUsing([function $func])Set/get function used to format the value
row([array $row])Get/set data row
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

Note: Those get/set methods follows this code rules.

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.

Methods #

Namedescription
prefix([string $prefix])Get/set prefix used to format value
suffix([string $suffix])Get/set suffix used to format value
stringCase([string $case])Get/set case type, accept "lower", "upper", "lcfirst" (lowercase first character), "ucfirst" (uppercase first character)

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
decimals([int $decimals])Get/set number of decimals after decimal point
thousandSeparator([string $separator])Get/set the thousand separator character
decimalPoint([string $point])Get/set decimal point
useRaw([boolean $raw])Get/set whether value should be formatted

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
baseFormat([string $format])Get/set the base format. Base format is the format of original datetime data, default format is Y-m-d H:i:s
displayFormat([string $format])The format that you want datetime to be shown to users

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

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.