# Class Field

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.

  DataTables\Ext
  DataTables\Editor\Field

Namespace: DataTables\Editor
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 `DataTables\Editor\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' )

Located at Editor/Field.php

Methods summary
`public` | # `__construct( string $dbField = null, string $name = null )` Field instance constructor. Field instance constructor. #### Parameters $dbField Name of the database column $name 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.
`public string|`DataTables\Editor\Field`` | # `dbField( string $_ = null )` Get / set the DB field name. Get / set the DB field name. 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 $_ Value to set if using as a setter. #### Returns string|`DataTables\Editor\Field` The name of the db field if no parameter is given, or self if used as a setter.
`public boolean|`DataTables\Editor\Field`` | # `get( boolean $_ = null )` Get / set the 'get' property of the field. Get / set the 'get' property of the field. A field can be marked as write only when setting the get property to false here. #### Parameters $_ Value to set if using as a setter. #### Returns boolean|`DataTables\Editor\Field` The get property if no parameter is given, or self if used as a setter.
`public callable|string|`DataTables\Editor\Field`` | # `getFormatter( callable|string $_ = null, mixed $opts = null )` Get formatter for the field's data. Get formatter for the field's data. 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 `DataTables\Editor\Format` class which can be used directly with this method. #### Parameters $_ 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 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. #### Returns callable|string|`DataTables\Editor\Field` The get formatter if no parameter is given, or self if used as a setter.
`public callable|string|`DataTables\Editor\Field`` | # `getValue( callable|string|number $_ = null )` 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. 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. #### Parameters $_ Value to set, or no value to use as a getter #### Returns callable|string|`DataTables\Editor\Field` Value if used as a getter, or self if used as a setter.
`public string|`DataTables\Editor\Field`` | # `name( string $_ = null )` Get / set the 'name' property of the field. Get / set the 'name' property of the field. 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 $_ Value to set if using as a setter. #### Returns string|`DataTables\Editor\Field` The name property if no parameter is given, or self if used as a setter.
`public `DataTables\Editor\Field`` | # `options( string|callable $table = null, string $value = null, string $label = null, callable $condition = null, callable $format = null, string $order = null )` 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. 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. 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 Database table name to use to get the paired data from, or a closure function if providing a method $value Table column name that contains the pair's value. Not used if the first parameter is given as a closure $label Table column name that contains the pair's label. Not used if the first parameter is given as a closure $condition Function that will add `where` conditions to the query $format Function will render each label $order SQL ordering #### Returns `DataTables\Editor\Field` Self for chaining
`public string|`DataTables\Editor\Field`` | # `set( string|boolean $_ = null )` Get / set the 'set' property of the field. Get / set the 'set' property of the field. 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 $_ 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 #### Returns string|`DataTables\Editor\Field` The set property if no parameter is given, or self if used as a setter.
`public callable|string|`DataTables\Editor\Field`` | # `setFormatter( callable|string $_ = null, mixed $opts = null )` Set formatter for the field's data. Set formatter for the field's data. 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 `DataTables\Editor\Format` class which can be used directly with this method. #### Parameters $_ 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 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. #### Returns callable|string|`DataTables\Editor\Field` The set formatter if no parameter is given, or self if used as a setter.
`public callable|string|`DataTables\Editor\Field`` | # `setValue( callable|string|number $_ = null )` 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. 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. #### Parameters $_ Value to set, or no value to use as a getter #### Returns callable|string|`DataTables\Editor\Field` Value if used as a getter, or self if used as a setter.
`public `DataTables\Editor\Upload`|`DataTables\Editor\Field`` | # `upload( `DataTables\Editor\Upload` $_ = null )` Get / set the upload class for this field. Get / set the upload class for this field. #### Parameters $_ Upload class if used as a setter #### Returns `DataTables\Editor\Upload`|`DataTables\Editor\Field` Value if used as a getter, or self if used as a setter.
`public callable|string|`DataTables\Editor\Field`` | # `validator( callable|string $_ = null, mixed $opts = null )` Get / set the 'validator' of the field. Get / set the 'validator' of the field. 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 `DataTables\Editor\Validate` class which can be used directly with this method. #### Parameters $_ 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 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. #### Returns callable|string|`DataTables\Editor\Field` The validation method if no parameter is given, or self if used as a setter.
`public `DataTables\Editor\Field`` | # `xss( callable|false $xssFormatter )` Set a formatting method that will be used for XSS checking / removal. This should be a function that takes a single argument (the value to be cleaned) and returns the cleaned value. Set a formatting method that will be used for XSS checking / removal. 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 XSS cleaner function, use `false` or `null` to disable XSS cleaning. #### Returns `DataTables\Editor\Field` Self for chaining.
`public string` | # `xssSafety( mixed $val )` Perform XSS prevention on an input. Perform XSS prevention on an input. #### Parameters $val Value to be escaped #### Returns string Safe value

Methods inherited from DataTables\Ext
`_getSet(), _propExists(), _readProp(), _writeProp(), inst(), instantiate()`

Constants summary
`string` | `SET_NONE` Set option flag (`set()`) - do not set data Set option flag (`set()`) - do not set data | # `'none'`
`string` | `SET_BOTH` Set option flag (`set()`) - write to database on both create and edit Set option flag (`set()`) - write to database on both create and edit | # `'both'`
`string` | `SET_CREATE` Set option flag (`set()`) - write to database only on create Set option flag (`set()`) - write to database only on create | # `'create'`
`string` | `SET_EDIT` Set option flag (`set()`) - write to database only on edit Set option flag (`set()`) - write to database only on edit | # `'edit'`