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.4.3 (or higher)*
• jquery.linkselect.js Plug-in
• jquery.bgiframe.js Plug-in (Optional; for fixing overlay issues in IE6)

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 .linkselect-container 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 the id attribute of the hidden input element that is created by the plug-in. If no name attribute exists, then the id is used as the name attribute of the hidden element that is created.

name

This attribute is optional and is used as the name attributes of the hidden input element 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.

You can also supply an optional "placeholder" class (see options) to an option element to have the option tag used as a selectable title for the linkselect object.

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("text")

Returns the text label for the selected linkselect option.

$("#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("change")

Triggers the "change" event for the Linkselect element. You can use this to trigger off the change events for the default selected item.

$("#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("destroy")

This destroys the linkselect element and places the original select element back in the DOM. The select element will reflect any changes made to the option elements done by the replaceOptions API call.

$("#id").linkselect("replaceOptions", options, includeFilter, 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.

You can use the includeFilter argument to specify a jQuery selector of elements to not replace. This is useful if you want to preserve your placeholder items, or other items in the select element that you do not want replaced.

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", className: "emphasis"}
    , {value: 5, text: "Option 5", className: "de-emphasis"}
];

$("#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.

{
      style: "linkselect"       // the default style to use
    , classLink: ""             // additional classes to use for the anchor tag
    , 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
}

Events

A linkselect object will announce the following events. You can use jQuery's bind() function to bind events to these listeners so that you can attach custom code anytime one of the events is triggered.

update [event, value, text, li]

Is fired any time the linkselect value is changed. Events are triggered for both the original select element and the input element that replaces the select element. The event returns 4 arguments:

• event - the jQuery event object
• value - the new value of the linkselect object
• text - the text description for the value
• li - a jQuery object contain the <li> element representing the original <option> element.

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.

License

Copyright 2008 Giva (https://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
    https://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.

Revisions

v1.5.15 (2019-02-20)

• Always uses "keydown" event for all keyboard monitoring to resolve issues caused by changes in how modern browser listen to "keypress" events

v1.5.14 (2017-06-07)

• Fixed bug where position/layout of dropdown may not be properly re-drawn after browser resizes
• Removed IE6 fixes (IE6 no longer supported)
• Added the "style" prefix to the "placeholder" class

v1.5.13 (2013-07-09)

• The "update" event every time the input's value is changed, so if either the change or select callbacks return false, the event is fired again when the value is reset.
• Fixed logic issue where returning to previous value could fail when callbacks return false under some circumstances.

v1.5.11 (2013-07-09)

• Linkselect plugin now annouces an "update" event whenever the value changes--which allows you to set up listeners for when the value has changed.

v1.5.10 (2012-09-11)

• Added the "change" method for re-running the change events on the currently selected item

v1.5.01 (2012-01-03)

• Fixed CSS declaration for "select" skin to use a defined font family and size and various other tweaks to improve appearance
• Changes in the keyboard behavior when a placeholder is used so that PAGE UP, PAGE DOWN, END and HOME stay within the context of the dropdown menu

v1.5.00 (2011-12-23)

• Revised CSS naming structure to make it to have multiple visual styles of linkselect elements on the same page. The changes in v1.5 are not backwards compatible, so you will need to update your CSS in order to upgrage to v1.5. You can either replace you existing CSS files with one included in the zip file, or you can modify your existing CSS files to match the new naming syntax (which for the most part is just changing the camel casing from "linkselectLink" to "linkselect-link", "linkselectLinkOpen" to "linkselect-link-open", etc. Also, all CSS classes now using the prefix "linkselect-" by default.
• Added new "style" option. This replaces all the previous class* options. The default style is "linkselect" and is simply used as the prefix used for all the CSS classes. You can create custom linkselect skins by just copying one of the included CSS files and changing the prefix to match your style option value.
• Added "text" API call to return the label of the currently selected option.
• Added "destroy" API call to destroy a linkselect element and return to original select element.
• Changed the "replaceOptions" API to add a new "includeFilter" argument. The API change is backwards compatible.
• jQuery.delegate() is now used to monitor event changes
• Changed <li /> elements to use "data-" attributes for custom attributes
• Changed <li /> elements to use "data-value" for storing selectable value instead of the "rel" attribute.
• Fixed issue with Chrome not correctly accepting focus when the linkselect element was clicked.
• Events related to closing/resizing of the open linkselect element are now registered/unregistered when the menu opens. This helps improve performance when there are many linkselect elements on the page as it reduces the document.click events that fire to see if the menu should be closed.
• Added ability to use both "name" and "id" attributes on a select element with different values.
• Added new "placeholder" functionality. You can now give an option element a class of "placeholder" to have it used as a selectable title for the linkselect element. This allows you to use a "Please select..." option element in your select and have it used as the title of the linkselect. Users will be able to select this option, just like any other option element.
• Fixed various positioning bugs.

v1.2.09 (2011-08-08)

• Fixed issue with code using .attr("className") instead of .attr("class")

v1.2.08 (2011-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

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 (68 KB)