language

string, language configuration for the plugin to enable the plugin to display messages for your locale (you must set the ISO code for the language). You can have multiple language widgets on the same page. The locale JS file from the js/locales folder of the extension (for the specific language code) must be loaded. This file must be loaded after dependent-dropdown.js.

depends

array the list of parent input ID attributes on which the current dropdown is dependent on. DO NOT prepend any # (hash) before the input id.

NOTE: Usually, for a nested dropdown, you set this to just the immediate parent element id. If you have a complex dependency where you have different dependent parents, then you can set it to the various parent identifiers.

initDepends

array, the list of INITIAL nested parent inputID attributes on which the current dropdown is dependent on. This is applicable only wheninitialize is set totrue (for firing the ajax requests on page initialization).

NOTE: Usually, for a nested dropdown, you may set it to the topmost parent in the hierarchy while initializing, unless you have complex multiple many to many dependencies. The ajax requests will be fired in sequence based on these dependent ids. DO NOT prepend any hash before the input id. If not set, this will default todepends. For example you could usedepends andinitDepends in the following manner:

$("#child-1").depdrop({

    depends: ['parent-1'],

    url: '/path/to/child_1_list'

});



$("#child-2").depdrop({

    depends: ['child-1'], // dependent only on child-1

    url: '/path/to/child_1_list'

});



$("#child-3").depdrop({

    depends: ['child-2'], // dependent only on child-2

    initDepends: ['parent-1'], // initial ajax loading will be fired first for parent-1, then child-1, and child-2

    initialize: true,

    url: '/path/to/child_2_list'

});

params

array the additional input ID attributes, whose values will be parsed and passed to the ajax call. DO NOT prepend any hash before the input id. When this is setup, the $_POST request would contain an array named depdrop_params with the values of these input identifiers. For example in PHP you can retrieve this as:

if (!empty($_POST['depdrop_params'])) {

    foreach ($_POST['depdrop_params'] as $id => $value) {

        $param1 = $params[0]; // the first parameter value you passed

        $param2 = $params[1]; // the second parameter value you passed

        // and so on

    }

}

url

string the ajax url action which will process the dependent list. The server action must return a JSON encoded specified format like {output: <dependent-list>, selected: <default-selected-value>}. where,

• the output is an array of data for the dependent list of the format {id: <option-value>, name: <option-name>},

• selected is the default selected value after the dependent dropdown is generated.

If you desire a dependent list containing optgroups then the output must be of the format {group-name: {id: <option-value>, name: <option-name>}}.

The plugin passes an array of dependent values as a POST request to the server under a variable name depdrop_parents. In addition, the plugin also passes a property depdrop_all_params that will be an associative array of keys and values (it merges the values of depdrop_parents and depdrop_params). This can be read by the server action to generate a dependent dropdown list. An example for a PHP server action could be:

public function generateChildren() {

    $out = [];

    if (isset($_POST['depdrop_parents'])) {

        $parents = $_POST['depdrop_parents'];

        if ($id != null) {

            $out = getChildList($parents);

            /*

             * the `getChildList` function can query a db and return array of format

             * {id: , name: }, based on the list of parents passed.

             * (note you can edit the `idParam` and `nameParam` properties of the plugin

             *  if you are returning different parameter names)

             */

            echo json_encode(['output'=>$out, 'selected'=>'']);

            return;

        }

        if (isset($_POST['depdrop_all_params'])) {

            for ($_POST['depdrop_all_params'] as $key => $value) {

                // $key = Element ID 

                // $value = Element Value

            }

        }

    }

    echo json_encode(['output'=>'', 'selected'=>'']);

    // note when a null or empty array is returned, the plugin will display `emptyMsg`

    // in the dependent dropdown

}

ajaxSettings

object additional ajax settings to pass to the plugin before submitting the ajax request to the server for validating dependency as specified in url. This can be useful to override default ajax settings OR to pass additional tokens to headers OR one can use it for setting other ajax options for advanced cases. Refer the jQuery ajax documentation for the various settings you can configure.

initialize

boolean, this is an important attribute if you want to auto initialize and populate the dropdowns by triggering the ajax calls when document is loaded. You must set this to true only for the last child in the nested dependency list, so that initial preselected values are refreshed sequentially in the nested hierarchy. Defaults to false. If this property is not true for any dependent dropdown, no ajax calls will be triggered on document load (i.e. the dropdowns will show the default data set by the html markup set on init).

skipDep

boolean whether to skip the ajax dependency request from firing when the value of the dropdown is empty or equal to the value specified in loadingText. Defaults to false.

loading

boolean whether to show a loading progress spin indicator in the child select when server is processing the ajax response. Defaults to true.

loadingClass

string the CSS class to attach to the child dropdown element when the server is processing the ajax response. Defaults to kv-loading.

loadingText

string the text to display in the child dropdown element when the server is processing the ajax response. Defaults to Loading ....

placeholder

string|boolean whether the child select has a default placeholder. This will create an option with an empty value within the child select element. For optgroups this will be a disabled option. If you set this to false, it will not be displayed. Defaults to Select ....

emptyMsg

string the message to display when the ajax response returned from the server is null or an empty array. Defaults to No data found.

idParam

string the name of the parameter that returns the id value for each list item via json response. Defaults to id.

nameParam

string the name of the parameter that returns the name value for each list item via json response. Defaults to name.

optionsParam

string the name of the parameter that returns the HTML options for each list item via json response. Defaults to options.

parentParam

string the name of the ajax data parameter that will send the parent dropdown values. Defaults to depdrop_parents.

otherParam

string the name of the ajax data parameter that will send the other dependent parameter values. Defaults to depdrop_params.

allParam

string the name of the ajax data parameter that will send the all parameter values combining both the data from parentParam and otherParam . Defaults to depdrop_all_params.