Krajee

Dependent Dropdown

Thankful to Krajee! BUY A COFFEEor to get more out of us.

A multi level dependent dropdown JQuery plugin that allows nested dependencies. The plugin allows you to convert normal select inputs, whose options are derived based on value selected in another input/or a group of inputs. It works both with normal select options and select with optgroups as well. View a complete demo.

Tip

Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)

  1. Apply the plugin on a select element and set dependency to one or more other input / select elements (including dependency nesting).

  2. Automatically convert select inputs with class depdrop to dependent dropdowns. The plugin supports HTML5 data attributes to configure the dependent dropdown options.

  3. Automatically initialize dependent dropdowns based on preselected values (useful for update scenario).

  4. Supports both select input with basic options and select with optgroups.

  5. Automatically lock/disable the dependent dropdown until dependent results are available.

  6. The plugin uses ajax call to the server to render the list of dependent options.

  7. Allows a loading indicator to be displayed in dependent select until the results are fetched from the server.

  8. Configure your own loading progress text to be displayed for each dependent dropdown before the results are fetched from the server.

  9. Display a placeholder label with an empty value. For optgroups automatically disable this option.

  10. Triggers JQuery events for advanced development. Events currently available are depdrop:init, depdrop:change, depdrop:beforeChange,depdrop:afterChange, and depdrop:error.

  11. Ability to configure HTML attributes of each option element via ajax response (for example dynamically disabling some dropdown options or adding styles).

  1. Latest JQuery

  2. All select inputs in markup must have a defined ID attribute for the plugin to work.

  3. Tested to work currently with default HTML select input. It is not directly tested to work with other JQuery plugins that enhance the HTML select input. However, the plugin exposes events, which can be used in such situations.

    Important

    You can refer the Yii 2 Framework DepDrop widget, where the dependent-dropdown plugin has been implemented to work along with the Select2 Plugin.
  4. The dependent dropdown is generated using an ajax call and hence requires a web server and web programming language to generate this. The plugin passes the dependent id values as an input to the ajax call via POST action. The ajax response should be a JSON encoded specified format like below:

    {output: <dependent-list>, selected: <default-selected-value>}

    where,

    • 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>}}

Example JSON Output

A sample JSON response for the dependent dropdown list is shown below:

{

    "output":[

        {"id":"1","name":"Mobile Phones"},

        {"id":"2","name":"Tablets"},

        {"id":"3","name":"Computers & Accessories"},

        {"id":"4","name":"Cameras"},

        {"id":"5","name":"Televisons"}

    ],

    "selected":"3"

}

The dependent-dropdown plugin can be installed automatically or manually using one of these options:

Bower Package Manager


Installation via bower package manager is as simple as running:

$ bower install dependent-dropdown

Node Package Manager


Installation via NPM is as simple as running:

$ npm install dependent-dropdown

Composer Package Manager


You can install dependent-dropdown via composer package manager. Either run:

$ php composer.phar require kartik-v/dependent-dropdown "dev-master"

or add:

"kartik-v/dependent-dropdown": "dev-master"

to your composer.json file

Manual Install


You can also manually install the plugin easily to your project. Just download the source ZIP or TAR ball and extract the plugin asset files and folders into your project.

Step 1: Load the following assets in your header.


<link href="path/to/css/dependent-dropdown.min.css" media="all" rel="stylesheet" type="text/css" />

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>

<script src="path/to/js/dependent-dropdown.min.js" type="text/javascript"></script>

<-- optionally load the locales file if needed -->

<script src="path/to/js/locales/.js" type="text/javascript"></script>

If you noticed, you need to load the jquery.min.js in addition to the dependent-dropdown.min.css and dependent-dropdown.min.js. The locale file js/locales/.js can be optionally included for translating for your language if needed./p>

Step 2: Setup your select input markup to. Automatically set dependent dropdowns by adding the class depdrop and setting data attributes. NOTE: All select inputs must have a defined ID attribute for the plugin to work.


<select id="parent-1">

   <!-- your select options -->

</select>



<select id="child-1" class="depdrop" data-depends="['parent-1']" data-url="/path/to/child_1_list">

   <!-- your select options -->

</select>



<select id="child-2" class="depdrop" data-depends="['parent-1, 'child-1']" data-url="/path/to/child_2_list">

   <!-- your select options -->

</select>

Step 2 (Alternative): You can initialize the plugin via javascript for your dependent dropdowns. For example,


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

    depends: ['parent-1'],

    url: '/path/to/child_1_list'

});



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

    depends: ['parent-1', 'child-1'],

    url: '/path/to/child_2_list'

});

The dependent dropdown plugin requires a right ajax response for displaying the child dropdown items. The server action code as set in url property must return a JSON encoded response of the following format:


{output: output, selected: selected}

Must be sent as a string. This identifies the selected option value for the dependent child dropdown.

Must be sent as a object|array. This must be a JSON encoded object that returns the dropdown items for your child select/dropdown. This can be returned in two different formats:

An array of objects with each array item containing the following keys:

  • id: string, this is the HTML identifier for each option element. The name of the key defaults to id, but it could be changed by setting the idParam property.

  • name: string, this is the value for each option element. The name of the key defaults to name, but it could be changed by setting the nameParam property.

  • options: object, key value pairs of HTML attributes for each option element.

An example of a json encoded response format for child options without groups is shown below:


[

    {id: 'id1', name: 'Name 1', options: {style: 'color:blue', disabled: false}},

    {id: 'id2', name: 'Name 2', options: {style: 'color:gray', disabled: true}},

    {id: 'id3', name: 'Name 3', options: {style: 'color:blue', disabled: false}},

]

The difference in this case is that child options with groups must be returned as a multi dimensional object with groups as shown below:


{

    'group-1': [

        {id: 'id1', name: 'Name 1', options: {style: 'color:blue', disabled: false}},

        {id: 'id2', name: 'Name 2', options: {style: 'color:gray', disabled: true}},

        {id: 'id3', name: 'Name 3', options: {style: 'color:blue', disabled: false}},

    ],

    'group-2': [

        {id: 'id4', name: 'Name 4', options: {style: 'color:blue', disabled: false}},

        {id: 'id5', name: 'Name 5', options: {style: 'color:gray', disabled: true}},

        {id: 'id6', name: 'Name 6', options: {style: 'color:blue', disabled: false}},

    ]

}

The group-1 and group-2 identify the labels for each option group.

The plugin supports these following options:

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

    }

}

Note

In addition to depdrop_params, the plugin sends depdrop_all_params as an associative array of keys and values. This is sent merged along with the keys and values of depdrop_parents. Read more about this in the url section below.

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

}

Note

If you return a null value or an empty array from the server, the plugin will display the emptyMsg in the dependent dropdown. The dependent select will always be disabled until the server returns a valid list of values.

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.

The plugin supports these events:

depdrop:init

This event is triggered when the dependent dropdown is initialized with values, after document is loaded and ready.

Example:

$('#input-id').on('depdrop:init', function(event) {

    // perform any action

});

depdrop:change

This event is triggered when a dependent parent input is modified or changed. This event also allows you to access these parameters:
  • id: the parent dependent dropdown element id.

  • value: the parent dependent dropdown value.

  • count: the count of options generated in the dependent dropdown.

  • textStatus: string, ajax error status e.g. success, notmodified, nocontent, timeout, error, abort, and parsererror.

  • jqXHR: jQuery XMLHttpRequest, object used for this transaction.

Example:


$('#child-1').on('depdrop:change', function(event, id, value, count, textStatus, jqXHR) {

    console.log(value);

    console.log(count);

});

depdrop:beforeChange

This event is triggered when a dependent parent input is modified or changed and before the ajax response is sent to the server. This event also allows you to access these parameters:

  • id: string, the parent dependent dropdown element id.

  • value: string, the parent dependent dropdown value.

  • jqXHR: jQuery XMLHttpRequest, object used for this transaction.

Example:


$('#child-1').on('depdrop:beforeChange', function(event, id, value, jqXHR) {

    console.log(value);

});

depdrop:afterChange

This event is triggered when a dependent parent input is modified or changed and after the ajax response is processed by the server. This event also allows you to access these parameters:

  • id: string, the parent dependent dropdown element id.

  • value: string, the parent dependent dropdown value.

  • jqXHR: jQuery XMLHttpRequest, object used for this transaction.

  • textStatus: string, ajax error status e.g. success, notmodified, nocontent, timeout, error, abort, and parsererror.

Example:


$('#child-1').on('depdrop:afterChange', function(event, id, value, jqXHR, textStatus) {

    console.log(value);

});

depdrop:error

This event is triggered when a dependent parent input is modified or changed and if an error is faced within the ajax response processed by the server. This event also allows you to access these parameters:

  • id: string, the parent dependent dropdown element id.

  • value: string, the parent dependent dropdown value.

  • jqXHR: jQuery XMLHttpRequest, object used for this transaction.

  • textStatus: string, ajax error status e.g. timeout, error, abort, and parsererror.

  • errorThrown: string, when an HTTP error occurs, this shows the textual portion of the HTTP status, such as Not Found or Internal Server Error.

Example:


$('#child-1').on('depdrop:error', function(event, id, value, jqXHR, textStatus, errorThrown) {

    console.log(errorThrown);

});

The plugin supports these methods:

init

Initialize the dependent dropdown.


$('#input-id').depdrop('init');

getAjaxResults

Returns the output data for the last ajax operation for the dependent dropdown.


var ajaxResults = $('#input-id').depdrop('getAjaxResults');

The plugin has been implemented as extensions in the following frameworks

Sl.FrameworkExtension SourceDeveloped ByExtension Demo
1.Yii Framework 2.0Yii2 WidgetsKrajee Yii2 Dependent Dropdown

Do you know any other framework extension using this plugin which is not listed here? Tell us so that we can consider its inclusion in this list.

dependent-dropdown is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.

Note

You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.

The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.

 
visitors to Krajee Jquery Plugins since 22-May-2017