Editor PHP 2.0.8

Field extends Ext

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

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 {@see 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.
apply()  : mixed
Check to see if a field should be used for a particular action (get or set).
dbField()  : mixed
Get / set the DB field name.
get()  : mixed
Get / set the 'get' property of the field.
getFormatter()  : mixed
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()  : mixed
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()  : mixed
Get / set the 'set' property of the field.
setFormatter()  : mixed
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.
val()  : mixed
Get the value of the field, taking into account if it is coming from the DB or from a POST. If formatting has been specified for this field, it will be applied here.
validator()  : mixed
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()  : 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

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

public mixed SET_BOTH = 'both'

SET_CREATE

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

public mixed SET_CREATE = 'create'

SET_EDIT

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

public mixed SET_EDIT = 'edit'

SET_NONE

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

public mixed SET_NONE = 'none'

Methods

__construct()

Field instance constructor.

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

@param string $dbField Name of the database column

Parameters
$dbField : mixed = null
$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

apply()

Check to see if a field should be used for a particular action (get or set).

public apply(string $action[, mixed $data = null ]) : mixed

Called by the Editor / Join class instances - not expected for general consumption - internal.

Parameters
$action : string

Direction that the data is travelling - 'get' is reading DB data, create and edit for writing to the DB @param array $data Data submitted from the client-side when setting. @return boolean true if the field should be used in the get / set. @internal

$data : mixed = null
Return values
mixed

dbField()

Get / set the DB field name.

public dbField([string $_ = null ]) : mixed

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 string|self The name of the db field if no parameter is given, or self if used as a setter.

Return values
mixed

get()

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

public get([bool $_ = null ]) : mixed

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 boolean|self The get property if no parameter is given, or self if used as a setter.

Return values
mixed

getFormatter()

Get formatter for the field's data.

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

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(). @param mixed $opts 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 callable|string|self The get formatter if no parameter is given, or self if used as a setter.

$opts : mixed = null
Return values
mixed

getValue()

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()

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!

Return values
Editor|Field|Join|Upload

class @static

instantiate()

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.

Return values
Editor|Field|Join|Upload

Instantiated class @static

name()

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

public name([string $_ = null ]) : mixed

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 string|self The name property if no parameter is given, or self if used as a setter.

Return values
mixed

options()

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()

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()

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()

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

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

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 string|self The set property if no parameter is given, or self if used as a setter.
Return values
mixed

setFormatter()

Set formatter for the field's data.

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

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(). @param mixed $opts 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 callable|string|self The set formatter if no parameter is given, or self if used as a setter.

$opts : mixed = null
Return values
mixed

setValue()

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()

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.

val()

Get the value of the field, taking into account if it is coming from the DB or from a POST. If formatting has been specified for this field, it will be applied here.

public val(string $direction, mixed $data) : mixed

Called by the Editor / Join class instances - not expected for general consumption - internal.

Parameters
$direction : string

Direction that the data is travelling - 'get' is reading data, and 'set' is writing it to the DB. @param array $data Data submitted from the client-side when setting or the data for the row when getting data from the DB. @return string Value for the field @internal

$data : mixed
Return values
mixed

validator()

Get / set the 'validator' of the field.

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

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(). @param mixed $opts 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 callable|string|self The validation method if no parameter is given, or self if used as a setter.

$opts : mixed = null
Return values
mixed

xss()

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()

Perform XSS prevention on an input.

public xssSafety(mixed $val) : string
Parameters
$val : mixed

Value to be escaped

Return values
string

Safe value

_getSet()

Common getter / setter function for DataTables classes.

protected _getSet(mixed &$prop, mixed $val[, mixed $array = false ]) : 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 @param mixed $val The value to set - if given as null, then we assume that the function is being used as a getter. @param boolean $array 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 self|mixed Class instance if setting (allowing chaining), or the value requested if getting.

$val : mixed
$array : mixed = false
Return values
mixed

_propExists()

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()

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()

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
throws
Exception

Information about duplicate properties

private
Return values
mixed

Search results