Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dnasir/jquery-cascading-dropdown
A simple and lighweight jQuery plugin for cascading dropdown.
https://github.com/dnasir/jquery-cascading-dropdown
Last synced: 7 days ago
JSON representation
A simple and lighweight jQuery plugin for cascading dropdown.
- Host: GitHub
- URL: https://github.com/dnasir/jquery-cascading-dropdown
- Owner: dnasir
- Created: 2012-11-14T14:37:02.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2022-12-06T16:02:39.000Z (almost 2 years ago)
- Last Synced: 2024-04-15T00:14:48.197Z (7 months ago)
- Language: HTML
- Size: 326 KB
- Stars: 228
- Watchers: 24
- Forks: 83
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# jQuery Cascading Dropdown Plugin
A simple and lighweight jQuery plugin for creating cascading dropdowns.
[View Demo](https://dnasir.github.io/jquery-cascading-dropdown/)
## Installation
```
npm install --save jquery-cascading-dropdown
```
Include script after the jQuery library (unless you are packaging scripts somehow else):
```html
```
## Usage
To initialize the plugin, simply attach it to the parent group of dropdown elements.
```html
Select type
...
```
```javascript
$('#dropdowns').cascadingDropdown(options);
```
## Options
#### usePost (boolean)
usePost: false
Added: 1.1.0
Tells the plugin to use POST when sending Ajax request.
#### UseJson (boolean)
useJson: false
Added: 1.1.2
Tells the plugin to stringify (JSON.stringify) dropdown data for Ajax requests. Requires
[json2.js](https://github.com/douglascrockford/JSON-js) if you're planning to support older browsers.
#### onReady (eventHandler)
onReady: function(event, allValues) { }
Added: 1.2.0
An event that is triggered when the plugin is completely initialised. The event handler will be provided with the event object, and an object containing the current values of all the dropdowns in the group.
#### onChange (eventHandler)
onChange: function(event, allValues) { }
Added: 1.2.0
An event that is triggered whenever the value of a dropdown in a particular group is changed. The event handler will be provided with the event object, and an object containing the current values of all the dropdowns in the group.
#### isLoadingClassName (string)
Added: 1.2.2
isLoadingClassName: 'cascading-dropdown-loading'
This overrides the default value for the class name applied to the dropdown element during Ajax calls.
#### selectBoxes
selectBoxes: [
{
selector: '.select1',
...
}
]
Added: 1.0.0
Array of dropdown objects
#### Dropdown object properties
##### selector (string)
selector: '.selectbox1'
Added: 1.0.0
Selector for select box inside parent container. (Required)
##### source (string|function)
source: '/api/CompanyInfo/GetCountries'
source: function(request, response) {
$.getJSON('path/to/api', request, function(data) {
response($.map(data, function(item, index) {
return {
label: item.itemLabel,
value: item.itemValue
}
}));
});
}
Added: 1.2.0
Source for dropdown items. This can be a URL pointing to the web service that provides the dropdown items, or a function that manually handles the Ajax request and response.
If a URL is provided, the web service needs to follow a convention where the object returned must be a JSON object containing an array of objects, each containing at least a key-value property named 'label', or 'value'.
Example JSON object
[
{
"label": "Item 1",
"value": "1"
},
{
"label": "Item 2",
"value": "2"
}
]
It's also possible to include a property named 'selected' in the object to define a selected item.
It is also possible to create option groups in the select by specifying a key (the group name) in the JSON.
Example JSON object with groups
{
'My Group':
[
{
"label": "Item 1",
"value": "1"
},
{
"label": "Item 2",
"value": "2"
}
],
'Another Group':
[
{
"label": "Item 3",
"value": "3"
},
{
"label": "Item 4",
"value": "4"
}
]
}
If the source parameter is not set, the plugin will simply enable the select box when requirements are met.
##### requires (array)
requires: ['.selectbox1']
Added: 1.0.0
Array of dropdown selectors required to have value before this dropdown is enabled.
##### requireAll (boolean)
requireAll: true
Added: 1.0.0
If set to true, all dropdowns defined in the requires array must have a value before this dropdown is enabled.
If this value is set to false, this dropdown will be enabled if any one of the required dropdowns is valid.
##### paramName (string)
paramName: 'countryId'
Added: 1.0.0
Required dropdown value parameter name used in Ajax requests. If this value is not set, the plugin will use the dropdown name attribute. If neither this parameter nor the name attribute is set, this dropdown will not be taken into account in any Ajax request.
##### selected (string|integer)
selected: 'red'
selected: 2
Added: 1.1.5
Sets the default dropdown item on initialisation. The value can be a the value of the targeted dropdown item, or its index value.
##### onChange (eventHandler)
onChange: function(event, value, requiredValues, requirementsMet) { }
Added: 1.0.0
Updated: 1.2.4
Event handler triggered when the dropdown value is changed. The event handler is passed the event object, the value of the current dropdown, and an object containing the values of all the required dropdowns. A boolean value indicating whether the requirements for a particular dropdown have been met or not is also passed.
## Methods
#### destroy
Destroys the instance and reverts everything back to their initial state.
```javascript
$('#dropdown').cascadingDropdown('destroy');
```
Added: 1.2.7
## Server-side implementation
By default, this plugin expects the web service to return a JSON object containing an array of objects with properties 'label' and 'value'. The web service may also include a 'selected' property for an object within an array to indicate that that particular object is to be the selected item.
```json
// Example server response
[
{
"label": "Item 1",
"value": "1"
},
{
"label": "Item 2",
"value": "2",
"selected": true
}
]
```
If the value property is not defined, the dropdown item will set the label as the value, and vice versa.