Standalone

While Editor is primarily designed to be software that provides an editing interface for DataTables, it can also be used as a standalone form editor without DataTables. This can be very useful for single dimension configuration data (for example, Enable service: Yes/No), for editing the data of a database row on an individual page, rather than a Javascript modal window, or for editing a collection of data outside of DatTables.

An example of Editor being used as a standalone form control can be seen on this site: the registration and customer details forms used on this site when you start a trial or purchase Editor use Editor in standalone mode use a standalone Editor instance. The information is collected and then sent to the server, without need for a DataTable.

Configuration

Editor's standalone mode is activated by simple not providing an table parameter (which is used to attach Editor to a specific DataTable) in the initialisation configuration object.

Editor in standalone mode can either directly manipulate the elements in the document reading and writing the values of a field to and from the document through use of specific HTML attributes, or use the Javascript API and events of Editor to have complete control over the data, with Editor providing the editing interface for the end user.

HTML

When operating in standalone model, Editor will automatically scan the document for elements with the following two attributes:

  • data-editor-field - The value of this attribute tells Editor that the content of this element is to be used for the Editor field of the same name.
  • data-editor-label - Optional. If defined, Editor will use the content of this element as the label for the field. This is useful if the label is already in the HTML, so you don't need to specify a fields.label option for the field.

As an example, consider the following HTML:

<dt data-editor-label="server-ip">Server IP:</dt>
<dd data-editor-field="server-ip">153.63.213.41</dd>

When Editor is initialised with a field name server-ip (fields.name) it will use the dt element above as the field label (fields.label) and the dd as the element from which to read the field's value when editing the form, and where to write the updated value after the user has edited the value.

Editor can also make use of the following optional attribute:

  • data-editor-value - The value that the field should take, rather than the HTML content of the element.

If the data-editor-value attribute is defined, its value is what will be used for the form field, and also will be written to when the field is updated. If it is not defined, the HTML content of the element with the relevant data-editor-field attribute will be used.

Javascript

If you do not wish to have Editor read and write values directly to the document (for example you might not want the end user to see the values, or they require formatting before display), simply don't use the two attributes defined above for those fields. Instead, use the set() method to set the value of the field when it is being edited, and the edit event to trigger any updates you require, based on the new values.

Editing data

To edit data in standalone mode, simply call edit(). Giving an identification value as the first parameter is optional in standalone mode (in DataTables editing mode, the first parameter indicates what row is to be edited). Given a value can be useful if you are editing data which is stored with a unique identifier, as it is passed to the server as the id parameter (see the client / server communication documentation), but is not required.

Setting values

If you are using HTML sourced editing fields (above) Editor will read the values for the form and display them to the end user. If not using the HTML attributes, provide the field values that you wish to have edited. For example:

$('#editButton').on( 'click', function () {
    editor
        .edit( null, false )           // no editing id, and don't show immediately
        .set( 'server-ip', config.ip ) // Get the value from Javascript
        .open();                       // Display the form
} );

Submitting

The data submitted to the server from a standalone form takes the same form as when using Editor to edit a DataTable. As such you can use the same server-side scripts to perform validation etc, as required. As with any other editor form, the data is submitted to the server using the submit() method, typically from a button configured in the Editor form.

Value updates

Once the values have been saved by the server, you will likely wish to update the page in some manner to reflect the change in the values. If using the data-editor-field HTML attribute, as described above, Editor will automatically write the new value to that element and no further code is required.

If you wish to take some action, such as updating elements directly, or if you are not using the data-editor-field attribute, the edit event can be used to know when the edit has been completed by the server and to get the new values. For example:

editor.on( 'edit', function ( e, json, data ) {
    alert( 'New server IP is: '+ json['server-ip'] );
} );

Collections

The discussion above focuses specifically on the case where you have single dimension (i.e. non-repeating data), however, Editor can also be used on data collections outside of a DataTable. This can be useful for cases where you want to display the data in a layout that is not constrained to rows and columns like a table, but want something more flexible such as displaying items in a grid. An example of this can be seen in the Editor examples.

In this case Editor needs to be able to distinguish between the different records of the repeating template, for which another attribute is defined:

  • data-editor-id - The id of the item to be edited / deleted

Consider for example the following HTML:

<div class="panel" data-editor-id="row_43">
    <dl>
        <dt>Name:</dt>
        <dd>
            <span data-editor-field="first_name">Bruno</span> 
            <span data-editor-field="last_name">Nash</span>
        </dd>

        <dt>Position:</dt>
        <dd data-editor-field="position">Software Engineer</dd>

        <dt>Office:</dt>
        <dd data-editor-field="office">London</dd>
    </dl>
</div>

Note that data-editor-id is assigned a unique id (based on the database table's primary key value usually) and the data-editor-field attributes are still used inside the element to identify to Editor what data belongs to each field.

Create

Using create() in standalone mode is similar to when used with DataTables to trigger the creation of a new row. However, when the server completes the creation of the new row, since Editor doesn't have a concept of how your data should be displayed, you will need to insert a new element into the document showing this data.

  • If an element with a match data-editor-id attribute is found for the newly created row, it will update the field values automatically (the new element could be created using preCreate).
  • If no element with a matching data-editor-id attribute is found no action is taken. You would need to use postCreate to insert the newly created item into the display.

Edit

The edit() method has no special requirements beyond those already discussed in this document. On completion of the edit the fields with a matching data-editor-field for each field in the data-editor-id container are automatically updated by Editor.

The following code can be used to trigger an edit of the example HTML above (typically you would make the id a variable based on a button click, such as an edit button in the HTML):

editor
    .title( 'Edit record' )
    .buttons( 'Save changes' )
    .edit( 'row_43' );

Remove

On completion of a remove() command Editor will automatically remove the element with a matching data-editor-id attribute for the item removed.

The following code would trigger a confirm remove message, and perform the removal if the end user okay's the action (as before, you would likely make the static row_43 shown below a variable based on information from a clicked button):

editor
    .title( 'Delete record' )
    .buttons( 'Delete' )
    .message( 'Are you sure you wish to delete this record?' )
    .remove( 'row_43' );

Examples

This site contains a number of examples of Editor in standalone mode, including showing its ability to use both bubble and inline editing (bubble() and inline()) as well as full form editing.