Fields

Overview #

Fields are smallest element which normally corresponds to your database table's column. The field also contains visual settings of column in admin table as well as in update, create and detail screen of admin panel.

All the fields in Dashboard can be used in Admin Panel including:

  1. Common fields: Text, Number, Percent, Currency, DateTime, Date, Time, TimeAgo, Calculated.
  2. Table-exclusive fields: Badge, Button, Icon, Image, Progress, Sparkline.
  3. Extra fields: ID, Password

ID Field #

As the name suggested, ID field is an special field to act as identity of a record in resources. It is always required in any field list.

protected function fields()
{
    return [
        ID::create("your-id-column-name"),
        ...
    ];
}

Note: The ID field by default is not showing in UpdateScreen. If you want the ID field to show on UpdateScreen and value can be updated, you use ->showOnUpdate(true) in ID field settings.

Where to use #

The fields used in fields() method of Resources and in Glasses to provide list of fields that needed to fetch data.

Properties #

The fields used in Admin Panel will have some special properties that may not be available in other place.

Nametypedefaultdescription
showOnIndexboolWhether the field will be shown on index list screen
showOnUpdateboolWhether the field will be shown on update screen
showOnDetailboolWhether the field will be shown on detail screen
showOnCreateboolWhether the field will be shown on create screen
showOnAllboolWhether the field will be shown on all screens
searchableboolAllow admin table to perform searching on this field
sortstringAccept desc or asc to let this fields sort
footerstringAccept sum,min, max, mode, count, avg
footerTextstringAssign text to footer of admin table
textAlignstringSet alignment of field in admin table, accept left, right, center
allowNullValueboolfalseWhether the field can update NULL to database
shouldUpdateboolSetup an anonymous function to determine whether a field should be updated to database
processValueToDatabasemixedSetup an anonymous function to alternate value to be updated to database

Example

Text::create("name")
    ->showOnAll(true)
    ->searchable(true)
    ->sortable(true)
    ->sort("desc")
    ->footerText("Name")
    ->footer("count")
    ->textAlign("right")
    ->allowNullValue(true)
    ->shouldUpdate(function($valueToUpdate){
        return $valueToUpdate!=$this->value();//Update when value is changed only
    })
    ->processValueToDatabase(function($valueToUpdate){
        //By default we update what user input into database, but we can change by return new value
        return $valueToUpdate;
    })

Extra fields #

Image #

The Image field have some special properties which will be used by CreateScreen and UpdateScreen.

Since the Image use FileUploader as default input Widget, it has some following property for faster setup FileUploader.

Nametypedefaultdescription
acceptarrayList of accepted file extension
notAcceptarray["php"]List of not-accepted file extension
saveToFolderstringThe location of folder that uploaded image will be stored

Password #

Password is a field designed to work with password field in your database. It will display password in a masked text and support encrypting raw password before update to database.

Nametypedefaultdescription
maskedTextstring********The masked text to hide password value
Password::create("password")
    ->maskedText("********")
    ->processValueToDatabase(function($password){
        return md5($password);
    }), 

Assign input to field #

Auto assign #

A field comes with an input element shown on UpdateScreen and CreateScreen. By default, the field will use TextBox as its input box. For some special field like DateTime or Date, the DateRangePicker will be used. The Image field will use the FileUploader.

Manual assign #

In some cases, you want to set your own input for a field or simply assign different setting to the input of the field, you can use the inputWidget() to set.

Example:

    Text::create("country")
        ->inputWidget(
            Select::create()
            ->dataSource(function(){
                return [
                    "United State"=>"US",
                    "Germany"=>"DE",
                ];
            })
        )

Validators #

Sometime the inputs from user in UpdateScreen and CreateScreen needed are to be validated. You can provide list of validators in to validators property of Field. Those validators will be used to validate the input of field in CreateScreen and UpdateScreen.

Example:

Text::create("email")
    ->validators([
        RequiredFieldValidator::create(),
        EmailValidator::create(),
    ])

Above settings will make sure that the email is never put empty and the input text should be in correct email format.

Learn more about Dashboard's Validators

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.