Editing

The Editor class is one of the main access points for processing requests from the server-side. It can handle all requests for reading and writing data to a database for a DataTable. It is very similar to the DataTable class, providing a very similar interface style. The documentation on this page will partly refer to the DataTable documentation due to the overlap!

It is important to note that the Editor class provides all of the same features as the DataTable class for reading data (i.e. you do not need to use both for the same table!), but also adds support for writing data. There are four basic request types that DataTables and Editor can make:

• Fetch - Get the data to display
• Create - Create a new row of data
• Edit - Update an existing row with changed data
• Remove - Delete one or more rows from the database

The Editor class will automatically detect which of these requests are being made and handle it correctly for you without adjustment. The data resulting from the request is then sent back to the client for it to complete the processing.

Basic initialisation

As with the DataTable documentation here we'll assume that you have successfully installed the DLL for the DataTables .NET libraries and established a database connection which is available in the variable db. Also assumed is that you have imported the DataTables namespace with using DataTables, as noted in the installing documentation.

In your controller, construct a Editor instance using:

new Editor( db, table, pkey="id" );

Where:

• db is an instance of the Database class, which connects to the database
• table is the table name to operate on.
• pkey is an optional parameter that specifies the primary key of the table - the default is id. This option can also be given as a string array to an overloaded constructor (see below).

Compound keys

As of v1.6 the .NET libraries support compound keys: a key which is made up from the data in two or more table columns, rather than just a single column as used in many tables. To use a compound key, simply pass the primary key information into the third parameter for the Editor constructor as an array:

new Editor( db, "visitors", new []{"visitor_id", "visit_date"} );

No special configuration is required on the client-side to support compound keys, however, when creating new rows you must submit the data for the columns that make up the compound key (an error will be shown otherwise). Editor cannot currently read information that is generated by the database. If you need to set a server-side computed value (e.g. current time), use the Field.SetValue() method to set the value. This limitation is due to the database engines that Editor currently supports.

Fields

Fields for the Editor instance are defined using the Field class which has two overloads:

new Column( dbColumn );
new Column( dbColumn, httpName );

Where:

• dbColumn is the name of the column that data will used for read / write
• httpName is the name that will be used for the JSON response to the client-side and looked for in HTTP requests related to the column. This parameter is optional and if omitted the column name will be used.

In the example below an Editor instance is configured with five simple fields:

new Editor( db, "staff" )
    .Fields(
        new Field( "first_name" ),
        new Field( "last_name" ),
        new Field( "position" ),
        new Field( "email" ),
        new Field( "office" )
    );

Like the DataTable class it is also possible to use .Model<T>() to have Editor automatically infer the database columns from the model class:

new Editor( db, "staff" )
    .Model<StaffModel>();

Please see the DataTable documentation for more details about using classes to define database columns, including how to handle joins and the property attributes that Editor supports.

Data processing

As with the DataTable class, to pass the data submitting by the client-side to the Editor instance, there is a .Process() method, that will take the data and perform the actions required on it, based on the configuration. This is typically POST data.

To continue the example above, if we add a Process() method call we now have:

new DataTable( db, 'staff' )
    .Model<StaffModel>()
    .Process( Request.Form );

Return data

Once the data has been processed and whatever action(s) required have been handled, the resulting data needs to be sent back to the client-side. This data is retrieved with the Editor.Data() method which is a DtResponse object which can be passed through the Json() method of your controller to create the JSON.

A completed controller might be as simple as:

DtResponse response = new DataTable( db, 'staff' )
    .Model<StaffModel>()
    .Process( Request.Form )
    .Data();

return Json(response);

And with that you've got a controller that can handle create, insert, update and delete operations!

Next steps

Now that you've got an Editor instance you'll need to put it a controller so Ajax requests can be correctly routed to it. See the WebAPI, MVC and WebForm documentation for more details. You can also of course configure Editor and the fields for more complex situations:

• Conditions
• Validators
• Formatters
• Joins