type: widget

release: 0.0

status:  in development

documentation: N/A

demo: http://view.jqueryui.com/selectmenu/demos/selectmenu/default.html

TODOs

• Use _getCreateOptions to read disabled-attribute into options, disable/enable based on that
• Should replace the current .attr("disabled") check
• See Spinner for a reference (reading min/max attributes) 
• Write unit tests to cover defaults, options, methods and events
• Should replace most visual tests, like the event logging 
• Check in Konquerer (see https://github.com/fnagel/jquery-ui/issues/197)
• Implement changed ARIA specification

1 - Description:

A jQuery UI widget that duplicates and extends the functionality of a native HTML select element, allowing it to be customizable in behavior and appearance far beyond the limitations of a native select. 

Related plugins:

• http://www.givainc.com/labs/linkselect_jquery_plugin.htm
• DropKick.js: http://jamielottering.github.com/DropKick/ 
• Chosen: http://harvesthq.github.com/chosen/ 

Previous implementations:

Bugfixed and jQuery 1.4.x / UI 1.8.x compatible version of this plugin: Please download repo at http://github.com/fnagel/jquery-ui/tree/selectmenu and open: demo/selectmenu/index.html
Feel free to post feature requests and bugs in the comments or even better in the GitHub issue tracker. This edit was made after consulting Todd Parker.

The wiki there has details, along with an FAQ, of what that version covers.

Additional Bugfixes can be found in this repo:  http://github.com/tauren/jquery-ui/tree/selectmenu. This repo is a fork of the fnagel repo listed above and includes all bug fixes and features available in that repo as well as bug fixes for positional problems such as using <optgroup> tags with scrolling popup selectmenus. A pull request has been sent for these bugfixes to be pulled into the fnagel repo. An additional demo for positional fixes has been included at https://github.com/tauren/jquery-ui/blob/selectmenu/demos/selectmenu/positioning.html. 

2 - Visual Design:

3 - Functional Specification:

The default way to use this plugin is by calling the selectmenu method on a select element:

$('select').selectmenu();

Feature details:

• selectmenu will act as a proxy back to the original select element, controlling its state for form submission or serialization 
• Any form label originally associated with the select menu will be associated with the new form control, by forwarding the click event on the original select (as long as the label's for-attribute matches the select's id-attribute).
• The menu will support both in-place "popup" or drop-down styles
• The menu will be fully keyboard accessible using matching conventions to native select elements
• Menu is keyboard accessible while closed as well - arrow keys make different selections
• The menu will have ARIA support for screenreaders so the original select element can safely be hidden from all users
• Different arrow icons depending on menu type 
• The presentation menu is built based on labels and values of the wrapped select. Custom presentations are possible.
• The min-width of the menu is the width of the input. Ala autocomplete.
• The max-height of the menu can be controlled via CSS, or, if necessary, via JS customizations  
• For render customizations, e.g. custom background images for each item, the widget provides _renderMenu and _renderItem, like autocomplete does. Users can override these, e.g. override _renderMenu and use a template to output the markup. These need to be better documented then what's currently in place for Autocomplete.
• A enter key event, with the input focussed, but the menu closed, does a regular form submit, just like the native select would. 
• Type-ahead, as built-in into menu. 
• Optgroup support just like native select does, with a flat list with group headers (similar to this categories autocomplete demo menu)
• Optional: Render groups as nested lists, making each group a popup menu, with the top-level item the group's header 
• Disabling individual options or optgroups happens by updating the original select, then calling the refresh method on the Selectmenu. 

Not supported:

• Initializing from something that isn't a select-element. Use Menu together with Popup instead.
• An index-method (no usecase so far). If you really need it, provide a usecase. 

Options: 

• appendTo
• see autocomplete 
• dropdown: Boolean, default true (open below trigger, same as native select), set to false to open the menu around the trigger
• position
• see autocomplete 
• might get overriden when using dropdown:false 

Methods:

• refresh
• parses the original element again, updates the value option and rerenders the menu
• triggers events if value changed 
• open
• opens the menu 
• close 
• closes the menu 

Events:

• open
• when menu opens 
• focus 
• when item receives focus  
• select  
• when selection changes 
• with reference to original option 
• close
• when menu closes 
• change
• on blur, when selected changed 
• with reference to original option 

4 - Markup & Style:

     4.1 Initial markup examples

     <select name="speedA" id="speedA">

          <option value="Slower" class="whoo">Slower</option>

          <option value="Slow">Slow</option>

          <option value="Med" selected="selected">Med</option>

          <option value="Fast">Fast</option>

          <option value="Faster">Faster</option>

   </select>

     4.2 Recommended transformed HTML markup

          <div class="css-scope">

          <a aria-owns="speedA_menu_318" aria-haspopup="true" href="#" id="speedA_button_318" class="ui-selectmenu ui-selectmenu-popup ui-widget ui-state-default ui-corner-all" tabindex="0" style="width: 173px;">

                    <span class="ui-selectmenu-status">Slower</span>

                         <span class="ui-selectmenu-icon ui-icon ui-icon-triangle-2-n-s"></span>

           </a>

     </div>

     <!-- at end of body-->

     <div class="css-scope">

          <ul id="speedA_menu_318" role="menu" aria-labelledby="speedA_button_318" class="ui-selectmenu-menu ui-widget ui-widget-content ui-corner-all ui-selectmenu-menu-popup ui-selectmenu-open" style="width: 147px; left: 184.017px; top: 136.95px;">

               <li class="whoo ui-corner-top ui-selectmenu-item-selected ui-state-active"><a aria-selected="true" role="option" tabindex="-1" href="#">Slower</a></li>

               <li><a aria-selected="false" role="option" tabindex="-1" href="#">Slow</a></li>

               <li><a aria-selected="false" role="option" tabindex="-1" href="#">Med</a></li>

               <li><a aria-selected="false" role="option" tabindex="-1" href="#">Fast</a></li>

               <li class="ui-corner-bottom"><a aria-selected="false" role="option" tabindex="-1" href="#">Faster</a></li>

          </ul>

     </div>

     4.3 Accessibility recommendation

   Attributes on button: 

• role="combobox" 
• aria-haspopup="true"
• aria-expanded (accordingly)
• aria-autocomplete="list"
• aria-activedescendant="[selected option's id value]" 
• aria-owns="[widget menu's id value]"
• generated ID for ARIA element referencing
• tabindex of 0 or value from select element
• aria-disabled (accordingly)
• Keep focus on the button 

     ARIA attributes on menu portion:

• role="listbox"
• aria-labelledby="[widget button's id value]"
• generated ID for ARIA element referencing
• Each anchor within menu requires :
• aria-selected (accordingly)
• tabindex="-1"
• role="option"

5 - Latest version of plugin:

http://view.jqueryui.com/selectmenu/demos/selectmenu/default.html

6 - Open issues being discussed

• ?

Tabled/deferred

• Should we have an option for scrollbarless slick scrolling (arrows at top and bottom and list scrolls dynamically with mouse position)?
• Should be an option of menu, not selectmenu. Not planned right now.   
• Mobile browser support: jQuery Mobile provides a good reference implementation for now, eventually we should be able to merge parts of both frameworks back together.