Selectgroup: Code commenting to aid open development.

Author: George Paterson

ui/jquery.ui.selectgroup.js

@@ -39,35 +39,44 @@
 			var that = this,
 				id = this.element.attr('id');
 			this.identifiers = ['ui-' + id, 'ui-' + id];
+			// Append one selectgroup.group for the widget as outlined in the flyweight pattern.
 			if ($.ui.selectgroup.group.initialised === false) {
 				$('body').append($.ui.selectgroup.group);
 				$.ui.selectgroup.group.hide();
 			}
 			$.ui.selectgroup.group.initialised = true;
+			// Obtain the placeholder text either from the selected option or the first option.
 			if ($(this.element).find('option:selected').length) {
 				this.copy = this.element.find('option:selected').text();
 			}
 			else {
 				this.copy = this.element.find('option').first().text();
 			}
+			// Create an element to replace the select element interface.
 			this.placeholder = $('<a href="#" id="' + this.identifiers[1] + '" class="' + this.widgetBaseClass + ' ui-widget ui-state-default ui-corner-all"'
 				+ 'role="button" aria-haspopup="true" aria-owns="' + this.widgetBaseClass + '-group">'
 				+ '<span class="' + this.widgetBaseClass + '-copy">'+ this.copy +'</span>'
 				+ '<span class="' + this.widgetBaseClass + '-icon ui-icon ui-icon-triangle-1-s"></span></a>');
+			// If the option to inherit classes is true then get the classnames from the select element and apply to the placeholder element.
 			if (this.options.classInherit.select) {
 				this.placeholder.addClass(this.element.attr('class'));
 			}
+			// If the option to use the popup style is true then we need to add the popup classes.
 			if (this.options.style === 'popup') {
 				this.placeholder.addClass(this.widgetBaseClass + '-popup');
 				this.placeholder.find('.' + this.widgetBaseClass + '-icon').removeClass('ui-icon-triangle-1-s').addClass('ui-icon-triangle-2-n-s');
 			}
+			// Place the placeholder element after the select element and hide the select element.
 			this.element.after(this.placeholder).hide();
+			// Binds events to the placeholder element to match the native select element events.
 			this._placeholderEvents(true);
+			// Bind the focus event on the associated label to the placeholder element.
 			$('label[for="' + id + '"]').attr( 'for', this.identifiers[0] )
 				.bind('click.selectgroup', function(event) {
 					event.preventDefault();
 					that.placeholder.focus();
 				});
+				// Bind click event to the document that will close the selectgroup.group if it is open.
 			$(document).bind('click.selectmenu', function(event) {
 				if (that.isOpen && !($(event.target).closest('.ui-selectgroup').length || $(event.target).closest('.ui-selectgroup-group').length)) {
 					window.setTimeout( function() {
@@ -80,6 +89,7 @@
 		},
 		_placeholderEvents: function(value) {
 			var that = this;
+			// If true then we want to bind events to the placeholder.
 			if (value === true) {
 				this.placeholder.removeClass('ui-state-disabled')
 					.bind('click.selectgroup', function(event) {
@@ -141,6 +151,7 @@
 						$(this).removeClass('ui-state-hover');
 					});
 			}
+			// Else binding events is false and we want to repath them to do nothing.
 			else {
 				this.placeholder.addClass('ui-state-disabled').unbind('.selectgroup');
 				this.placeholder.bind('click.selectgroup', function(event) {
@@ -152,6 +163,7 @@
 			}
 		},
 		_index: function() {
+			// Get all the options within the select element. Map their properties to an array for quick reference. 
 			this.selectors = $.map($('option', this.element), function(value) {
 				return {
 					element: $(value),
@@ -169,6 +181,7 @@
 		_renderGroup: function() {
 			var that = this, 
 				hidden = false;
+			// Create the selectgroup list container.
 			this.group = $('<ul class="' + this.widgetBaseClass + '-list" role="listbox" aria-hidden="true"></ul>');
 			if (this.options.autoWidth) {
 				if (this.options.style === 'dropdown') {
@@ -181,14 +194,17 @@
 			if (this.options.style === 'popup') {
 				this.group.addClass(this.widgetBaseClass + '-popup');
 			}
+			// Render the options available within the select. 
 			this._renderOption();
 			this.group.attr('aria-labelledby', this.identifiers[0]);
 			$($.ui.selectgroup.group).html(this.group);
 		},
 		_renderOption: function() {
 			var that = this;
+			// Iterate through the selectors array which is a map of the options within the select element.
 			$.each(this.selectors, function(index) {
 				var self = this;
+				// Each option will be represented as a list item. Bind properties and events to each list item.
 				var list = $('<li role="presentation"><a role="option" href="#">'+ this.text +'</a></li>')
 					.bind('click.selectgroup', function(event) {
 						event.preventDefault();
@@ -219,11 +235,14 @@
 				if (typeof this.disabled !== "undefined" && this.disabled === 'disabled') {
 					list.addClass('ui-state-disabled');
 				}
+				// The option may be part of an option group.
 				if (this.optgroup.length) {
 					var name = that.widgetBaseClass + '-optgroup-' + that.element.find('optgroup').index(this.optgroup);
+					// If the option group has already been rendered append the option list item to the option group list.
 					if (that.group.find('li.' + name).length ) {
 						that.group.find('li.' + name + ' ul').append(list);
 					}
+					// Else we need to create a representation of an option group and then append the option list item.
 					else {
 						var opt = $('<li class="' + name + ' ' + that.widgetBaseClass + '-optgroup"><span>'+ this.optgroup.attr('label') +'</span><ul></ul></li>');
 						if (that.options.classInherit.optionGroup) {
@@ -237,6 +256,7 @@
 						}
 					}
 				}
+				// Else it is not part of an option group and we can append directly to the selectgroup list container.
 				else {
 					list.appendTo(that.group);
 				}
@@ -246,11 +266,14 @@
 			var options = this.options,
 				local = this.group.find('li').not('.ui-selectgroup-optgroup'),
 				instance = local.get(this.position);
+			// Reset the selectgroup.group position.
 			$($.ui.selectgroup.group).css({'top': 0, 'left': 0});
-			$($.ui.selectgroup.group).show()
+			$($.ui.selectgroup.group).show();
+			// Adjust position if it is a popup.
 			if (this.options.style === 'popup' && !this.options.positioning.offset) {
 				var adjust = '0 -' + ($(instance).outerHeight() + $(instance).offset().top);
 			}
+			// Position the selectgroup.group using the jQuery UI position widget and any applied options.
 			$($.ui.selectgroup.group).position({
 				of: options.positioning.of || this.placeholder,
 				my: options.positioning.my,
@@ -260,6 +283,7 @@
 			});
 		},
 		_toggle: function() {
+			// Toggle the selectgroup to open or close.
 			if ($.ui.selectgroup.group.past !== null) {
 				if ($.ui.selectgroup.group.past.element !== this.element) {
 					this.focus();
@@ -296,34 +320,37 @@
 				position = this.position,
 				instance = null;	
 			  position = this.position + value;
-				if (position < 0) {
-					position = 0;
-				}
-				if (position > maximum) {
-					position = maximum;
-				}
-				if (position === record) { 
-					return;
-				}
-				if (this.selectors[position].disabled === 'disabled' || this.selectors[position].optDisabled === 'disabled') {
-					if (value > 0) {
-						++value;
-					}
-					else {
-						--value;
-					}
-					this._traverse(value, position);
+			// Traverse the selectgroup based on a numerical iteration.
+			if (position < 0) {
+				position = 0;
+			}
+			if (position > maximum) {
+				position = maximum;
+			}
+			// If we have traversed through the positions and not found a new one due to a disabled state we can return to the last available position.
+			if (position === record) { 
+				return;
+			}
+			if (this.selectors[position].disabled === 'disabled' || this.selectors[position].optDisabled === 'disabled') {
+				if (value > 0) {
+					++value;
 				}
 				else {
-					this.position = position;
-					instance = local.get(this.position);
-					this.copy = $(instance).find('a').text();
-					local.removeClass('ui-state-hover');
-					$(instance).addClass('ui-state-hover');						
-					this.placeholder.find('.ui-selectgroup-copy').text(this.copy);
-					this.element.find('option:selected').removeAttr('selected');
-					$(this.selectors[this.position].element).attr('selected', 'selected');
+					--value;
 				}
+				// The next position may be disabled. Iterate through until a position is found, zero or maxmimum position reached.
+				this._traverse(value, position);
+			}
+			else {
+				this.position = position;
+				instance = local.get(this.position);
+				this.copy = $(instance).find('a').text();
+				local.removeClass('ui-state-hover');
+				$(instance).addClass('ui-state-hover');						
+				this.placeholder.find('.ui-selectgroup-copy').text(this.copy);
+				this.element.find('option:selected').removeAttr('selected');
+				$(this.selectors[this.position].element).attr('selected', 'selected');
+			}
 			$.ui.selectgroup.group.position = value;
 		},
 		_typeahead: function(character) {
@@ -332,6 +359,7 @@
 				local = this.group.find('li').not('.ui-selectgroup-optgroup'),
 				instance = null,
 				found = false;
+			// Type ahead based on an alpha numeric charater input.
 			character = character.toLowerCase();
 			this.search[1] += character;
 			window.clearTimeout(this.timer);
@@ -346,7 +374,10 @@
 				found = true;
 				that.search[3] = index;
 			};
+			// Typing ahead we need to remember an array of possible word states based on time and character position.
+			// Is the new character a repetition of the first character.
 			if (this.search[0] === this.search[1][0]) {
+				// Are we attempting to iterate through the selectors using the same character?
 				if (this.search[1].length < 2) {
 					$.each(this.selectors, function(index) {
 						if (!found) {
@@ -361,6 +392,7 @@
 					});				
 					this.search[0] = this.search[1][0];
 				}
+				// Or are we navigating to a character combination based on the first character?
 				else {
 					$.each(this.selectors, function(index) {
 						if (!found) {
@@ -377,6 +409,7 @@
 				}
 			}
 			else {
+				// Iterate through the selectors with the new unrepeated character.
 				$.each(this.selectors, function(index) {
 					if (!found) {
 						if (that.search[1] === that.selectors[index].text.substring(0, that.search[1].length).toLowerCase()) {
@@ -387,14 +420,18 @@
 				});
 				this.search[0] = this.search[1][0];
 			}
+			// If the end of available matches is meet we can reposition to the start of available matches.
 			if (that.search[4] === that.search[3]) {
 				that.search[3] = that.search[2];
 				focusOption(that.search[3]);
 			}
 			this.search[4] = this.search[3];
+			// Clear the initial search after 1 second.
 			this.timer = window.setTimeout(function() {that.search[1] = '';}, (1000));
 		},
 		destroy: function() {
+			// Remove the selectgroup completely.
+			// Has known issues.
 			var id = this.identifiers[0].split('ui-')
 			if (this.isOpen) {
 				this.close();
@@ -407,6 +444,8 @@
 			this.element.show();
 		},
 		enable: function(index, type) {
+			// Enable the placeholder, an option group or option in the original select.
+			// Trigger a 'change' event to redraw the selectgroup.
 			if (this.isOpen) {
 				this.close();
 			}
@@ -423,6 +462,8 @@
 			}
 		},
 		disable: function(index, type) {
+			// Disable the placeholder, an option group or option in the original select.
+			// Trigger a 'change' event to redraw the selectgroup.
 			if (this.isOpen) {
 				this.close();
 			}
@@ -439,18 +480,22 @@
 			}
 		},
 		focus: function() {
+			// Focus on the placeholder to activate without opening the selectgroup.group.
 			this._index();
 			this._renderGroup();
 			this.isActive = true;
 		},
 		blur: function() {
+			// After losing focus on the placeholder. 
 			this.isActive = false;
 		},
 		change: function() {
+			// Redraw the selectgroup.group.
 			this._index();
 			this._renderGroup();
 		},
 		refresh: function() {
+			// Refresh the placeholder.
 			if ($(this.element).find('option:selected').length) {
 				this.copy = this.element.find('option:selected').text();
 			}
@@ -460,6 +505,7 @@
 			this.placeholder.find('.ui-selectgroup-copy').text(this.copy);
 		},
 		open: function() {
+			// Open the selectgroup.group.
 			if (this.options.style === 'dropdown') {
 				$.ui.selectgroup.group.removeClass('ui-corner-all').addClass('ui-corner-bottom');
 				this.placeholder.removeClass('ui-corner-all').addClass('ui-state-active ui-corner-top');
@@ -473,6 +519,7 @@
 			this.isOpen = true;
 		},
 		close: function() {
+			// Close the selectgroup.group.
 			if ($.ui.selectgroup.group.past !== null) {
 				$.ui.selectgroup.group.past.placeholder.removeClass('ui-state-active');
 			}
@@ -486,7 +533,8 @@
 			this.group.attr('aria-hidden', 'true');
 			this.isOpen = false;
 		}
-	})
+	});
+	// Publically available objects used once by the selectgroup to enable the flyweight pattern.
 	$.ui.selectgroup.group = $('<div class="ui-selectgroup-group ui-widget ui-widget-content ui-corner-all"></div>');
 	$.ui.selectgroup.group.initialised = false;
 	$.ui.selectgroup.group.past = null;