Display controllers

When creating your web-application you will have a particular style and visual interface in mind and the last thing you will want is a library that should be saving you time getting in the way of that visual style and costing you time and effort to integrate it with your app! Editor recognises this fact and presents a display controller plug-in architecture for its display components allowing you to completely customise the look and feel of your forms.

Editor has two built in display controllers, lightbox and envelope and additional display controllers can easily be added through plug-ins, the interface for which is detailed in this document. Which display controller is used for an Editor instance can be selected using the display option.

It is important to understand that the display controller determines the overall display container for the Editor form - not the contents of the form itself, which is handled by the Editor core. So the display controller presents the form container on screen, giving it position, styling and manipulating other elements if required.

Plug-in interface

Field type plug-ins for Editor are objects which are added to the DataTable.Editor.display namespace (where the default display controllers are also defined). The object that you add to the display namespace must provide the following three functions:

init - Initialisation method, called by Editor during an instance's initialisation
- Function with the following signature:
- Parameter 1: The DataTables Editor instance that has requested the action - this allows access to the Editor API if required.
- Returns: The object that Editor will use to run the open and close methods against. If static methods are used then just return the object that holds the three methods, however, this also allows a display controller to be created with a new instance of an object.
open - Display the form (i.e. add it to the visual display in the document) so the user can interact with it
- Function with the following signature:
- Parameter 1: The DataTables Editor instance that has requested the action - this allows access to the Editor API if required.
- Parameter 2: DOM node that should be shown to the end user
- Parameter 3: Callback function that is to be executed when the form has been displayed (optional)
- Returns: None
close - Hide the form (i.e. remove it form the display in the document)
- Function with the following signature:
- Parameter 1: The DataTables Editor instance that has requested the action - this allows access to the Editor API if required.
- Parameter 2: Callback function that is to be executed when the form has been hidden (optional)
- Returns: None

Note that each of these functions has the Editor instance that is performing the action passed in as the first parameter. This provides this ability to access the API methods for that Editor instance.

Template structure

Editor provides a template model for display controller plug-ins which can be extended to create a new display controller. In the following example code, the Editor.models.display object is extend with prototypes for the three required methods and the resulting object is saved to a new display controller called myDisplayController (attached to Editor.display):

var Editor = DataTable.Editor;

Editor.display.myDisplayController = $.extend( true, {}, Editor.models.display, {
    // Create the HTML mark-up needed the display controller
    init: function ( editor ) {

      return Editor.display.myDisplayController;
    },

    // Show the form
    open: function ( editor, form, callback ) {

    },

    // Hide the form
    close: function ( editor, callback ) {

    }
} );

Now we just need to fill in the functions!

Example

To illustrate how a display controller can be created, an example is presented and discussed in detail below. This example uses DataTables child row capabilities (row().child()) to show the Editor form for a row in a child row for that row. The completed example can be seen running here.

init

The init method, as discussed above, is used to create any additional HTML needed to display the form, however, in this particular case there is no additional initialisation required since the row().child() method is used to create the child row when the form needs to be displayed in the open function.

As such, all this function needs to do is tell Editor where the open and close methods are. In this case, they are static functions attached to Editor.display.details (i.e. our display controller), so we simply return that (where Editor === DataTable.Editor):

"init": function ( editor ) {
    return Editor.display.details;
},

open

The open function is slightly more complex - but not too much! This function is called when Editor wishes to have the form displayed to the end user, so all we need to do is create the child row using the row().child() method and attach the form.

To perform these operations we need the DataTable that the form is operating with and the row that to be edited. These two options are available using the s (settings) namespace in Editor - specifically we wish to use the s.table and s.modifiers option respectively here (see the JS developer documentation for full information about the settings object).

Our resulting code is:

"open": function ( editor, append, callback ) {
    var table = $(editor.s.table).DataTable();
    var row = editor.s.modifier;

    // Close any rows which are already open
    Editor.display.details.close( editor );

    // Open the child row on the DataTable
    table
        .row( row )
        .child( append )
        .show();

    $( table.row( row ).node() ).addClass( 'shown' );

    if ( callback ) {
        callback();
    }
},

close

The final piece to our display controller is to be able to close the child row when requested to do so by the Editor instance. To do that, we can use DataTables API to loop over each row (rows() and each() checking to see if each row is shown (row().child.isShown()) and if so hiding it.

The code for this is:

"close": function ( editor, callback ) {
    var table = $(editor.s.table).DataTable();

    table.rows().eq(0).each( function ( idx ) {
        if ( table.row( idx ).child.isShown() ) {
            table.row( idx ).child.hide();
            $( table.row( idx ).node() ).removeClass( 'shown' );
        }
    } );

    if ( callback ) {
        callback();
    }
}

Putting it all together

To use the new display controller the display option can very simply be set to the name given when attaching the plug-in to the Editor.models.display namespace.

The example constructed here is available in the Editor examples.