DataTables Editor base class for creating editable tables.
Editor class instances are capable of servicing all of the requests that
DataTables and Editor will make from the client-side - specifically:
- Get data
- Create new record
- Edit existing record
- Delete existing records
The Editor instance is configured with information regarding the database
table fields that you which to make editable, and other information needed to
read and write to the database (table name for example!).
This documentation is very much focused on describing the API presented by
these DataTables Editor classes. For a more general overview of how the Editor
class is used, and how to install Editor on your server, please refer to the
Editor manual.
Methods summary
public static
|
string
|
#
action( $http )
Determine the request type from an HTTP request.
Determine the request type from an HTTP request.
Parameters
- $http
array
$http Typically $_POST, but can be any array used to carry an Editor
payload
Returns
string
Editor::ACTION_READ , Editor::ACTION_CREATE ,
Editor::ACTION_EDIT or Editor::ACTION_DELETE
indicating the request type.
|
public
|
|
#
__construct( $db = null, $table = null, $pkey = null )
Constructor.
Parameters
- $db
DataTables\Database
$db An instance of the DataTables Database class that we can use for the DB
connection. Can be given here or with the 'db' method.
456
- $table
string|array
$table The table name in the database to read and write information from and
to. Can be given here or with the 'table' method.
- $pkey
string
$pkey Primary key column name in the table given in the $table parameter. Can
be given here or with the 'pkey' method.
|
public
|
array
|
#
data( )
Get the data constructed in this instance.
Get the data constructed in this instance.
This will get the PHP array of data that has been constructed for the command
that has been processed by this instance. Therefore only useful after process
has been called.
Returns
array
Processed data array.
|
public
|
DataTables\Database |self
|
#
db( $_ = null )
Get / set the DB connection instance
Get / set the DB connection instance
Parameters
- $_
DataTables\Database
$_ DataTable's Database class instance to use for database connectivity. If
not given, then used as a getter.
Returns
DataTables\Database |self
The Database connection instance if no parameter is given, or self if used as
a setter.
|
public
|
DataTables\Editor\Field[] |self
|
#
field( $_ = null )
Get / set field instances.
Get / set field instances.
The list of fields designates which columns in the table that Editor will
work with (both get and set).
Parameters
Returns
See
|
public
|
DataTables\Editor\Field[] |self
|
#
fields( $_ = null )
Get / set field instances.
|
public
|
string|self
|
#
idPrefix( $_ = null )
Get / set the DOM prefix.
Get / set the DOM prefix.
Typically primary keys are numeric and this is not a valid ID value in an
HTML document - is also increases the likelihood of an ID clash if multiple
tables are used on a single page. As such, a prefix is assigned to the primary
key value for each row, and this is used as the DOM ID, so Editor can track
individual rows.
Parameters
- $_
string
$_ Primary key's name. If not given, then used as a getter.
Returns
string|self
Primary key value if no parameter is given, or self if used as a setter.
|
public
|
array
|
#
inData( )
Get the data that is being processed by the Editor instance. This is only
useful once the process() method has been called, and is available
for use in validation and formatter methods.
Get the data that is being processed by the Editor instance. This is only
useful once the process() method has been called, and is available
for use in validation and formatter methods.
Returns
array
Data given to process() .
|
public
|
DataTables\Editor\Join[] |self
|
#
join( $_ = null )
Get / set join instances. Note that for the majority of use cases you will
want to use the leftJoin() method. It is significantly easier to
use if you are just doing a simple left join!
Get / set join instances. Note that for the majority of use cases you will
want to use the leftJoin() method. It is significantly easier to
use if you are just doing a simple left join!
The list of Join instances that Editor will join the parent table to (i.e.
the one that the DataTables\Editor::table() and DataTables\Editor::fields() methods refer to in this class
instance).
Parameters
Returns
See
|
public
|
string|self
|
#
json( $print = true )
Get the JSON for the data constructed in this instance.
Get the JSON for the data constructed in this instance.
Basically the same as the DataTables\Editor::data() method, but in this case we echo, or
return the JSON string of the data.
Parameters
- $print
boolean
$print Echo the JSON string out (true, default) or return it (false).
Returns
string|self
self if printing the JSON, or JSON representation of the processed data if
false is given as the first parameter.
|
public
|
self
|
#
jsonp( $callback = null )
Echo out JSONP for the data constructed and processed in this instance. This
is basically the same as DataTables\Editor::json() but wraps the return in a JSONP
callback.
Echo out JSONP for the data constructed and processed in this instance. This
is basically the same as DataTables\Editor::json() but wraps the return in a JSONP
callback.
Parameters
- $callback
string
$callback The callback function name to use. If not given or
null , then $_GET['callback'] is used (the jQuery
default).
Returns
|
public
|
self
|
#
leftJoin( $table, $field1, $operator, $field2 )
Add a left join condition to the Editor instance, allowing it to operate over
multiple tables. Multiple leftJoin() calls can be made for a single
Editor instance to join multiple tables.
Add a left join condition to the Editor instance, allowing it to operate over
multiple tables. Multiple leftJoin() calls can be made for a single
Editor instance to join multiple tables.
A left join is the most common type of join that is used with Editor so this
method is provided to make its use very easy to configure. Its parameters are
basically the same as writing an SQL left join statement, but in this case
Editor will handle the create, update and remove requirements of the join for
you:
- Create - On create Editor will insert the data into the primary table and
then into the joined tables - selecting the required data for each table.
- Edit - On edit Editor will update the main table, and then either update the
existing rows in the joined table that match the join and edit conditions, or
insert a new row into the joined table if required.
- Remove - On delete Editor will remove the main row and then loop over each
of the joined tables and remove the joined data matching the join link from the
main table.
Please note that when using join tables, Editor requires that you fully
qualify each field with the field's table name. SQL can result table names for
ambiguous field names, but for Editor to provide its full CRUD options, the
table name must also be given. For example the field first_name in
the table users would be given as
users.first_name .
Parameters
- $table
string
$table Table name to do a join onto
- $field1
string
$field1 Field from the parent table to use as the join link
- $operator
string
$operator Join condition (= , '<`, etc)
- $field2
string
$field2 Field from the child table to use as the join link
Returns
Example
Simple join:
->field(
Field::inst( 'users.first_name as myField' ),
Field::inst( 'users.last_name' ),
Field::inst( 'users.dept_id' ),
Field::inst( 'dept.name' )
)
->leftJoin( 'dept', 'users.dept_id', '=', 'dept.id' )
->process($_POST)
->json();
This is basically the same as the following SQL statement:
SELECT users.first_name, users.last_name, user.dept_id, dept.name
FROM users
LEFT JOIN dept ON users.dept_id = dept.id
|
public
|
string[]|self
|
#
table( $_ = null )
Get / set the table name.
Get / set the table name.
The table name designated which DB table Editor will use as its data source
for working with the database. Table names can be given with an alias, which can
be used to simplify larger table names. The field names would also need to
reflect the alias, just like an SQL query. For example: users as
a .
Parameters
- $_
string|array
$_,... Table names given as a single string, an array of strings or multiple
string parameters for the function.
Returns
string[]|self
Array of tables names, or self if used as a setter.
|
public
|
string|self
|
#
pkey( $_ = null )
Get / set the primary key.
Get / set the primary key.
The primary key must be known to Editor so it will know which rows are being
edited / deleted upon those actions. The default value is 'id'.
Parameters
- $_
string
$_ Primary key's name. If not given, then used as a getter.
Returns
string|self
Primary key value if no parameter is given, or self if used as a setter.
|
public
|
self
|
#
process( $data )
Process a request from the Editor client-side to get / set data.
Process a request from the Editor client-side to get / set data.
Parameters
- $data
array
$data Typically $_POST or $_GET as required by what is sent by Editor
Returns
self
|
public
|
boolean
|
#
validate( & $errors, $data )
Perform validation on a data set.
Perform validation on a data set.
Note that validation is performed on data only when the action is
create or edit . Additionally, validation is performed
on the _wire data_ - i.e. that which is submitted from the client, without
formatting. Any formatting required by setFormatter is performed
after the data from the client has been validated.
Parameters
- $errors
&array
$errors Output array to which field error information will be written. Each
element in the array represents a field in an error condition. These elements
are themselves arrays with two properties set; name and
status .
- $data
array
$data The format data to check
Returns
boolean
true if the data is valid, false if not.
|
public
|
string[]|self
|
#
where( $key = null, $value = null, $op = '=' )
Where condition to add to the query used to get data from the database.
Where condition to add to the query used to get data from the database.
Can be used in two different ways:
- Simple case:
where( field, value, operator )
- Complex:
where( fn )
The simple case is fairly self explanatory, a condition is applied to the
data that looks like field operator value (e.g. name =
'Allan' ). The complex case allows full control over the query conditions
by providing a closure function that has access to the database Query that
Editor is using, so you can use the where() ,
or_where() , and_where() and where_group()
methods as you require.
Please be very careful when using this method! If an edit made by a user
using Editor removes the row from the where condition, the result is undefined
(since Editor expects the row to still be available, but the condition removes
it from the result set).
Parameters
- $key
string|function
$key Single field name or a closure function
- $value
string
$value Single field value.
- $op
string
$op Condition operator: <, >, = etc
Returns
string[]|self
Where condition array, or self if used as a setter.
|
public
|
|
#
_ssp_field( $http, $index )
Convert a column index to a database field name - used for server-side
processing requests.
Convert a column index to a database field name - used for server-side
processing requests.
Parameters
- $http
array
$http HTTP variables (i.e. GET or POST)
- $index
integer
$index Index in the DataTables' submitted data
Private
// It is actually public for PHP 5.3 compatibility with a closure
Returns
string DB field name
|
public
|
|
#
_remove_table( $table, $ids, $pkey = null )
Delete one or more rows from the database for an individual table
Delete one or more rows from the database for an individual table
Parameters
- $table
string
$table Database table name to use
- $ids
array
$ids Array of ids to remove
- $pkey
string
$pkey Database column name to match the ids on for the delete condition. If
not given the instance's base primary key is used.
Private
|