# Class Editor

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 wish 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.

  DataTables\Ext
  DataTables\Editor

Namespace: DataTables
Example:

A very basic example of using Editor to create a table with four fields. This is all that is needed on the server-side to create a editable table - the `DataTables\Editor::process()` method determines what action DataTables / Editor is requesting from the server-side and will correctly action it.

    Editor::inst( $db, 'browsers' )
             ->fields(
                 Field::inst( 'first_name' )->validator( Validate::required() ),
                 Field::inst( 'last_name' )->validator( Validate::required() ),
                 Field::inst( 'country' ),
                 Field::inst( 'details' )
             )
             ->process( $_POST )
             ->json();

Located at Editor.php

Methods summary
`public static string` | # `action( array $http )` 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 #### 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. 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 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 `DataTables\Database`|`DataTables\Editor` The Database connection instance if no parameter is given, or self if used as a setter.
`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\Editor` Debug 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 `DataTables\Editor\Field`|`DataTables\Editor\Field[]`|`DataTables\Editor` The selected field, an array of fields, or the Editor instance for chaining, depending on the input parameter. #### Throws Exception Unkown field error #### See `DataTables\Editor\Field` for field documentation.
`public `DataTables\Editor\Field[]`|`DataTables\Editor`` | # `fields( `DataTables\Editor\Field` $_ = null )` Get / set field instances. Get / set field instances. An alias of `DataTables\Editor::field()`, for convenience. #### Parameters $_ $_... Instances of the `DataTables\Editor\Field` class, given as a single instance of `DataTables\Editor\Field`, an array of `DataTables\Editor\Field` instances, or multiple `DataTables\Editor\Field` instance parameters for the function. #### Returns `DataTables\Editor\Field[]`|`DataTables\Editor` Array of fields, or self if used as a setter. #### See `DataTables\Editor\Field` for field documentation.
`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\Editor` 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[]`|`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 $_ Instances of the `DataTables\Editor\Join` class, given as a single instance of `DataTables\Editor\Join`, an array of `DataTables\Editor\Join` instances, or multiple `DataTables\Editor\Join` instance parameters for the function. #### Returns `DataTables\Editor\Join[]`|`DataTables\Editor` Array of joins, or self if used as a setter. #### See `DataTables\Editor\Join` for joining documentation.
`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\Editor` self 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 `DataTables\Editor` Self for chaining. #### 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 `DataTables\Editor` Self for chaining. #### 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\Editor` Value 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 `DataTables\Editor` Self for chaining.
`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\Editor` Primary 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 `DataTables\Editor`
`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 string[]|`DataTables\Editor` Array of read tables names, or self if used as a setter.
`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 string[]|`DataTables\Editor` Array of tables names, or self if used as a setter.
`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 boolean|`DataTables\Editor` Transactions enabled flag, or self if used as a setter.
`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\Editor` Value 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 string[]|`DataTables\Editor` Where condition array, or self if used as a setter.
`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` | # `_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

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

Constants summary
`string` | `ACTION_READ` Request type - read Request type - read | # `'read'`
`string` | `ACTION_CREATE` Request type - create Request type - create | # `'create'`
`string` | `ACTION_EDIT` Request type - edit Request type - edit | # `'edit'`
`string` | `ACTION_DELETE` Request type - delete Request type - delete | # `'remove'`
`string` | `ACTION_UPLOAD` Request type - upload Request type - upload | # `'upload'`

Properties summary
`public string` | $version | # `'1.9.0'`