Add ability to accept and display optgroups

Added ability to parse and create option groups in the select
Updated the README to explain the JSON object expected for option groups
Added a demo item (example5) to show this functionallity
Added call in ajax-mocks that groups the resolutions for the demo

Author: dfisch

README.md

@@ -1,6 +1,6 @@
 # jQuery Cascading Dropdown Plugin
 
-A simple and lighweight jQuery plugin for creating cascading dropdowns. 
+A simple and lighweight jQuery plugin for creating cascading dropdowns.
 
 [View Demo](http://dnasir.com/github/jquery-cascading-dropdown/demo.html)
 
@@ -28,7 +28,7 @@ Tells the plugin to use POST when sending Ajax request.
 
 <sub>Added: 1.1.2</sub>
 
-Tells the plugin to stringify (JSON.stringify) dropdown data for Ajax requests. Requires 
+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)
@@ -114,6 +114,36 @@ Example JSON object
 
 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)
@@ -149,7 +179,7 @@ Required dropdown value parameter name used in Ajax requests. If this value is n
 
 <sub>Added: 1.1.5</sub>
 
-Sets the default dropdown item on initialisation. The value can be a the value of the targeted dropdown item, or its index value. 
+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)
 

ajax-mocks.js

@@ -120,10 +120,34 @@ function getResolutions(screen, storage) {
 	var phones = getPhones(screen, null, storage);
 
 	var resolutions = $.map(phones, function(phone) { return phone.resolution; });
+
 	resolutions.sort(asc);
 	return arrayUnique(resolutions);
 }
 
+function getGroupedResolutions(screen, storage) {
+	var phones = getPhones(screen, null, storage);
+
+	// Create SD and HD resolution groups
+	// SD <= 540
+	// HD >= 720
+	var groupedResolutions = {'SD': [], 'HD': []};
+	$.each(phones, function(index, item) {
+		if (item.resolution <= 540) {
+			groupedResolutions.SD.push(item.resolution);
+		} else {
+			groupedResolutions.HD.push(item.resolution);
+		}
+	});
+
+	$.each(groupedResolutions, function(key, value) {
+		value.sort(asc);
+		groupedResolutions[key] = arrayUnique(value);
+	});
+
+	return groupedResolutions;
+}
+
 function getStorages(screen, resolution) {
 	var phones = getPhones(screen, resolution, null);
 
@@ -169,6 +193,15 @@ $.mockjax({
 	}
 });
 
+$.mockjax({
+	url: '/api/resolutionsGrouped',
+	contentType: 'application/json; charset=utf-8',
+	responseTime: 1000,
+	response: function(settings){
+		this.responseText = JSON.stringify(getGroupedResolutions(settings.data.screen, settings.data.storage));
+	}
+});
+
 $.mockjax({
 	url: '/api/storages',
 	contentType: 'application/json; charset=utf-8',
@@ -185,4 +218,4 @@ $.mockjax({
 	response: function(settings){
 		this.responseText = JSON.stringify(getPhones(settings.data.screen, settings.data.resolution, settings.data.storage));
 	}
-});
+});

demo.html

@@ -273,6 +273,90 @@ <h6>Code</h6>
 
 			<br />
 
+			<h4>Option Group</h4>
+			<p>This example demonstrates the plugin's capability to combine both standard and grouped (option group) dropdowns.</p>
+
+			<div id="example5" class="bs-docs-example">
+				<h4>Phone finder</h4>
+
+				<select class="step1" name="screen">
+					<option value="">Screen size</option>
+					<option value="4" selected="selected">4.0"</option>
+					<option value="4.3">4.3"</option>
+					<option value="4.7">4.7"</option>
+					<option value="5">5.0"</option>
+				</select>
+				<select class="step2" name="resolution">
+					<option value="">Screen resolution</option>
+				</select>
+				<select class="step3" name="storage">
+					<option value="">Storage size</option>
+				</select>
+
+				<h4>Matches <img src="ajax-loader.gif" data-bind="visible: loading" /></h4>
+				<ul data-bind="foreach: phones, visible: phones().length > 0">
+					<li>
+						<span data-bind="text: maker"></span>
+						<span data-bind="text: model"></span>
+					</li>
+				</ul>
+				<p data-bind="visible: phones().length == 0">No matches</p>
+			</div>
+
+			<h6>Code</h6>
+			<div>
+				<pre class="brush: js">$('#example5').cascadingDropdown({
+	selectBoxes: [
+	{
+		selector: '.step1'
+	},
+	{
+		selector: '.step2',
+		source: function(request, response) {
+			$.getJSON('/api/resolutionsGrouped', request, function(data) {
+				var newData = {};
+				$.each(data, function(key, value) {
+					newData[key] = $.map(value, function(item, index) {
+						return {
+							label: item + 'p',
+							value: item
+						};
+					});
+				});
+
+				response(newData);
+			});
+		}
+	},
+	{
+		selector: '.step3',
+		requires: ['.step1', '.step2'],
+		requireAll: true,
+		source: function(request, response) {
+			$.getJSON('/api/storages', request, function(data) {
+				response($.map(data, function(item, index) {
+					return {
+						label: item + ' GB',
+						value: item,
+						selected: index == 0 // set to true to mark it as the selected item
+					};
+				}));
+			});
+		}
+	}
+	],
+	onChange: function(event, dropdownData) {
+		// do stuff
+		// dropdownData is an object with values from all the dropdowns in this group
+	},
+	onReady: function(event, dropdownData) {
+		// do stuff
+	}
+});</pre>
+			</div>
+
+			<br />
+
 			<h4>Multiple select</h4>
 			<p>You can enable multiple select by including the <code>multiple</code> attribute. The value for the dropdown will then be an array of strings instead of a string. However, you will need to ensure that your backend service supports this type of data.</p>
 
@@ -321,11 +405,13 @@ <h4>Matches <img src="ajax-loader.gif" data-bind="visible: loading" /></h4>
 				example2 = new viewmodel(),
 				example3 = new viewmodel(),
 				example4 = new viewmodel();
+				example5 = new viewmodel();
 
 			ko.applyBindings(example1, document.getElementById('example1'));
 			ko.applyBindings(example2, document.getElementById('example2'));
 			ko.applyBindings(example3, document.getElementById('example3'));
 			ko.applyBindings(example4, document.getElementById('example4'));
+			ko.applyBindings(example5, document.getElementById('example5'));
 
 			// Example 1
 			$('#example1').cascadingDropdown({
@@ -356,7 +442,7 @@ <h4>Matches <img src="ajax-loader.gif" data-bind="visible: loading" /></h4>
 					}
 				]
 			});
-			
+
 			// Example 2
 			$('#example2').cascadingDropdown({
 				selectBoxes: [
@@ -410,7 +496,7 @@ <h4>Matches <img src="ajax-loader.gif" data-bind="visible: loading" /></h4>
 					}
 				]
 			});
-			
+
 			// Example 3
 			$('#example3').cascadingDropdown({
 				selectBoxes: [
@@ -516,11 +602,68 @@ <h4>Matches <img src="ajax-loader.gif" data-bind="visible: loading" /></h4>
 					});
 				}
 			});
+
+			// Example 5
+			$('#example5').cascadingDropdown({
+				selectBoxes: [
+				{
+					selector: '.step1'
+				},
+				{
+					selector: '.step2',
+					source: function(request, response) {
+						$.getJSON('/api/resolutionsGrouped', request, function(data) {
+							var newData = {};
+							$.each(data, function(key, value) {
+								newData[key] = $.map(value, function(item, index) {
+									return {
+										label: item + 'p',
+										value: item
+									};
+								});
+							});
+
+							response(newData);
+						});
+					}
+				},
+				{
+					selector: '.step3',
+					requires: ['.step1', '.step2'],
+					requireAll: true,
+					source: function(request, response) {
+						$.getJSON('/api/storages', request, function(data) {
+							response($.map(data, function(item, index) {
+								return {
+									label: item + ' GB',
+									value: item,
+									selected: index == 0 // set to true to mark it as the selected item
+								};
+							}));
+						});
+					}
+				}
+				],
+				onChange: function(event, dropdownData) {
+					example5.loading(true);
+					$.getJSON('/api/phones', dropdownData, function(data) {
+						example5.phones(data);
+						example5.loading(false);
+					});
+				},
+				onReady: function(event, dropdownData) {
+					example5.loading(true);
+					$.getJSON('/api/phones', dropdownData, function(data) {
+						example5.phones(data);
+						example5.loading(false);
+					});
+				}
+			});
 		</script>
 		<script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/scripts/shCore.js"></script>
 		<script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/SyntaxHighlighter/3.0.83/scripts/shBrushJScript.js"></script>
 		<script type="text/javascript">
 			SyntaxHighlighter.all();
 		</script>
 	</body>
-</html>
+</html>

jquery.cascadingdropdown.js

@@ -1,4 +1,4 @@
-/* 
+/*
  *   jQuery Cascading Dropdown Plugin 1.2.5
  *   https://github.com/dnasir/jquery-cascading-dropdown
  *
@@ -194,25 +194,42 @@
             var self = this;
 
             // Remove all dropdown items and restore to initial state
-            self.el.children('option').remove();
+            self.el.find('option, optgroup').remove();
             self.el.append(self.originalDropdownItems);
 
-            if(!items || !items.length) {
+            if(!items) {
                 self._triggerReady();
                 return;
             }
 
             var selected;
 
             // Add all items as dropdown item
-            $.each(items, function(index, item) {
-                var selectedAttr = '';
-                if(item.selected) {
-                    selected = item;
+            var getOption = function(item) {
+              var selectedAttr = '';
+              if(item.selected) {
+                selected = item;
+              }
+
+              return '<option value="' + item.value + '"' + selectedAttr + '>' + item.label + '</option>';
+            };
+
+            if ($.isArray(items)) {
+              $.each(items, function(index, item) {
+                self.el.append(getOption(item));
+              });
+            } else {
+              $.each(items, function(key, value) {
+                var itemData = [];
+                itemData.push('<optgroup label="' + key + '">');
+                for (var i = 0; i < value.length; i++) {
+                  var item = value[i];
+                  itemData.push(getOption(item));
                 }
-
-                self.el.append('<option value="' + item.value + '"' + selectedAttr + '>' + item.label + '</option>');
-            });
+                itemData.push('</optgroup>');
+                self.el.append(itemData.join(''));
+              });
+            }
 
             // Enable the dropdown
             self.enable();
@@ -280,7 +297,7 @@
 
             // Instance array
             self.dropdowns = [];
-            
+
             var dropdowns = $($.map(self.options.selectBoxes, function(item) {
                 return item.selector;
             }).join(','), self.el);
@@ -297,7 +314,7 @@
             function changeEventHandler(event) {
                 self.options.onChange.call(self, event, self.getValues());
             }
-            
+
             if(typeof self.options.onReady === 'function') {
                 dropdowns.bind('ready', readyEventHandler);
             }