diff --git a/CHANGE.md b/CHANGE.md index 59a3890..2449dda 100644 --- a/CHANGE.md +++ b/CHANGE.md @@ -1,27 +1,24 @@ Change Log: `dependent-dropdown` ================================ -## Version 1.4.4 +## version 1.4.4 -**Date:** 26-Oct-2015 +**Date:** 16-Dec-2015 -1. (enh #30): Better validation for undefined groups key param. +1. (enh #29): Ability to configure and extend ajax settings +2. (enh #33): Add language and localization support. +3. (enh #34): Make all parameter names configurable. +4. (enh #35): AMD and Node Common JS Support. +5. (enh #36): Enhance ability to configure HTML attributes for each option. -## Version 1.4.3 - -**Date:** 14-Jul-2015 - -1. (enh #27): Better validation for value selected. -2. (enh #28): Ability to configure HTML attributes for each option element via ajax. - -## Version 1.4.2 +## version 1.4.2 **Date:** 18-Jun-2015 1. (enh #23): New property `initDepends` to set all dependent parents in the chain. 2. (enh #24): Enhancement for Select2 plugin. -## Version 1.4.1 +## version 1.4.1 **Date:** 22-May-2015 @@ -30,7 +27,7 @@ Change Log: `dependent-dropdown` 3. (bug kartik-v/yii2-widget-depdrop#10): Fix process dependency params. 4. (enh #22): Fixes for JQuery v2.1.4 & Select2. -## Version 1.4.0 +## version 1.4.0 **Date:** 01-Feb-2015 @@ -41,20 +38,20 @@ Change Log: `dependent-dropdown` 5. (enh #15): Implement reusable constructor for extending plugin if needed. 6. (enh #16): Enhance Select2 dropdowns to show loading indicator. -## Version 1.3.0 +## version 1.3.0 **Date:** 08-Nov-2014 1. Set release to stable in composer.json. 2. Updated CHANGE log to reflect user friendly date time formats. -## Version 1.2.0 +## version 1.2.0 **Date:** 02-Jul-2014 - Enh #8: Ability to pass additional form input data within each ajax call. -## Version 1.1.0 +## version 1.1.0 **Date:** 05-May-2014 @@ -63,7 +60,7 @@ Change Log: `dependent-dropdown` - Added support for plugin to work with other plugins like Select2. -## Version 1.0.0 +## version 1.0.0 **Date:** 30-Apr-2014 diff --git a/README.md b/README.md index 4c398a2..d3fdd9a 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,9 @@ dependent-dropdown [![Packagist Downloads](https://poser.pugx.org/kartik-v/dependent-dropdown/downloads)](https://packagist.org/packages/kartik-v/dependent-dropdown) [![Monthly Downloads](https://poser.pugx.org/kartik-v/dependent-dropdown/d/monthly)](https://packagist.org/packages/kartik-v/dependent-dropdown) -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. +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. -> NOTE: The latest version of the plugin v1.4.3 has been released. Refer the [CHANGE LOG](https://github.com/kartik-v/dependent-dropdown/blob/master/CHANGE.md) for details. +> NOTE: The latest version of the plugin v1.4.4 has been released. Refer the [CHANGE LOG](https://github.com/kartik-v/dependent-dropdown/blob/master/CHANGE.md) for details. ## Features @@ -31,7 +29,7 @@ with normal select options and select with optgroups as well. - Size of the entire plugin is less than 4KB (about 3KB for the minified JS and 1KB for the minified CSS). - Ability to configure HTML attributes of each `option` element via ajax response (for example dynamically disabling some dropdown options or adding styles). -## Demo +## Documentation and Demo View the [plugin documentation](http://plugins.krajee.com/dependent-dropdown) and [plugin demos](http://plugins.krajee.com/dependent-dropdown/demo) at Krajee JQuery plugins. @@ -66,12 +64,6 @@ View the [plugin documentation](http://plugins.krajee.com/dependent-dropdown) an ``` {group-name: {id: , name: }} ``` - - When no data is available for a specific situation (like an backend error), you can send a custom emptyMsg - - ``` - {emptyMsg: ''} - ``` ## Installation @@ -106,10 +98,11 @@ plugin assets (css and js folders) into your project. + + ``` -If you noticed, you need to load the `jquery.min.js` in addition to the `dependent-dropdown.min.css` and -`dependent-dropdown.min.js` for the plugin to work with default settings. +If you noticed, you need to load the `jquery.min.js` in addition to the `dependent-dropdown.min.css` and `dependent-dropdown.min.js` for the plugin to work with default settings. The locale file `depdrop_locale_.js` can be optionally included for translating for your language if needed. **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. @@ -143,217 +136,6 @@ $("#child-2").depdrop({ ``` -## Documentation - -### Plugin Options -The plugin supports these following options: - -##### 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. - -##### initDepends -_array_ the list of INITIAL nested parent input`ID` attributes on which the current dropdown is dependent on. This is applicable only when`initialize` is set to`true` (for firing the ajax requests on page initialization). Usually 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 to`depends`. For example you could use`depends` and`initDepends` in the following manner: - -```js -$("#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 list of 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: - -```php - if (!empty($_POST['depdrop_params'])) { - $params = $_POST['depdrop_params']; - $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: , selected: }`. -where, the `output` is an array of data for the dependent list of the format `{id: , name: }`, -and `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: , 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`). The keys are the element identifiers for dependent dropdown parent elements and the element identifiers set via `params` property. -This can be read by the server action to generate a dependent dropdown list. An example for a PHP server action could be: - -```php -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. - */ - 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. - -##### 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). - -##### loading -_boolean_ whether to show a loading progress spin indicator and the loading text in the child dropdown element 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 option item via json response. Defaults to `id`. - -##### nameParam -_string_ the name of the parameter that returns the `name` value for each list option item via json response. Defaults to `name`. - -### Plugin Events -The plugin supports these events: - -#### depdrop.init -This event is triggered when the dependent dropdown is initialized. - -#### depdrop.ready -This event is triggered when the dependent dropdown is initialized with values, after document is loaded and ready. - -**Example:** -```js -$('#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. -- `initVal`: the initial preselected value in the dependent dropdown. - Defaults to `false` if not set. - -**Example:** -```js -$('#child-1').on('depdrop.change', function(event, id, value, count) { - 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`: the parent dependent dropdown element id. -- `value`: the parent dependent dropdown value. -- `initVal`: the initial preselected value in the dependent dropdown. - Defaults to `false` if not set. - -**Example:** -```js -$('#child-1').on('depdrop.beforeChange', function(event, id, value) { - 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`: the parent dependent dropdown element id. -- `value`: the parent dependent dropdown value. -- `initVal`: the initial preselected value in the dependent dropdown. - Defaults to `false` if not set. - -**Example:** -```js -$('#child-1').on('depdrop.afterChange', function(event, id, value) { - console.log(value); -}); -``` - -#### depdrop.error -This event is triggered when a dependent parent input is modified or changed and if an error is faced in -the ajax response processed by the server. This event also allows you to access these parameters: - -- `id`: the parent dependent dropdown element id. -- `value`: the parent dependent dropdown value. -- `initVal`: the initial preselected value in the dependent dropdown. - Defaults to `false` if not set. - -**Example:** -```js -$('#child-1').on('depdrop.error', function(event, id, value) { - console.log(value); -}); -``` - -### Plugin Methods -The plugin supports these methods: - -#### init -Initialize the dependent dropdown. -```js -$('#input-id').depdrop('init'); -``` - ## License -**dependent-dropdown** is released under the BSD 3-Clause License. See the bundled `LICENSE.md` for details. +**dependent-dropdown** is released under the BSD 3-Clause License. See the bundled `LICENSE.md` for details. \ No newline at end of file diff --git a/bower.json b/bower.json index 83c7f0b..dfe2129 100644 --- a/bower.json +++ b/bower.json @@ -1,6 +1,6 @@ { "name": "dependent-dropdown", - "version": "1.4.3", + "version": "1.4.4", "homepage": "https://github.com/kartik-v/dependent-dropdown", "authors": [ "Kartik Visweswaran " diff --git a/css/dependent-dropdown.css b/css/dependent-dropdown.css index b7912ea..47e8c26 100644 --- a/css/dependent-dropdown.css +++ b/css/dependent-dropdown.css @@ -1,6 +1,6 @@ /*! * @copyright Copyright © Kartik Visweswaran, Krajee.com, 2013 - 2015 - * @version 1.4.3 + * @version 1.4.4 * * Styling for the dependent-dropdown JQuery plugin. * diff --git a/css/dependent-dropdown.min.css b/css/dependent-dropdown.min.css index e9ab5c1..66b7797 100644 --- a/css/dependent-dropdown.min.css +++ b/css/dependent-dropdown.min.css @@ -1,6 +1,6 @@ /*! * @copyright Copyright © Kartik Visweswaran, Krajee.com, 2013 - 2015 - * @version 1.4.3 + * @version 1.4.4 * * Styling for the dependent-dropdown JQuery plugin. * diff --git a/js/depdrop_locale_LANG.js b/js/depdrop_locale_LANG.js new file mode 100644 index 0000000..be4e965 --- /dev/null +++ b/js/depdrop_locale_LANG.js @@ -0,0 +1,19 @@ +/*! + * Dependent Dropdown Translations + * + * This file must be loaded after 'dependent-dropdown.js'. Patterns in braces '{}', or + * any HTML markup tags in the messages must not be converted or translated. + * + * @see http://github.com/kartik-v/dependent-dropdown + * + * NOTE: this file must be saved in UTF-8 encoding. + */ +(function ($) { + "use strict"; + + $.fn.depdropLocales[''] = { + loadingText: 'Loading ...', + placeholder: 'Select ...', + emptyMsg: 'No data found' + }; +})(window.jQuery); \ No newline at end of file diff --git a/js/depdrop_locale_de.js b/js/depdrop_locale_de.js new file mode 100644 index 0000000..b6f2a3b --- /dev/null +++ b/js/depdrop_locale_de.js @@ -0,0 +1,19 @@ +/*! + * Dependent Dropdown German Translations + * + * This file must be loaded after 'dependent-dropdown.js'. Patterns in braces '{}', or + * any HTML markup tags in the messages must not be converted or translated. + * + * @see http://github.com/kartik-v/dependent-dropdown + * + * NOTE: this file must be saved in UTF-8 encoding. + */ +(function ($) { + "use strict"; + + $.fn.depdropLocales['de'] = { + loadingText: 'Laden ...', + placeholder: 'Auswählen ...', + emptyMsg: 'Keine Daten gefunden' + }; +})(window.jQuery); \ No newline at end of file diff --git a/js/depdrop_locale_es.js b/js/depdrop_locale_es.js new file mode 100644 index 0000000..ee5e626 --- /dev/null +++ b/js/depdrop_locale_es.js @@ -0,0 +1,19 @@ +/*! + * Dependent Dropdown Spanish Translations + * + * This file must be loaded after 'dependent-dropdown.js'. Patterns in braces '{}', or + * any HTML markup tags in the messages must not be converted or translated. + * + * @see http://github.com/kartik-v/dependent-dropdown + * + * NOTE: this file must be saved in UTF-8 encoding. + */ +(function ($) { + "use strict"; + + $.fn.depdropLocales['es'] = { + loadingText: 'Cargando ...', + placeholder: 'Seleccionar ...', + emptyMsg: 'Datos no encontrados' + }; +})(window.jQuery); \ No newline at end of file diff --git a/js/depdrop_locale_fr.js b/js/depdrop_locale_fr.js new file mode 100644 index 0000000..9a65a3b --- /dev/null +++ b/js/depdrop_locale_fr.js @@ -0,0 +1,19 @@ +/*! + * Dependent Dropdown French Translations + * + * This file must be loaded after 'dependent-dropdown.js'. Patterns in braces '{}', or + * any HTML markup tags in the messages must not be converted or translated. + * + * @see http://github.com/kartik-v/dependent-dropdown + * + * NOTE: this file must be saved in UTF-8 encoding. + */ +(function ($) { + "use strict"; + + $.fn.depdropLocales['fr'] = { + loadingText: 'Chargement ...', + placeholder: 'Sélectionner ...', + emptyMsg: 'Aucune donnée disponible' + }; +})(window.jQuery); \ No newline at end of file diff --git a/js/depdrop_locale_ru.js b/js/depdrop_locale_ru.js new file mode 100644 index 0000000..3eb45aa --- /dev/null +++ b/js/depdrop_locale_ru.js @@ -0,0 +1,19 @@ +/*! + * Dependent Dropdown Russian Translations + * + * This file must be loaded after 'dependent-dropdown.js'. Patterns in braces '{}', or + * any HTML markup tags in the messages must not be converted or translated. + * + * @see http://github.com/kartik-v/dependent-dropdown + * + * NOTE: this file must be saved in UTF-8 encoding. + */ +(function ($) { + "use strict"; + + $.fn.depdropLocales['ru'] = { + loadingText: 'загрузка ...', + placeholder: 'Выбрать ...', + emptyMsg: 'Данные не найдены' + }; +})(window.jQuery); \ No newline at end of file diff --git a/js/dependent-dropdown.js b/js/dependent-dropdown.js index d84503b..9c83501 100644 --- a/js/dependent-dropdown.js +++ b/js/dependent-dropdown.js @@ -1,48 +1,68 @@ /*! * @copyright © Kartik Visweswaran, Krajee.com, 2013 - 2015 - * @version 1.4.3 + * @version 1.4.4 * - * A multi level dependent dropdown JQuery plugin. The plugin - * allows nested and combined dependencies. + * A multi level dependent dropdown JQuery plugin. The plugin allows nested and combined dependencies. * * For more JQuery plugins visit http://plugins.krajee.com * For more Yii related demos visit http://demos.krajee.com */ -(function ($) { +(function (factory) { "use strict"; - var isEmpty = function (value, trim) { - return value === null || value === undefined || value.length === 0 || (trim && $.trim(value) === ''); - }, - addOption = function ($el, id, name, sel, opts) { - var settings = {value: id, text: name}; - opts = opts || {}; - settings = $.extend(settings, opts); - if (sel !== null && sel.length && id.toString() === sel) { - settings.selected = "selected"; - } - $("",{label:t});e.each(n,function(e,t){o=t.options||{},a(d,t[p],t[s],i)}),d.appendTo(l)}}),l.html()}},e.fn.depdrop=function(t){var a=Array.apply(null,arguments);return a.shift(),this.each(function(){var n=e(this),i=n.data("depdrop"),o="object"==typeof t&&t;i||(i=new d(this,e.extend({},e.fn.depdrop.defaults,o,e(this).data())),n.data("depdrop",i)),"string"==typeof t&&i[t].apply(i,a)})},e.fn.depdrop.defaults={url:"",loading:!0,loadingClass:"kv-loading",loadingText:"Loading ...",placeholder:"Select ...",emptyMsg:"No data found",initialize:!1,idParam:"id",nameParam:"name",params:{}},e.fn.depdrop.Constructor=d,e(function(){e("select.depdrop").depdrop()})}(window.jQuery); \ No newline at end of file + */!function(e){"use strict";"function"==typeof define&&define.amd?define(["jquery"],e):"object"==typeof module&&module.exports?module.exports=e(require("jquery")):e(window.jQuery)}(function(e){"use strict";e.fn.depdropLocales={};var t,a,n,d;t=function(t,a){return null===t||void 0===t||0===t.length||a&&""===e.trim(t)},a=function(t,a,n,d,o){var r={value:a,text:n};o=o||{},r=e.extend(r,o),null!==d&&d.length&&a.toString()===d&&(r.selected="selected"),e("")},success:function(n){l=t(n.selected)?f.initVal===!1?null:f.initVal:n.selected,t(n)?a(d,"",D,""):(d.html(f.getSelect(n.output,b,l)),d.find("optgroup").length>0&&d.find('option[value=""]').attr("disabled","disabled"),n.output&&d.removeAttr("disabled")),g=d.find("option").length,d.find('option[value=""]').length>0&&(g-=1),d.trigger("depdrop.change",[o,e("#"+o).val(),g,f.initVal])},error:function(){d.trigger("depdrop.error",[o,e("#"+o).val(),f.initVal])},complete:function(){P&&d.removeClass(j),d.trigger("depdrop.afterChange",[o,e("#"+o).val(),f.initVal])}},p=e.extend(p,f.ajaxSettings),e.ajax(p)},getSelect:function(n,d,o){var r,i=this,l=e("