1. John Fuex
  2. ImprovedDropdown (jQuery Plugin)

Source

ImprovedDropdown (jQuery Plugin) /

Filename Size Date modified Message
css
docs
img
js
screenshots
550 B
10.8 KB
7.0 KB
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.