Commits

John Fuex committed acedcc5

Copied readme.txt file to root.

Comments (0)

Files changed (1)

+Improved Dropdown jQuery Plugin
+
+Author: John Fuex 
+Created: April 21, 2011
+Available From: http://improvingsoftware.com/projects/improved-dropdown-jquery-plugin/
+Requirements: jQuery 1.4.2 or later.
+
+Introduction
+============
+	I built this jQuery plug-in to meet a need in one of my own projects. I can't be the only
+	web developer who wanted a slightly better class of drop-down controls in my web applications
+	so I am sharing this through the OSS community. 
+
+	If you are using it in your projects or have any commentary on it, I'd love to hear about it. Please
+	give me a shout out on twitter (@johnFx) or in the comments on my blog (http://improvingsoftware.com/projects).
+
+	Enjoy, and happy coding!
+	-John Fuex
+
+
+What it does and doesn't do
+===========================	
+	This is a very simple control. It creates a filterable combo-box style control (ImprovedDropdown) 
+	for each SELECT html element you call it on. Your original SELECT element will still be in the
+	DOM, just hidden and it's value will be auto-magically synchronized with the user's selection
+	in the ImprovedDropdown control. The theory is that you should be able to use this plug-in
+	without changes to your server side scripts since they can continue to interact with the existing
+	SELECT control and not even know about the plug-in. It should work fine with ASP.NET, PHP, JSP, 
+	or any server-side scripting engine. 
+
+	One other feature that I needed, but wasn't seeing in similar controls was the ability to 
+	preserve OPTGROUP elements from the original SELECT control so I built support for them into
+	the ImprovedDropdown plugin. If you include them in your source SELECT elements, they will be 
+	displayed in the Improved Dropdowns.
+
+	This control is not intended to be another of those AJAXy suggestion boxes that query from the server
+	as you type. There are plenty of other plugins out there that work really well for that. This
+	control is about adding functionality to the dropdown controls without all the hullabaloo of 
+	making AJAX calls to the server.
+
+Usage Notes
+===========
+
+Getting Started
+---------------
+	(1) Copy the improvedDropdown.js, improvedDropdown.css, dropIcon.png, and jQuery 1.4.2 (or later) files to your site.
+
+	(2) Add references to jQuery,  improvedDropDown.js, and improvedDropDown.css to each page on your site will use this control.
+
+	Example:
+		<head>
+			<script type="text/javascript" src="js/jquery.js"></script>
+			<script type="text/javascript" src="js/improvedDropDown.js"></script>
+			<link rel="StyleSheet" href="css/improvedDropdown.css" type="text/css" />
+		</head>
+
+
+Adding the control(s) to your pages
+-----------------------------------
+	Just create HTML select controls as normal then call the improveDropDown() method to upsize them.
+
+		$(document).ready(function () {
+			$("select").improveDropDown(); //convert all select elements using the default configuration
+		});
+
+	The original SELECT elements you upsized will still be in your document, but hidden and the values will remain 
+	synchronized with whatever the user selects in the visible ImprovedDropdown versions of them. Your server-side
+	code will still interact with the original (hidden) controls so you can seamlessly integrate these controls
+	without needing to change your form processing code on the web server.
+
+
+Configuration Options
+---------------------
+If you want more control over how the ImprovedDropdown controls look you can pass in a configuration object to the improveDropDown call like so:
+
+		$(document).ready(function () {
+			$("select").improveDropDown(			
+											{
+											   iconPath:'./img/dropIcon.png',
+											   noMatchesText: 'No Matches',
+											   noItemsText: 'No Items Available'
+											   hideHeadersForEmptyGroups: false;
+											}
+			                           ); //convert all select elements using specific configuration
+		});
+
+
+Note: The values in the above example are the defaults for the control. Any omitted configuration parameters will default to these values.
+
+Styling the Control
+-------------------
+	The ImprovedDropdown controls will mirror the control they were created from basic characteristics, like size. To tweak the 
+	look and feel of the ImprovedDropdown controls you can modify the ImprovedDropdown.css to your tastes.
+	 
+
+Setting the selected value at runtime
+-------------------------------------
+	When an ImprovedDropdown control is created, the original value is auto-magically copied to the newly created control 
+	and the underlying control (yours) is kept synchronized with any changes the user makes in the ImprovedDropdown.
+
+	If you need to change the selected item after the ImprovedDropdown has been created, just call the improveDropDown method
+	again with a string parameter indicating the new value. This will set the value of both the original SELECT element
+	and the associated ImprovedDropdown control.
+
+	Example:
+		$('#YourSelectControl').improveDropDown('NewValue');
+
+    Usage Notes:
+     - If you try to set the value to an option not in the dropdown, the command will ignore your request without error.
+	 - The value you are passing refers to the VALUE of the item to be selected, not the TEXT, if they are different.
+     - You can't initialize an ImprovedDropdown and set the value simultaneously using .improveDropDown('newValue'). 
+
+
+Event Handling
+--------------
+When the value of the Improved Dropdown control changes the change event will be fired on the original control.
+
+
+Modifying the contents of the dropdown list
+-------------------------------------------
+	If you need to modify the contents of the SELECT list after initializing the ImprovedDropdown for it, just 
+	modify your original SELECT object then call improveDropDown() on it again to re-build an ImprovedDropdown control.
+
+Common Issues
+-------------
+Issue: I get just a text box with no-dropdown icon. 
+Solution: Check that the improvedDropDown.css file is referenced your page (See "Getting Started"), and that the path is correct.
+
+Issue: I get errors complaining about "controlID.lastIndexOf" and invalid indexes.
+Solution: Every SELECT item that you improve with this plug-in MUST have an ID attribute set on it, and it must be unique. This is
+usually the cause of invalid index errors.
+
+
+=====================
+Licensing Information
+=====================
+Copyright 2011 - John Fuex
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+
+