API

Editor makes it quick and easy to create an editable table through the built in Buttons support and simple initialisation. But to unlock the real power of Editor, you'll want to use its API. The API provides the ability to control each individual Editor instance, with complete control over the fields in the form, what editing display is shown to the end user and what interaction options they have.

The Editor API is broken into three key areas:

• Editing
• Form fields control (multiple fields)
• Individual fields

In this section of the manual we will cover a range of the methods that are available, showing how they can be used, but not all of them. For a full list of the methods that are available in Editor, please refer to the API reference section.

Accessing the API

An Editor object instance, with the data type DataTables.Editor, is created when you initialise Editor using new DataTable.Editor(), as described in the getting started documentation. This object has the Editor API methods attached to it and can be accessed by simply saving the resulting object to a variable. For example:

var editor = new DataTable.Editor();

This will create a new Editor instance and save it into the variable editor. API methods can then be accessed simply by calling them as functions of that object. For example: editor.create() will call the create() method, while editor.submit() will call the submit() method.

Multiple Editor instances can be defined on a single page, and this can often be quite useful if you want to present different forms to the end user (perhaps for different tables, or for showing a simple limited set of the available fields or the full set of fields). Each Editor instance is entirely independent of any other existing instances, and calling the API methods of one will not effect any others. To access the API for multiple instances, simply assign the instances to different variables.

Chaining

Editor, like the DataTables API, makes extensive use of chaining, with the majority of methods returning the instance itself, so you can immediately call another API method. Consider for example the following three function calls:

editor.create( false );
editor.val( 'log_time', new Date() );
editor.submit();

This code calls the three API methods create(), val() and submit() to have Editor automatically create a new record, set a value and submit it to the server, all without user interaction (a single button clicked by the end user could trigger such an action, for example).

As each of these three methods return the Editor API instance, the next method can be called immediately using that returned value. For example:

editor
    .create( false )
    .val( 'log_time', new Date() )
    .submit();

This example has been written so that one method call is used on each line of code, but it could equally be written all on one line. The code in both of the above cases is functionally identical. Writing your code in a chained style such as this is entirely optional in Editor, however chaining can allow more succinct and expressive code, and is used extensively in the Editor documentation and examples.

API methods

The Editor API methods are broken into three distinct groups, as noted above, to provide complete control over the form, its behaviour and the fields in it.

Editing

The editing group of methods provides access to Editor's core editing abilities. These methods are called to start the editing process, telling Editor to initialise the form fields for the required edit. For example, a create action will pre-fill the fields with the default values, while the edit action will pre-fill the fields with the existing values.

There are five editing methods in Editor:

• create() - Create a new row
• edit() - Edit an existing row
• remove() - Remove one or more existing rows
• bubble() - Edit fields in a bubble display
• inline() - Edit a field in an inline display

Whenever you wish to perform a CRUD operation on the table, one of these methods must be called first. Subsequently you can use the other methods to manipulate the form, or submit it to the server.

Form fields

The form fields group of methods provide the ability to control the collection of fields in the form. These fields can be added (add()) or removed (clear()) dynamically at any time, or you can perform collective operations on multiple fields with a single API call.

Many of the form field methods overlap with the individual field controls (below) in terms of the functionality they provide (setting a field value for example), but the primary difference between the two sets is the return value. The form field methods will return the Editor instance (DataTables.Editor), while the individual field methods will return the Field instance (DataTables.Editor.Field). This return value can effect chaining if you are using that style of code.

Consider for example the code used in the chaining example above:

editor
    .create( false )
    .val( 'log_time', new Date() )
    .submit();

The val() method returns the Editor instance, so we can immediately call the submit() method. field().val() can also be used to set a field value, but it will return the field instance, and the submit method will not be available for chaining.

Individual fields

While Editor has its own API methods through Editor instance, each individual field an Editor form also has its own API. The field instances (of data type DataTables.Editor.Field) are created automatically when you use the fields initialisation option, or the add() method to add a new field. They can be access through the field() method which will return the Field instance for the field requested.

Consider for example:

var fname = editor.field( 'first_name' );

The variable fname now contains a reference to the field instance for the first_name field. Using the field instance API we can get and set values, control visibility of the field, set messages etc. Extending the example above, we can use the field().def() and field().val() methods to set a default and then the actual value of the field:

fname
    .def( 'No name entered' )
    .val( 'Allan' );

Notice that the field instance also uses chaining in the same way as the Editor instance, although in this case it returns the field instance, so you can continue using the field API.

Example

The Editor API is extremely flexible and you can control your form and the fields in it completely and the API reference documentation contains an example for each API method, along with a detailed description of what it does, what it returns and what parameters it will accept.

This dense information can be fairly daunting when using Editor for the first time though, so let's form the concepts described above into a detailed, line-by-line example of how the Editor API can be used.

In this example we create a single Editor instance, which is used for both full row editing of a DataTable and inline editing. It is also used to provide a single click button for the end user to submit data to the server automatically when clicked (in this case an approved flag).

var editor = new DataTable.Editor( {
    ajax: "php/users.php",
    table: "#users",
    fields: [
        { label: "First name:", name: "first_name" },
        { label: "Last name:",  name: "last_name" },
        { label: "Approved:",   name: "approved" }
    ]
} );

var table = new DataTable('#users', {
    dom: "Bfrtip",
    ajax: "php/users.php",
    columns: [
        { data: "first_name" },
        { data: "last_name" },
        { data: "approved" }
    ],
    select: true,
    buttons: [
        { extend: "create", editor: editor },
        { extend: "edit",   editor: editor },
        { extend: "remove", editor: editor }
    ]
} );

$('#users').on( 'click', 'tbody td', function () {
    editor.inline( this );
} );

$('#approve').on( 'click', function () {
    editor
        .edit( table.rows( {selected: true } ).indexes(), false )
        .val( 'approved', 1 )
        .submit();
} );

Note that much of the above code is simply initialisation and is shown here for completeness - an Editor instance and a DataTable are both created. The Editor API usage that we are mainly interested in here starts at line 27.

• Lines 1-9 - Create an Editor instance (see getting started) for our main row editor.
• Lines 11-25 - Create a DataTable configured for the data used and configure with buttons that control Editor using the Buttons extension and Select for row selection.
• Line 27 - Attach a jQuery click event handler to the cells in the table's body
• Line 28 - When activated, the inline() method is called to edit the cell (note that this in the context of a jQuery callback is the element that the event was activated upon, so in this case we are passing in the table cell).
• Line 31 - Attach a jQuery click event handler to a button (which has an id of #approve).
• Line 32-33 - The edit() method is called on the selected rows, but in such a way that it will not display the editing form to the end user.
• Line 34 - The value for the field approved is set using val()
• Line 35 - The form is submitted using submit() - no user interaction required.

As you can see, the Editor API is extremely flexible, and provides a wide range of options for accessing and manipulating the form and the fields in it. Please see the API reference documentation for a full list of the methods that are available.