Methods summary
public static
string
|
#
action( array $http, string $name = 'action' )
Determine the request type from an HTTP request.
Determine the request type from an HTTP request.
Parameters
- $http
Typically $_POST, but can be any array used to carry
an Editor payload - $name
- The parameter name that the action should be read from.
Returns
string Editor::ACTION_READ, Editor::ACTION_CREATE,
Editor::ACTION_EDIT or Editor::ACTION_DELETE indicating the request
type.
|
public
|
#
__construct( DataTables\Database $db = null, string|array $table = null, string|array $pkey = null )
Constructor.
Parameters
- $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
The table name in the database to read and write
information from and to. Can be given here or with the 'table' method. - $pkey
Primary key column name in the table given in
the $table parameter. Can be given here or with the 'pkey' method.
|
public
string|DataTables\Editor
|
#
actionName( string $_ = null )
Get / set the action name to read in HTTP parameters. This can be useful
to set if you are using a framework that uses the default name of action
for something else (e.g. WordPress).
Get / set the action name to read in HTTP parameters. This can be useful
to set if you are using a framework that uses the default name of action
for something else (e.g. WordPress).
Parameters
- $_
- to set. If not given, then used as a getter.
Returns
|
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|DataTables\Editor
|
#
db( DataTables\Database $_ = null )
Get / set the DB connection instance
Get / set the DB connection instance
Parameters
- $_
DataTable's Database class instance to use for database
connectivity. If not given, then used as a getter. Returns
|
public
boolean|DataTables\Editor
|
#
debug( boolean|mixed $_ = null, string $path = null )
Get / set debug mode and set a debug message.
Get / set debug mode and set a debug message.
It can be useful to see the SQL statements that Editor is using. This
method enables that ability. Information about the queries used is
automatically added to the output data array / JSON under the property
name debugSql.
This method can also be called with a string parameter, which will be
added to the debug information sent back to the client-side. This can
be useful when debugging event listeners, etc.
Parameters
- $_
Debug mode state. If not given, then used as a
getter. If given as anything other than a boolean, it will be added
to the debug information sent back to the client. - $path
- $path=null] Set an output path to log debug information
Returns
boolean| DataTables\EditorDebug mode state if no parameter is given, or
self if used as a setter or when adding a debug message.
|
public
DataTables\Editor\Field|DataTables\Editor\Field[]|DataTables\Editor
|
#
field( DataTables\Editor\Field|string $_ = null )
Get / set field instance.
Get / set field instance.
The list of fields designates which columns in the table that Editor will work
with (both get and set).
Parameters
- $_
$_... This parameter effects the return value of the
function:
* `null` - Get an array of all fields assigned to the instance
* `string` - Get a specific field instance whose 'name' matches the
field passed in
* DataTables\Editor\Field - Add a field to the instance's list of fields. This
can be as many fields as required (i.e. multiple arguments)
* `array` - An array of DataTables\Editor\Field instances to add to the list
of fields.
Returns
Throws
Exception
Unkown field error
See
|
public
DataTables\Editor\Field[]|DataTables\Editor
|
|
public
string|DataTables\Editor
|
#
idPrefix( string $_ = 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
- $_
- Primary key's name. If not given, then used as a getter.
Returns
string| DataTables\EditorPrimary 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[]|DataTables\Editor
|
#
join( DataTables\Editor\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|DataTables\Editor
|
#
json( boolean $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
Echo the JSON string out (true, default) or return it
(false). Returns
string| DataTables\Editorself if printing the JSON, or JSON representation of
the processed data if false is given as the first parameter.
|
public
DataTables\Editor
|
#
jsonp( string $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
The callback function name to use. If not given
or null, then $_GET['callback'] is used (the jQuery default). Returns
Throws
Exception
JSONP function name validation
|
public
DataTables\Editor
|
#
leftJoin( string $table, string $field1, string $operator, string $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
- Table name to do a join onto
- $field1
- Field from the parent table to use as the join link
- $operator
- Join condition (
=, '<`, etc)
- $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
boolean|DataTables\Editor
|
#
leftJoinRemove( boolean $_ = null )
Indicate if a remove should be performed on left joined tables when deleting
from the parent row. Note that this is disabled by default and will be
removed completely in v2. Use ON DELETE CASCADE in your database instead.
Indicate if a remove should be performed on left joined tables when deleting
from the parent row. Note that this is disabled by default and will be
removed completely in v2. Use ON DELETE CASCADE in your database instead.
Deprecated
Parameters
- $_
- Value to set. If not given, then used as a getter.
Returns
boolean| DataTables\EditorValue if no parameter is given, or
self if used as a setter.
|
public
DataTables\Editor
|
#
on( string $name, callable $callback )
Add an event listener. The Editor class will trigger an number of
events that some action can be taken on.
Add an event listener. The Editor class will trigger an number of
events that some action can be taken on.
Parameters
- $name
- Event name
- $callback
Callback function to execute when the event
occurs Returns
|
public
string|DataTables\Editor
|
#
pkey( string|array $_ = 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
- $_
Primary key's name. If not given, then used as a
getter. An array of column names can be given to allow composite keys to
be used. Returns
string| DataTables\EditorPrimary key value if no parameter is given, or
self if used as a setter.
|
public
string
|
#
pkeyToValue( string $row, boolean $flat = false )
Convert a primary key array of field values to a combined value.
Convert a primary key array of field values to a combined value.
Parameters
- $row
The row of data that the primary key value should
be extracted from. - $flat
Flag to indicate if the given array is flat
(useful for where conditions) or nested for join tables. Returns
string
The created primary key value.
Throws
Exception If one of the values that the primary key is made up
of cannot be found in the data set given, an Exception will be thrown.
|
public
array
|
#
pkeyToArray( string $value, boolean $flat = false, string[] $pkey = null )
Convert a primary key combined value to an array of field values.
Convert a primary key combined value to an array of field values.
Parameters
- $value
- The id that should be split apart
- $flat
Flag to indicate if the returned array should be
flat (useful for where conditions) or nested for join tables. - $pkey
The primary key name - will use the instance value
if not given Returns
array
Array of field values that the id was made up of.
Throws
Exception If the primary key value does not match the expected
length based on the primary key configuration, an exception will be
thrown.
|
public
DataTables\Editor
|
#
process( array $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
Typically $_POST or $_GET as required by what is sent
by Editor Returns
|
public
string[]|DataTables\Editor
|
#
readTable( string|array $_ = null )
The CRUD read table name. If this method is used, Editor will create from the
table name(s) given rather than those given by Editor->table(). This can be
a useful distinction to allow a read from a VIEW (which could make use of a
complex SELECT) while writing to a different table.
The CRUD read table name. If this method is used, Editor will create from the
table name(s) given rather than those given by Editor->table(). This can be
a useful distinction to allow a read from a VIEW (which could make use of a
complex SELECT) while writing to a different table.
Parameters
- $_
Read table names given as a single string, an array
of strings or multiple string parameters for the function. Returns
|
public
string[]|DataTables\Editor
|
#
table( string|array $_ = 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
- $_
Table names given as a single string, an array of
strings or multiple string parameters for the function. Returns
|
public
boolean|DataTables\Editor
|
#
transaction( boolean $_ = null )
Get / set transaction support.
Get / set transaction support.
When enabled (which it is by default) Editor will use an SQL transaction
to ensure data integrity while it is performing operations on the table.
This can be optionally disabled using this method, if required by your
database configuration.
Parameters
- $_
Enable (true) or disabled (false) transactions.
If not given, then used as a getter. Returns
|
public
boolean|DataTables\Editor
|
#
tryCatch( boolean $_ = null )
Enable / try catch when process() is called. Disabling this can be
useful for debugging, but is not recommended for production.
Enable / try catch when process() is called. Disabling this can be
useful for debugging, but is not recommended for production.
Parameters
- $_
true to enable (default), otherwise false to disable Returns
boolean| DataTables\EditorValue if used as a getter, otherwise $this when
used as a setter.
|
public
boolean
|
#
validate( array & $errors, array $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
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
- The format data to check
Returns
boolean
true if the data is valid, false if not.
|
public
DataTables\Editor|callable
|
#
validator( callable $_ = null )
Get / set a global validator that will be triggered for the create, edit
and remove actions performed from the client-side. Multiple validators
can be added.
Get / set a global validator that will be triggered for the create, edit
and remove actions performed from the client-side. Multiple validators
can be added.
Parameters
- $_
Function to execute when validating the input data.
It is passed three parameters: 1. The editor instance, 2. The action
and 3. The values. Returns
DataTables\Editor|callable Editor instance if called as a setter, or the
validator function if not.
|
public
string[]|DataTables\Editor
|
#
where( string|callable $key = null, string $value = null, string $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
- Single field name or a closure function
- $value
- Single field value.
- $op
- Condition operator: <, >, = etc
Returns
|
public
boolean
|
#
whereSet( boolean $_ = null )
Get / set if the WHERE conditions should be included in the create and
edit actions.
Get / set if the WHERE conditions should be included in the create and
edit actions.
Deprecated
Note that whereSet is now deprecated and replaced with the
ability to set values for columns on create and edit. The C# libraries
do not support this option at all.
Parameters
- $_
- Include (
true), or not (false)
Returns
boolean
Current value
|
public
|
|
public
|
#
_ssp_field( array $http, integer $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
- HTTP variables (i.e. GET or POST)
- $index
- Index in the DataTables' submitted data
Throws
Exception
Unknown fields
Private
Note that it is actually public for PHP 5.3 - thread 39810
Returns
string DB field name
|
DataTables\Editor