Giva Labs

Linkselect jQuery Plug-in

Overview

The jQuery Linkselect plug-in converts <select /> elements into a combination of an anchor tag associated with a dropdown menu. This combination allows you to highly customize the look and feel of the select element, without losing any functionality.

While there are many similar plug-ins, the key differentiator with the Linkselect plug-in is that is designed to fit in limited real estate. One key design issue with the <select /> is that it's hard to control how much screen real estate is taken up by the element. If your <select /> contains options of varying sizes, the width of the <select /> element can quickly get out of hand.

In a recent project we were working on, we required the functionality of a <select /> element, but had to work within a very confined design area. Because we had no control over how much data or the length of the items that appeared in the <select /> element, we knew couldn't use the element as-is. What we need was a <select /> element that would allow us to wrap long options to another line. This is what lead to the development of the Linkselect plug-in.

The Linkselect Plug-in resolves this space by replacing the <select /> element with an anchor tag that provides all the same functionality of a single item select box.

Requirements

In order to use the Linkselect plug-in, you need the following:

• jQuery v1.2.6 (or higher)*
• jquery.linkselect.js Plug-in
• jquery.bgiframe.js Plug-in (Optional; for fixing overlay issues in IE6)

* This plug-in may work with older versions of jQuery in the 1.2 family. If you try using this with an older version of jQuery, you will need to include the jquery.dimensions.js plug-in (as of jQuery v1.2.6 the jquery.dimensions.js plug-in is included in the jQuery core.)

Usage

To convert your <select /> elements into linkselect elements, just invoke the jQuery plug-in using the following syntax:

$("select").linkselect([options]);

The width of the drop down based on the width of the anchor tag. If anchor tag happens to be an inline element (i.e. display: inline;,) then the width will be based on the anchor's parent element. If the fixedWidth is set to false, then the drop down will be further adjusted to make sure that the width of the drop down is wide enough. You can set a maximum width by setting the max-width property of the .linkselectContainer class.

Arguments

options

This argument is optional and allows you to customize the settings used for each instance of the plug-in. For a list of all available options, see the Options section.

Elements

The Linkselect converts the standard <select /> element to a specialized UI element. There are a few key attributes from both the <select /> and <option /> elements which are used by the Linkselect plug-in and special funcationality. Below is a list of the attributes that provided special functionality to the Linkselect plug-in.

<select />

id

This attribute is required and is used as both the name and id attributes of the hidden tag that is created by the plug-in.

title

This attribute is optional and is used to provide a title bar to the Linkselect's dropdown menu.

tabindex

This attribute is optional and is used to set the tabindex of the anchor tag. This just duplicates the original <select /> element's tabindex.

onchange

This attribute is optional and will be fired just like the original onchange event would. However, when this function is triggered, it will have access to the same arguments that the normal change callback would.

NOTE: The Linkselect Plug-in was designed only for single select style elements. It will not allow you to select more than one option.

<option />

NOTE: The text of the <option /> is used as the text shown in the dropdown for the item.

value

This attribute is option and is used as the value for the selected item.

selected

This attribute is optional and is used to define which option is selected by default.

class

This attribute is optional and is used to define any classes that should be applied to the option in the dropdown.

Now that we have a reference to the widget, we can invoke any of the public API calls.

Public API

$("#id").linkselect("val")

Returns the current value for the linkselect element.

$("#id").linkselect("val", value)

Sets the value of the linkselect element.

$("#id").linkselect("focus")

Places focus on the Linkselect's anchor tag. This is like doing a $("a").focus();

$("#id").linkselect("blur")

Blur's the focus from the Linkselect's anchor tag. This is like doing a $("a").blur();

$("#id").linkselect("open")

Opens the Linkselect's dropdown menu.

$("#id").linkselect("close")

Closes the Linkselect's dropdown menu.

$("#id").linkselect("disable", boolean)

Disables (true) or enables (false) the Linkselect element. Disabled elements still pass their form value when the form is submitted to the server, but the user can not change the value via the UI.

$("#id").linkselect("replaceOptions", options, doCallback)

Replaces the options in the dropdown with the array of objects passed into the options argument. You can use this API method to repopulate a Linkselect with options via an AJAX call. When the options are replaced, the change callback is triggered for the newly selected item. You can set the doCallback to false to prevent callback from being triggered.

For example:

var options = [
	  {value: 1, text: "Option 1"}
	, {value: 2, text: "Option 2"}
	, {value: 3, text: "Option 3", selected: true}
	, {value: 4, text: "Option 4"}
	, {value: 5, text: "Option 5"}
];

$("#id").linkselect("replaceOptions", options);

Each item in the "options" array is a JavaScript object that must contain at least the keys "value" and "text". Also supported are the keys "selected" (which can be true for any single item that needs selecting) and the "className" key, which can be used to define a class for the <option /> element.

$("#id").linkselect("object")

Returns a reference to the internal $.Linkselect object. This is for advanced usage only. Examine the source code for uses of the $.Linkselect object.

Options

There are a number of options available for customizing the look and feel of the Linkselect widget.

{
         classLink: "linkselectLink"             // the class to use for the anchor tag
       , classLinkOpen: "linkselectLinkOpen"     // the anchor's class when the dropdown is shown
       , classLinkFocus: "linkselectLinkFocus"   // the anchor's class when it has focus
       , classContainer: "linkselectContainer"   // the class to the container that holds the options
       , classSelected: "selected"               // the class of the currently selected item
       , classCurrent: "current"                 // the class of the highlighted item
       , classDisabled: "linkselectDisabled"     // the class used on the text when the linkselect is disabled
       , classValue: "linkselectValue"           // the class used for each item in the dropdown
       , yAxis: "top"                            // the position of the dropdown relative to the link
                                                 // (can be either "top" or "bottom")
       , titleAlign: "right"                     // location of dropdown's title bar if dropdown is on right edge
                                                 // of the screen (can be either "right" or "left")
       , fixedWidth: false                       // false = dropdown sizes to width of options,
                                                 // true = dropdown uses width of link
       , init: null                              // callback that occurs when a linkselect menu is initialized
       , change: null                            // callback that occurs when an option is selected
       , format: null                            // callback that occurs when rendering the HTML to use for an
                                                 // item in the dropdown
       , open: null                              // callback that occurs when the menu is opened
       , close: null                             // callback that occurs when the menu is closed
}

Keyboard Usage

The linkselect's keyboard functionality is set to mimic the behavior of Internet Explorer 6's handling of the <select /> element. When a Linkselect element has focus you can:

• Press the first letter of an option to jump to the first instance of that item in the dropdown. Subsequent presses of the same key will cycle through all items that start with the matching character. When a new key is pressed, it will attempt to jump to the first item that starts with the new keyboard character typed.
• Press [UP ARROW] or [DOWN ARROW] to cycle through valid options
• Press [HOME] to jump to the first item
• Press [END] to jump to the last item
• Press [PAGE UP] to jump up one page of options
• Press [PAGE DOWN] to jump down one page of options

Getting Started

The first thing we need to do is to load the required JavaScript libraries and the CSS stylesheet used by the widget:

<script type="text/javascript" src="./lib/jquery-1.2.6.min.js"></script>
<script type="text/javascript" src="./lib/jquery.linkselect.js"></script>

<!---// load the Linkselect CSS stylesheet //--->
<link type="text/css" href="./css/jquery.linkselect.css" rel="stylesheet" media="all" />

Before you can invoke an instance of the Linkselect widget, you must have one or more <select /> elements on your page. The key attributes from your select tag (id, title, tabindex) are all supported by the Linkselect plug-in.

<select id="category" title="Select a category" class="linkselect">
	<option value="">[none]</option>
	<option value="help_desk">Help Desk</option>
	<option value="customer_service">Customer Service</option>
	<option value="knowledge_manager">Knowledge Manager</option>
	<option value="change_manager">Change Manager</option>
	<option value="service_desk">Service Desk</option>
	<option value="asset_manager">Asset Manager</option>
	<option value="software_manager">Software Manager</option>
</select>

The next step is to actually create an instance of the Linkselect widget. You want to make sure to initialize the widget after all the necessary DOM elements are available, which makes the document.ready event a great place to initialize the widget.

<script type="text/javascript">
$(document).ready(function (){
	$("#category").linkselect();
});
</script>

Now let us take a look at what the code above produced.

Example

Original <select /> element

Please select a category: [none] Help Desk Customer Service Knowledge Manager Change Manager Service Desk Asset Manager Software Manager

Same code using the Linkselect Plug-in

Please select a category: [none] Help Desk Customer Service Knowledge Manager Change Manager Service Desk Asset Manager Software Manager

Click on the "[none]" anchor above to open up the linkselect dropdown. As you change options, the text of the anchor will get updated with the text from the <option /> tag. A hidden <input /> element with with the same name/id attribute will have it's value updated with the value of the <option /> tag. The hidden <input /> element is used to pass the value of the Linkselect element back to the server.

Linkselect's element have full keyboard support, which has been modeled after how Internet Explorer 6 handles <select /> elements. See the Keyboard Usage section for more information.

For more examples, see the Giva Labs - Linkselect Example Page page.

Support

This source code is provided as-is. At this time Giva is not offering direct support for this product. If you are in need of assistance, post your question to one of the jQuery Mailing Lists. Members of the Giva development team actively participate on the jQuery Mailing lists, so if we see your question we will try our best to respond.

License

Copyright 2010 Giva, Inc. (http://www.givainc.com/labs/)

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.

Download

The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.

jquery.linkselect.zip (44 KB)

Revisions

v1.2.08 (2009-07-30)

• Fixed error with repaint() function when <select /> element did not have a title attribute

v1.2.07 (2009-07-13)

• Fixed error with close callback

v1.2.06 (2009-03-30)

• Fixed issues with IE8

v1.2.05 (2009-02-10)

• Fixed bug where keyboard support did not work in Chrome (moved from using keypress to keydown)

v1.2.04 (2008-12-09)

• Fixed bug in getScreenDimensions() by changing width/height calculation to use the document object instead of the body element

v1.2.03 (2008-12-01)

• Fixed bug in repaint() if not using a title on your select elements
• Fixed bug in repaint() if not using a title on your select elements
• Added close() method (which did not exists, contrary to documentation)

v1.2.01 (2008-10-14)

• Initial release