Editor PHP 2.2.2

Field extends Ext
in package

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

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

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

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

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

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!

Tags
static
Return values
Editor|Field|Join|Upload —

class

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.

Tags
static
Return values
Editor|Field|Join|Upload —

Instantiated class

name()

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

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

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

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.

validator()

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

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

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
private
Return values
mixed — 

        

        
    




    

    

                

    

        

            
Search results