TableField

Introduction

[api:TableField] behaves in the same manner as [api:TableListField], however allows the editing of existing and adding of new rows. The data is saved back by the surrounding form-saving (mostly EditForm->save).

See [api:TableListField] for more documentation on the base-class

Usage

Add hidden default data

Please use TableField->setExtraData() to specify additional (non-editable) data. You might use the following code that shows the Player of Team with a particular Team ID and automatically saves new Players into this Team.

In this example, you'll note that we're setting TeamID to $this->ID. This works well if you're including a TableField as an editable field on a getCMSFields() call.

:::php
$myTableField = new TableField(
  'MyTableField', // fieldName
  'Player', // sourceType
  array(
    'FirstName'=>'First Name',
    'Surname'=>'Surname'
  ), // fieldList
  array(
    'FirstName'=>'TextField',
    'Surname'=>'TextField'
  ), // fieldTypes
  null, // filterField (legacy)
  "Player.TeamID",
  $this->ID
);
// add some HiddenFields thats saved with each new row
$myTableField->setExtraData(array(
  'TeamID' => $this->ID ? $this->ID : '$RecordID'
));

The '$RecordID' value is used when building forms that create new records. It will be populated with whatever record id is created.

Row Transformation

You can apply a [api:FormTransformation] to any given field, based on a eval()ed php-rule. You can access all columns on the generated DataObjects here.

:::php
$myTF->setTransformationConditions(array(
  "PlayerName" => array(
    "rule" => '$PlayerStatus == "Retired" || $PlayerStatus == "Injured"',
    "transformation" => "performReadonlyTransformation"
  )
));

Required Fields

Due to the nested nature of this fields dataset, you can't set any required columns as usual with the [api:RequiredFields]** on the TableField-instance for this. Note: You still have to attach some form of [api:Validator] to the form to trigger any validation on this field.

Nested Table Fields

When you have [api:TableField] inside a [api:ComplexTableField], the parent ID may not be known in your getCMSFields() method. In these cases, you can set a value to '$RecordID' in your [api:TableField] extra data, and this will be populated with the newly created record id upon save.

Known Issues

A [api:TableField] doesn't reload any submitted form-data if the saving is interrupted by a failed validation. After refreshing the form with the validation-errors, the [api:TableField] will be blank again.
You can't add visible default data to columns in a [api:TableField], please use setExtraData

API Documentation

[api:TableField]

2.7 KiB Raw Blame History