form-options

Form display and interaction options.
Please note - this property requires the Editor extension for DataTables.

The full Editor reference documentation is available to registered users of Editor - the information shown below is a summary only. If you already have an Editor license please sign-in, alternatively an Editor license can be purchased on this site, or sign up for the free trial.

Description

The five Editor editing methods (create(), edit(), remove(), bubble() and inline()) all provide common options for how the editor form is configured for display and how the end user can interact with it. This form-options type defines what these common options are.

The values of each of the options presented by this configuration object are useful in different values for different circumstances. As such, for the default values that these options take for each editing mode, please refer to the documentation for those editing types initialisation options: formOptions.bubble, formOptions.inline and formOptions.main.

Options

The form options are properties in a standard Javascript object. The following properties are supported:

• Behaviour:
  • focus
  • nest (2.0+)
  • onBackground
  • onBlur
  • onComplete
  • onEsc
  • onFieldError (1.6+)
  • onReturn
  • scope (1.7.3+)
  • submit (1.5+)
• Display:
  • buttons
  • cancelTrigger (2.1+ inline editing only)
  • cancelHtml (2.1+ inline editing only)
  • drawType (1.5+)
  • message
  • submitTrigger (2.0+ inline editing only)
  • submitHtml (2.0+ inline editing only)
  • title

Behaviour options

focus

When the Editor form is shown to the end user, they are going to want to start editing the content with the minimum of delay (that's what the form is there for after all!). To assist in this, Editor has the ability to automatically focus on an input element in the form - the first input is typical (and the default for Editor's editing methods).

This option provides the ability to control which field Editor will focus on when the form is displayed, and has a number of different options available:

• null: No focus will be performed
• integer (default = 0): The field at the integer index will be focused on - i.e. use 0 to focus upon the first field.
• string: As a string, this option can be given is two different ways:
  • With a jq: prefix: this will run a jQuery selector on the form and focus on the element returned by the selector given.
  • Without a prefix: the string given should match a field name (fields.name) for the field to be focused on.

Note for remove() - as there are no fields shown in the remove form, the integer expression will focus on a button of the given index and null will cause no focus.

Focus on the second field in the form

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        focus: 1
    } );
} );

No focus on display

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        focus: null
    } );
} );

nest

Editor 2 has the ability to work with nested forms (i.e. form B is called from inside form A), which is particularly useful when working with the new datatable field type to allow editing of joined data. Editor maintains an internal hierarchy of the forms being shown, but we need a way to distinguish between a top level action and a nested action - this parameter provides that information to Editor.

When set to true Editor will add the new form to its internal queue, so when methods such as close() are called, the form in the next level up will be restored to the display.

Trigger a nested edit by clicking on a row in a table in the Editor form

editor
    .field('myTable')
    .input()
    .on( 'click', 'tbody tr', function () {
        nestedEditor.edit( this, {
            nest: true
        } );
    } );

onBackground

Action to take when a background element is activated

When the editing form is shown, a click on the background element (shown in the main and bubble editing modes) and cause the form to perform one of the following actions:

• blur (default): The form will be blurred (i.e. blur()). The resulting behaviour will then be defined by the onBlur option.
• close: The form will be closed and any changes discarded (i.e. close()).
• none: Take no action
• submit: The form will be submitted and any changes saved (i.e. submit()).
• function (since 1.6.0): The provided function will be executed. It can call API methods such as close() in addition to any other logic required. A single parameter is passed in, the Editor instance.

Special note for inline editing: this option is always true for inline() editing and cannot be overridden.

Disable any action from occurring when clicking on the background of a bubble edit

$('#myTable').on( 'click', 'tbody td', function () {
    editor.bubble( this, {
        onBackground: 'none'
    } );
} );

onBlur

Action to take when the form is blurred

This option is used to control what action is taken by Editor when the form is blurred (i.e. it looses focus). It may take one of the following values:

• submit: submit the form to the server
• close (default): close the form without submission
• none: take no action
• function (since 1.6.0): The provided function will be executed. It can call API methods such as close() in addition to any other logic required. A single parameter is passed in, the Editor instance.

A blur is triggered either by a call to blur() or by the end user causing the form to loose focus - i.e. clicking upon the background.

Note that if onBackground (above) is not set to blur, this setting is irrelevant as no action will be taken.

Automatically submit on blur of an inline edit

$('#myTable').on( 'click', 'tbody td', function () {
    editor.inline( this, {
        onBlur: 'submit'
    } );
} );

onComplete

Action to occur after Ajax update

If you wish to reuse the form after a submission has been completed, you might find it useful to have it not automatically hide (i.e. an automatic call to close()). This is particularly used in standalone forms where the user has a progression of forms to complete with the fields being configured through the API to display different forms to the user.

This option is a string value and may take one of the following values:

• close (default): close the form without submission
• none: take no action
• function (since 1.6.0): The provided function will be executed. It can call API methods such as close() in addition to any other logic required. A single parameter is passed in, the Editor instance.

Don't hide the form immediately on submit complete.

$('#myTable').on( 'click', 'tbody td', function () {
    editor.create( this, {
        onComplete: 'none'
    } );
} );

onEsc

This option defines the action that Editor should take when the esc key is pressed by the user on their keyboard. The default action is to simply close the form, discarding any information that the user has previously entered in the form. However it can be given as a number of different values:

• blur: The form will be blurred (i.e. blur()). The resulting behaviour will then be defined by the onBlur option.
• close: The form will be closed and any changes discarded (i.e. close()).
• none: Take no action
• submit: The form will be submitted and any changes saved (i.e. submit()).
• function (since 1.6.0): The provided function will be executed. It can call API methods such as close() in addition to any other logic required. A single parameter is passed in, the Editor instance.

Blur on esc

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        onEsc: 'blur'
    } );
} );

onFieldError

This option provides the ability to control what action Editor will take when a field error is returned in the JSON sent back by the server. This option required Editor 1.6 or newer.

• focus: Automatically focus on the field that is in the error state and scroll the display controller's viewport to it if required.
• none: Take no action. The error message will still be displayed for the field, but no automatic display shift will occur.
• function (since 1.6.0): The provided function will be executed. It can call API methods such as close() in addition to any other logic required. Two parameters are passed in; the Editor instance and the error information returned from the server.

No action on field error

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        onFieldError: 'none'
    } );
} );

onReturn

Action to take on return key when the form is focused

Editor can automatically listen for the end user pressing the return key while the form has focus. This can be very useful for rapid editing of items in a DataTables. It is a string value and may take one of the following values:

• submit: submit the form to the server
• none: take no action
• function (since 1.6.0): The provided function will be executed. It can call API methods such as close() in addition to any other logic required. A two parameters are passed in, the Editor instance and the original event that triggered this action (in that order).

Editor will automatically recognise which field types are suitable for a return key press to submit the form and only act upon those fields. For example, if a textarea has focus, pressing return is a valid option for the user to take without expecting the form to submit.

Please note that when triggered and configured to submit the form, this action will call submit() directly and without any configured options. If you have defined custom actions in a button click handler you would need to either disable this option and replace it with a custom event handler or also listen for the return key event.

Disable submit on return for a main edit

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        onReturn: 'submit'
    } );
} );

submit

What values should be submitted to the server

As of Editor 1.5 this option can be used to determine what values will be submitted to the server when submit() is executed. It can be one of the following values:

• all - The values of all fields being edited will be submitted
• changed - Only the values of the fields that have been changed will be submitted
• allIfChanged - The values of all fields being edited will be submitted, but only if there is a changed value.

If the above conditions are not met (i.e. changed is used and no values are actually changed), Editor will not submit the data as there are no changes, and therefore nothing to submit! Instead, it will execute any submit complete callbacks, close the form (if onComplete is set to close - see above) and trigger submitComplete. Events such as submitSuccess and postEdit will not be executed.

This option will only be used when editing data (i.e. edit(), bubble() and inline()). It has no effect on create and remove actions.

Inline editing, submit the values of all fields if there is a value change for the field being edited

$('#myTable').on( 'click', 'tbody td', function () {
    editor.inline( this, {
        submit: 'allIfChanged'
    } );
} );

Main editing, only submit the changed values

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        submit: 'changed'
    } );
} );

scope

What data should be loaded into the form

As of Editor 1.7.3 this option can be used to determine what data should be loaded into the form for the item(s) to be edited. It can take one of the following values:

• row (default) - The data from the entire row will be loaded into the form.
• cell - Data from only the cells selected for editing will be loaded. Other field cannot have their values set.

It can sometimes be useful to limit the data that is used to populate the form to only specific items from inside a row - for example when editing a single cell, particularly when editing multiple cells at the same time (as is allowed by inline editing). Equally, it can also be useful to allow all fields to be edited programmatically, even if the end user can only see a single item (e.g. while inline editing). These two states are mutually exclusive, so this option is available to allow you to select which mode you would prefer Editor to operate in.

This option will only be used when editing data (i.e. edit(), bubble() and inline()). It has no effect on create and remove actions.

Inline editing, loading only the data for the cell requested.

$('#myTable').on( 'click', 'tbody td', function () {
    editor.inline( this, {
        scope: 'cell'
    } );

    // Note that using `editor.field(...).set()` will not work
    // for any field, other than the one we are editing, since
    // the scope is limited to this cell only.
} );

See the multi-item example to see the scope option being used. It allows individual cells from multiple rows to be edited.

Display options

buttons

The buttons option can be used to either define the buttons to include in the form, by using an button-options data type (or an array of button options to define multiple buttons) or can be set to use the buttons that have been defined by a call to buttons() prior to the edit function call by giving the value as true or for the form to not display buttons by setting the value to false.

Although you will almost always want to show buttons in the main form, bubble and inline editing can both readily be used without buttons through the submitOnReturn option defined above.

Define a simple submit button

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        buttons: 'Save changes'
    } );
} );

Use the buttons() method to define a button and use in a bubble edit

$('#myTable').on( 'click', 'tbody td', function () {
    editor
        .buttons( 'Save' )
        .bubble( this, {
            buttons: true
        } );
} );

cancelTrigger

This option was added in Editor 2.1 to compliment the submitTrigger option. Where that option will trigger the form submission when activated, this option will cancel the edit and close the form. Otherwise the use of this option is exactly the same as submitTrigger.

cancelHtml

Just as with the submitTrigger option, this option is the partner of cancelTrigger and defines the HTML that will be inserted into the document when required.

Inline editing with cancel button in last column, and submit button in second last row.

$('#example').on( 'click', 'tbody td.row-edit', function (e) {
    editor.inline( table.cells(this.parentNode, '*').nodes(), {
        cancelTrigger: -1,
        cancelHtml: '<i class="fa fa-times"/>',
        submitTrigger: -2,
        submitHtml: '<i class="fa fa-floppy-o"/>'
    } );
} );

drawType

The drawType option is used to define the type of draw that DataTables will perform when data is updated. The draw() method (which Editor uses to redraw the table after an update) has the following modes of operation:

• full-reset or true - the ordering and search will be recalculated and the rows redrawn in their new positions. The paging will be reset back to the first page.
• full-hold or false (default) - the ordering and search will be recalculated and the rows redrawn in their new positions. The paging will not be reset - i.e. the current page will still be shown.
• page - ordering and search will not be updated and the paging position held where is was. This is useful for paging (i.e. page()) when data has not been changed between draws.
• none (since 1.5.5) - the redraw will not happen (this option is unique to Editor and will not work with draw() itself.

The full-hold operation is the default action for Editor, however, you may at times which to use the page method so that data which has been edited will not immediately have the new ordering and searching criteria applied to it.

These property will accept any of the values that are valid for draw().

Don't redraw immediately after an inline edit

$('#myTable').on( 'click', 'tbody td', function () {
    editor.inline( this, {
        drawType: 'page'
    } );
} );

message

The message option can be used to either define a message to display for the form by using it as a string, or as a boolean value. If true then the form message as previously set by message() will be used and displayed, otherwise if false then the form message will not be shown for the edit.

Special note for inline editing: this option is always false for inline() editing and cannot be overridden (including the form title in the inline form would cause a significant shift in the table layout).

Define and show a message for a row edit

$('#myTable').on( 'click', 'tbody tr', function () {
    editor.edit( this, {
        message: 'After completing this form, click the \'Save\' button below',
        buttons: 'Save'
    } );
} );

Use the message() method to define the message

$('#myTable').on( 'click', 'tbody td:first-child', function () {
    editor
        .message( 'For the name input, ensure that you use both the first and last name' )
        .bubble( this, {
            message: true
        } );
} );

submitTrigger

This option can be used for inline editing, and will be useful when editing multiple fields at the same time. As such, this option is only available in Editor 2.0 and newer. It provides an easy way for you to have a submit button for the form - often this will replace the trigger element that was used to activate inline editing in the first place. This option tells Editor where the submit element should go in the target row. It may take one of the following forms:

• node: The td or other element in the row where the submit element should be placed,
• number: The visible column index for where the submit element should be placed. A negative number may be specified, counting from the right,
• string (since 2.1): A CSS selector for the element where the submit element should be placed.

The submit element, which is defined by the submitHtml option (see below), will replace the contents of the targeted cell completely. They will then be restored when the form is closed (either by being cancelled or successfully submitted).

By default this option is not enabled (i.e. no submit element will be automatically inserted into the inline editing row).

submitHtml

This option goes hand in hand with the submitTrigger option, although in this case it does have a default value - simply the character ▶. The value given here is what will be inserted into the submit trigger target (see submitTrigger above) - it should give some indication to the end user that clicking on it will submit the form.

Inline editing of a row with a submit button in the second last column of the table

$('#example').on( 'click', 'tbody td.row-edit', function (e) {
    editor.inline( table.cells(this.parentNode, '*').nodes(), {
        submitTrigger: -2,
        submitHtml: '<i class="fa fa-play"/>'
    } );
} );

title

The title option can be used to either define a title to display for the form by using it as a string, or as a boolean value. If true then the form title as previously set by title() will be used and displayed, otherwise if false then the form title will not be shown for the edit.

Special note for inline editing: this option is always false for inline() editing and cannot be overridden (including the form title in the inline form would cause a significant shift in the table layout).

Define and show a title for a bubble edit

$('#myTable').on( 'click', 'tbody td', function () {
    editor.edit( this, {
        title: 'Edit:'
    } );
} );

Use the title() method to define the title

$('#myTable').on( 'click', 'tbody td', function () {
    editor
        .title( 'Save' )
        .bubble( this, {
            title: true
        } );
} );