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 DataTables\Editor\Editor::field and DataTables\Editor\Join::field()
methods to describe what fields should be interacted with by the
editable table.
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( $dbField = null, $name = null )
Field instance constructor.
Field instance constructor.
Parameters
- $dbField
string
$dbField Name of the database column
- $name
string
$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|self
|
#
dbField( $_ = 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
- $_
string
$_ Value to set if using as a setter.
Returns
string|self
The name of the db field if no parameter is given, or self if used as a
setter.
|
public
|
boolean|self
|
#
get( $_ = 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
- $_
boolean
$_ Value to set if using as a setter.
Returns
boolean|self
The get property if no parameter is given, or self if used as a setter.
|
public
|
function|string|self
|
#
getFormatter( $_ = null, $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
- $_
function|string
$_ 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
$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
function|string|self
The get formatter if no parameter is given, or self if used as a setter.
|
public
|
function|string|self
|
#
getValue( $_ = 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
- $_
function|string|number
$_ Value to set, or no value to use as a getter
Returns
function|string|self
Value if used as a getter, or self if used as a setter.
|
public
|
string|self
|
#
name( $_ = 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
- $_
string
$_ Value to set if using as a setter.
Returns
string|self
The name property if no parameter is given, or self if used as a setter.
|
public
|
DataTables\Editor\Field
|
#
options( $table, $value = null, $label = 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
string|function
$table Database table name to use to get the paired data from, or a closure
function if providing a method
- $value
string
$value Table column name that contains the pair's value. Not used if the
first parameter is given as a closure
- $label
string
$label Table column name that contains the pair's label. Not used if the
first parameter is given as a closure
Returns
|
public
|
string|self
|
#
set( $_ = 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
- $_
string|boolean
$_ 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_NONE * false
- Same as Field::SET_BOTH * 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|self
The set property if no parameter is given, or self if used as a setter.
|
public
|
function|string|self
|
#
setFormatter( $_ = null, $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
- $_
function|string
$_ 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
$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
function|string|self
The set formatter if no parameter is given, or self if used as a setter.
|
public
|
function|string|self
|
#
setValue( $_ = 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
- $_
function|string|number
$_ Value to set, or no value to use as a getter
Returns
function|string|self
Value if used as a getter, or self if used as a setter.
|
public
|
function|string|self
|
#
validator( $_ = null, $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
- $_
function|string
$_ 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
$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
function|string|self
The validation method if no parameter is given, or self if used as a
setter.
|