Menu

## Field extends Ext
in package

Field.php : 58

Field definitions for the DataTables Editor.

Each Database column that is used with Editor can be described with this Field method (both for Editor and Join instances). It basically tells Editor what table column to use, how to format the data and if you want to read and/or write this column.

Field instances are used with the Editor->field() and Join->field() methods to describe what fields should be interacted with by the editable table.

##### Tags

example

  Simply get a column with the name "city". No validation is performed.

        Field::inst( 'city' )

  @example Get a column with the name "first_name" - when edited a value must be given due to the "required" validation from the Validate class.

        Field::inst( 'first_name' )->validator( 'Validate::required' )

  @example Working with a date field, which is validated, and also has get and set formatters.

        Field::inst( 'registered_date' )
            ->validator( 'Validate::dateFormat', 'D, d M y' )
            ->getFormatter( 'Format::date_sql_to_format', 'D, d M y' )
            ->setFormatter( 'Format::date_format_to_sql', 'D, d M y' )

  @example Using an alias in the first parameter

        Field::inst( 'name.first as first_name' )

### Table of Contents

SET_BOTH = 'both'
  Set option flag (`set()`) - write to database on both create and edit
SET_CREATE = 'create'
  Set option flag (`set()`) - write to database only on create
SET_EDIT = 'edit'
  Set option flag (`set()`) - write to database only on edit
SET_NONE = 'none'
  Set option flag (`set()`) - do not set data
__construct() : mixed
  Field instance constructor.
dbField() : string|self
  Get / set the DB field name.
get() : bool|self
  Get / set the 'get' property of the field.
getFormatter() : callable|string|self
  Get formatter for the field's data.
getValue() : callable|string|self
  Get / set a get value. If given, then this value is used to send to the client-side, regardless of what value is held by the database.
inst() : Editor|Field|Join|Upload
  Static method to instantiate a new instance of a class (shorthand of 'instantiate').
instantiate() : Editor|Field|Join|Upload
  Static method to instantiate a new instance of a class.
name() : string|self
  Get / set the 'name' property of the field.
options() : Field
  Get a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.
searchBuilderOptions() : self
  Get a list of values that can be used for the options list in SearchBuilder.
searchPaneOptions() : self
  Get a list of values that can be used for the options list in SearchPanes.
set() : string|self
  Get / set the 'set' property of the field.
setFormatter() : callable|string|self
  Set formatter for the field's data.
setValue() : callable|string|self
  Get / set a set value. If given, then this value is used to write to the database regardless of what data is sent from the client-side.
upload() : Upload|self
  Get / set the upload class for this field.
validator() : callable|string|self
  Get / set the 'validator' of the field.
xss() : Field
  Set a formatting method that will be used for XSS checking / removal.
xssSafety() : string
  Perform XSS prevention on an input.
_getSet() : self|mixed
  Common getter / setter function for DataTables classes.
_propExists() : bool
  Determine if a property is available in a data set (allowing `null` to be a valid value).
_readProp() : mixed
  Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.
_writeProp() : mixed
  Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).

### Constants

#### SET_BOTH

Field.php : 68

Set option flag (`set()`) - write to database on both create and edit

`public mixed SET_BOTH = 'both'`

#### SET_CREATE

Field.php : 71

Set option flag (`set()`) - write to database only on create

`public mixed SET_CREATE = 'create'`

#### SET_EDIT

Field.php : 74

Set option flag (`set()`) - write to database only on edit

`public mixed SET_EDIT = 'edit'`

#### SET_NONE

Field.php : 65

Set option flag (`set()`) - do not set data

`public mixed SET_NONE = 'none'`

### Methods

#### __construct()

Field.php : 88

Field instance constructor.

`public __construct([string $dbField = null ][, string $name = null ]) : mixed`

##### Parameters

$dbField : string = null

  Name of the database column

$name : string = null

  Name to use in the JSON output from Editor and the HTTP submit from the client-side when editing. If not given then the $dbField name is used.

##### Return values

mixed —

#### dbField()

Field.php : 188

Get / set the DB field name.

`public dbField([string $_ = null ]) : string|self`

Note that when used as a setter, an alias can be given for the field using the SQL `as` keyword - for example: `firstName as name`. In this situation the dbField is set to the field name before the `as`, and the field's name (`name()`) is set to the name after the `as`.

As a result of this, the following constructs have identical functionality:

Field::inst( 'firstName as name' ); Field::inst( 'firstName', 'name' );

##### Parameters

$_ : string = null

  Value to set if using as a setter.

##### Return values

string|self —

The name of the db field if no parameter is given, or self if used as a setter.

#### get()

Field.php : 217

Get / set the 'get' property of the field.

`public get([bool $_ = null ]) : bool|self`

A field can be marked as write only when setting the get property to false here.

##### Parameters

$_ : bool = null

  Value to set if using as a setter.

##### Return values

bool|self —

The get property if no parameter is given, or self if used as a setter.

#### getFormatter()

Field.php : 244

Get formatter for the field's data.

`public getFormatter([callable|string $_ = null ][, mixed $opts = null ]) : callable|string|self`

When the data has been retrieved from the server, it can be passed through a formatter here, which will manipulate (format) the data as required. This can be useful when, for example, working with dates and a particular format is required on the client-side.

Editor has a number of formatters available with the Format class which can be used directly with this method.

##### Parameters

$_ : callable|string = null

  Value to set if using as a setter. Can be given as a closure function or a string with a reference to a function that will be called with call_user_func().

$opts : mixed = null

  Variable that is passed through to the get formatting function - can be useful for passing through extra information such as date formatting string, or a required flag. The actual options available depend upon the formatter used.

##### Return values

callable|string|self —

The get formatter if no parameter is given, or self if used as a setter.

#### getValue()

Field.php : 263

Get / set a get value. If given, then this value is used to send to the client-side, regardless of what value is held by the database.

`public getValue([callable|string|number $_ = null ]) : callable|string|self`

##### Parameters

$_ : callable|string|number = null

  Value to set, or no value to use as a getter

##### Return values

callable|string|self —

Value if used as a getter, or self if used as a setter.

#### inst()

Ext.php : 55

Static method to instantiate a new instance of a class (shorthand of 'instantiate').

`public static inst() : Editor|Field|Join|Upload`

This method performs exactly the same actions as the 'instantiate' static method, but is simply shorter and easier to type!

##### Tags

static

##### Return values

Editor|Field|Join|Upload —

class

#### instantiate()

Ext.php : 34

Static method to instantiate a new instance of a class.

`public static instantiate() : Editor|Field|Join|Upload`

A factory method that will create a new instance of the class that has extended 'Ext'. This allows classes to be instantiated and then chained - which otherwise isn't available until PHP 5.4. If using PHP 5.4 or later, simply create a 'new' instance of the target class and chain methods as normal.

##### Tags

static

##### Return values

Editor|Field|Join|Upload —

Instantiated class

#### name()

Field.php : 281

Get / set the 'name' property of the field.

`public name([string $_ = null ]) : string|self`

The name is typically the same as the dbField name, since it makes things less confusing(!), but it is possible to set a different name for the data which is used in the JSON returned to DataTables in a 'get' operation and the field name used in a 'set' operation.

##### Parameters

$_ : string = null

  Value to set if using as a setter.

##### Return values

string|self —

The name property if no parameter is given, or self if used as a setter.

#### options()

Field.php : 307

Get a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.

`public options([string|callable $table = null ][, string $value = null ][, string $label = null ][, callable $condition = null ][, callable $format = null ][, string $order = null ]) : Field`

Note that this is for simple 'label / value' pairs only. For more complex data, including pairs that require joins and where conditions, use a closure to provide a query

##### Parameters

$table : string|callable = null

  Database table name to use to get the paired data from, or a closure function if providing a method

$value : string = null

  Table column name that contains the pair's value. Not used if the first parameter is given as a closure

$label : string = null

  Table column name that contains the pair's label. Not used if the first parameter is given as a closure

$condition : callable = null

  Function that will add `where` conditions to the query

$format : callable = null

  Function will render each label

$order : string = null

  SQL ordering

##### Return values

Field —

Self for chaining

#### searchBuilderOptions()

Field.php : 379

Get a list of values that can be used for the options list in SearchBuilder.

`public searchBuilderOptions([SearchBuilderOptions|callable $sbInput = null ]) : self`

##### Parameters

$sbInput : SearchBuilderOptions|callable = null

  SearchBuilderOptions instance or a closure function if providing a method

##### Return values

self —

#### searchPaneOptions()

Field.php : 352

Get a list of values that can be used for the options list in SearchPanes.

`public searchPaneOptions([SearchPaneOptions|callable $spInput = null ]) : self`

##### Parameters

$spInput : SearchPaneOptions|callable = null

  SearchPaneOptions instance or a closure function if providing a method

##### Return values

self —

#### set()

Field.php : 421

Get / set the 'set' property of the field.

`public set([string|bool $_ = null ]) : string|self`

A field can be marked as read only using this option, to be set only during an create or edit action or to be set during both actions. This provides the ability to have fields that are only set when a new row is created (for example a "created" time stamp).

##### Parameters

$_ : string|bool = null

  Value to set when the method is being used as a setter (leave as undefined to use as a getter). This can take the value of:

  - `true` - Same as `Field::SET_BOTH`
  - `false` - Same as `Field::SET_NONE`
  - `Field::SET_BOTH` - Set the database value on both create and edit commands
  - `Field::SET_NONE` - Never set the database value
  - `Field::SET_CREATE` - Set the database value only on create
  - `Field::SET_EDIT` - Set the database value only on edit

##### Return values

string|self —

The set property if no parameter is given, or self if used as a setter.

#### setFormatter()

Field.php : 454

Set formatter for the field's data.

`public setFormatter([callable|string $_ = null ][, mixed $opts = null ]) : callable|string|self`

When the data has been retrieved from the server, it can be passed through a formatter here, which will manipulate (format) the data as required. This can be useful when, for example, working with dates and a particular format is required on the client-side.

Editor has a number of formatters available with the Format class which can be used directly with this method.

##### Parameters

$_ : callable|string = null

  Value to set if using as a setter. Can be given as a closure function or a string with a reference to a function that will be called with call_user_func().

$opts : mixed = null

  Variable that is passed through to the get formatting function - can be useful for passing through extra information such as date formatting string, or a required flag. The actual options available depend upon the formatter used.

##### Return values

callable|string|self —

The set formatter if no parameter is given, or self if used as a setter.

#### setValue()

Field.php : 473

Get / set a set value. If given, then this value is used to write to the database regardless of what data is sent from the client-side.

`public setValue([callable|string|number $_ = null ]) : callable|string|self`

##### Parameters

$_ : callable|string|number = null

  Value to set, or no value to use as a getter

##### Return values

callable|string|self —

Value if used as a getter, or self if used as a setter.

#### upload()

Field.php : 486

Get / set the upload class for this field.

`public upload([Upload $_ = null ]) : Upload|self`

##### Parameters

$_ : Upload = null

  Upload class if used as a setter

##### Return values

Upload|self —

Value if used as a getter, or self if used as a setter.

#### validator()

Field.php : 515

Get / set the 'validator' of the field.

`public validator([callable|string $_ = null ][, mixed $opts = null ]) : callable|string|self`

The validator can be used to check if any abstract piece of data is valid or not according to the given rules of the validation function used.

Multiple validation options can be applied to a field instance by calling this method multiple times. For example, it would be possible to have a 'required' validation and a 'maxLength' validation with multiple calls.

Editor has a number of validation available with the Validate class which can be used directly with this method.

##### Parameters

$_ : callable|string = null

  Value to set if using as the validation method. Can be given as a closure function or a string with a reference to a function that will be called with call_user_func().

$opts : mixed = null

  Variable that is passed through to the validation function - can be useful for passing through extra information such as date formatting string, or a required flag. The actual options available depend upon the validation function used.

##### Return values

callable|string|self —

The validation method if no parameter is given, or self if used as a setter.

#### xss()

Field.php : 549

Set a formatting method that will be used for XSS checking / removal.

`public xss(callable|false $xssFormatter) : Field`

This should be a function that takes a single argument (the value to be cleaned) and returns the cleaned value.

Editor will use HtmLawed by default for this operation, which is built into the software and no additional configuration is required, but a custom function can be used if you wish to use a different formatter such as HTMLPurifier.

If you wish to disable this option (which you would only do if you are absolutely confident that your validation will pick up on any XSS inputs) simply provide a closure function that returns the value given to the function. This is not recommended.

##### Parameters

$xssFormatter : callable|false

  XSS cleaner function, use `false` or `null` to disable XSS cleaning.

##### Return values

Field —

Self for chaining.

#### xssSafety()

Field.php : 844

Perform XSS prevention on an input.

`public xssSafety(mixed $val) : string`

##### Parameters

$val : mixed

  Value to be escaped

##### Return values

string —

Safe value

#### _getSet()

Ext.php : 81

Common getter / setter function for DataTables classes.

`protected _getSet(mixed &$prop, mixed $val[, bool $array = false ]) : self|mixed`

This getter / setter method makes building getter / setting methods easier, by abstracting everything to a single function call.

##### Parameters

$prop : mixed

  The property to set

$val : mixed

  The value to set - if given as null, then we assume that the function is being used as a getter.

$array : bool = false

  Treat the target property as an array or not (default false). If used as an array, then values passed in are added to the $prop array.

##### Return values

self|mixed —

Class instance if setting (allowing chaining), or the value requested if getting.

#### _propExists()

Ext.php : 113

Determine if a property is available in a data set (allowing `null` to be a valid value).

`protected _propExists(string $name, array<string|int, mixed> $data) : bool`

##### Parameters

$name : string

  Javascript dotted object name to write to

$data : array<string|int, mixed>

  Data source array to read from

##### Tags

private

##### Return values

bool —

true if present, false otherwise

#### _readProp()

Ext.php : 152

Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.

`protected _readProp(string $name, array<string|int, mixed> $data) : mixed`

##### Parameters

$name : string

  Javascript dotted object name to write to

$data : array<string|int, mixed>

  Data source array to read from

##### Tags

private

##### Return values

mixed —

The read value, or null if no value found.

#### _writeProp()

Ext.php : 196

Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).

`protected _writeProp(array<string|int, mixed> &$out, string $name, mixed $value) : mixed`

##### Parameters

$out : array<string|int, mixed>

  Array to write the data to

$name : string

  Javascript dotted object name to write to

$value : mixed

  Value to write

##### Tags

private

##### Return values

mixed —

## Search results