dependent()

Create a dependency on a field's value that can alter the form.
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

Very often, in complex forms, the state of one or more fields will depend upon the state of another field. Consider for example asking for an EU VAT number in a form (as we do on this very site during the purchasing process!): you only want to display the VAT input if the customer selects an EU country as their, or their company's, place of residence - for all other countries the VAT input should be hidden to simplify the form.

This method provides a method of performing dependent actions on the form based on a selected field (the first parameter given to this method). Multiple actions can be taken by the dependent operation, affecting one or more fields:

• Update options in a list (for example select, radio or checkbox).
• Set a value for a field
• Show / hide fields
• Enable / disable fields
• Set a field information or error message
• Set field labels

Please see the Return options / JSON section below for information on how to trigger these actions.

How the dependent() method obtains this update data is configured by the parameters with which the method is called. There are two basic modes of operation:

• Ajax - a string or dt-object is given as the second parameter and is used to configure an Ajax request (using $.ajax()) to get data from the server.
• Local callback - a function given as the second parameter will be executed when the dependency changes. This provides complete control over how the update data is retrieved - it can be hard coded locally in Javascript, or you could use a more complex approach such as streaming updates over a WebSocket. Please see the function type documentation below for further details on using a local callback with this method.

By default the dependent() method will trigger an update call whenever a change event is activated upon the field's input element. For example in the case of a select list this will occur when the user selects a value from the drop down list. You can also modify the event listener using the event option of the third parameter (described below) - this can be useful for text inputs where you want to listen for each keyup for example.

As of Editor 1.8 when a dependent action is triggered the field().processing() method will be used to show the target field is in a processing state. This will be disabled when the action is completed.

Submit data

The data submitted (either by Ajax, or in the callback function) contains the original data source object / array for the item being edited (so you can use the unedited values if needed) and the current values of all fields in the form. The data structure is:

{
    "rows": [ {
        ... original data source object
    } ],
    "values": {
        ... current values for all fields
    }
}

Consider for example a form and data source which has two fields - name and position - it might look like the following:

{
    "rows": [ {
        "name": "Allan",
        "position": "Director"
    } ],
    "values": {
        "name": "Allan",
        "position": "Senior director"
    }
}

rows[0][name] = "Allan"
rows[0][position] = "Director"
values[name] = "Allan"
values[position] = "Senior director"

Return options / JSON

As noted above, the return object (JSON data if returned by Ajax) can effect the visibility of fields in the form, options and values. This is made possible using the following optional parameters - they are broken into two types to reflect the values they are expected to take:

• Interactive options - the options available here must be given as an object where each parameter name is the field that should be updated, and the parameter value is the value to set:
  • errors (v1.4.1) - Field error messages to set - see field().error()
  • labels (v1.4.1) - Field labels to update - see field().label()
  • messages (v1.4.1) - Field information messages to set - see field().message()
  • options - Options to set for select, radio and checkbox field types
  • values - Values to set for the given fields - see field().val()
• Boolean options - the options available here can be given as either a string field name or array of field names:
  • disable (v1.4.1) - field(s) to disable - see disable()
  • enable (v1.4.1) - field(s) to enable - see enable()
  • hide - field(s) to be hidden - see hide()
  • show - field(s) to be shown - see show()

There is also a special top level animate parameter (v1.9) which can be set to a boolean value to enable (default) or disable the show / hide animation when the show and hide methods are used.

The interactive options will look like:

"messages": {
    "fieldName1": "message 1",
    "fieldName2": "message 2"
}

while the boolean options will look like:

"hide": "salary",               // single field
"show": [ "position", "title" ] // array of fields

This can be a little daunting at first sight, but let's put it all together to illustrate its use with multiple parameters and it will become clearer; consider the following JSON structure as returned data for the dependent() method:

{
    "options": {
        "position": [
            "Director",
            "Senior VP",
            "VP"
        ]
    },
    "values": {
        "position": "VP",
        "location": "San Francisco"
    },
    "show": "salary"
}

Points of interest in the above example:

• Options:
  • position is updated to have 3 options available (it might be, for example a select field type.
  • Only one field has its options updated
• Values:
  • The fields position and location both have new values set
  • Multiple values can easily be set
• Show:
  • A single field is made visible using the show option as a string. Multiple fields could be made visible using an array of field names.
• Hide:
  • No fields are hidden in this update object
  • All four of the options are optional - they need not be specified if they are not required.