Manual merge for PR #38

Author: dnasir

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)
 
@@ -32,7 +32,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)
@@ -118,6 +118,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)
@@ -153,7 +183,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)
 

dist/jquery.cascadingdropdown.js

@@ -207,25 +207,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();
@@ -293,7 +310,7 @@
 
             // Instance array
             self.dropdowns = [];
-            
+
             var dropdowns = $($.map(self.options.selectBoxes, function(item) {
                 return item.selector;
             }).join(','), self.el);
@@ -310,7 +327,7 @@
             function changeEventHandler(event) {
                 self.options.onChange.call(self, event, self.getValues());
             }
-            
+
             if(typeof self.options.onReady === 'function') {
                 dropdowns.bind('ready', readyEventHandler);
             }

index.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="res/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="res/ajax-loader.gif" data-bind="visible: loading" /></h4>
 					}
 				]
 			});
-			
+
 			// Example 2
 			$('#example2').cascadingDropdown({
 				selectBoxes: [
@@ -410,7 +496,7 @@ <h4>Matches <img src="res/ajax-loader.gif" data-bind="visible: loading" /></h4>
 					}
 				]
 			});
-			
+
 			// Example 3
 			$('#example3').cascadingDropdown({
 				selectBoxes: [
@@ -516,11 +602,68 @@ <h4>Matches <img src="res/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>

res/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));
 	}
-});
+});