Editor PHP 2.3.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.

  new Field( '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.

  (new Field( 'first_name' ))->validator( 'Validate::required' )
example

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

  (new Field( '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

  new Field( 'name.first as first_name' )

Table of Contents

Constants

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

Methods

__construct()  : mixed
Field instance constructor.
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()  : mixed
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()  : static
Static method to instantiate a new instance of a class (shorthand of 'instantiate').
instantiate()  : static
Static method to instantiate a new instance of a class.
name()  : mixed
Get / set the 'name' property of the field.
options()  : mixed
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()  : mixed
Get a list of values that can be used for the options list in SearchBuilder.
searchPaneOptions()  : mixed
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()  : mixed
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()  : mixed
Get / set the upload class for this field.
validator()  : mixed
Get / set the 'validator' of the field.
xss()  : $this
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([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.

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:

new Field( 'firstName as name' ); new Field( 'firstName', 'name' );

Parameters
$_ : string = null

Value to set if using as a setter.

Return values
mixed —

The name of the db field if no parameter is given.

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

The get property if no parameter is given.

getFormatter()

Get formatter for the field's data.

public getFormatter([mixed $_ = 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
$_ : mixed = null
$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
mixed —

The get formatter if no parameter is given.

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([mixed $_ = null ]) : mixed
Parameters
$_ : mixed = null
Return values
mixed —

Value if used as a getter.

inst()

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

public static inst() : static

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

Return values
static —

class

instantiate()

Static method to instantiate a new instance of a class.

public static instantiate() : static

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
static —

Instantiated class

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

The name property if no parameter is given.

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([mixed $table = null ][, string $value = null ][, string $label = null ][, mixed $condition = null ][, mixed $format = null ][, string $order = null ]) : mixed

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 : mixed = null
$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 : mixed = null
$format : mixed = null
$order : string = null

SQL ordering

searchBuilderOptions()

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

public searchBuilderOptions([mixed $sbInput = null ]) : mixed
Parameters
$sbInput : mixed = null

searchPaneOptions()

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

public searchPaneOptions([mixed $spInput = null ]) : mixed
Parameters
$spInput : mixed = null

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

The set property if no parameter is given.

setFormatter()

Set formatter for the field's data.

public setFormatter([mixed $_ = 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
$_ : mixed = null
$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
mixed —

The set formatter if no parameter is given.

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([mixed $_ = null ]) : mixed
Parameters
$_ : mixed = null
Return values
mixed —

Value if used as a getter.

upload()

Get / set the upload class for this field.

public upload([Upload $_ = null ]) : mixed
Parameters
$_ : Upload = null

Upload class if used as a setter

Return values
mixed —

Value if used as a getter.

validator()

Get / set the 'validator' of the field.

public validator([mixed $_ = 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
$_ : mixed = null
$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
mixed —

The validation method if no parameter is given.

xss()

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

public xss(mixed $xssFormatter) : $this

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 : mixed
Return values
$this

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

_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

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

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


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results