type: widget

release: 1.8

status: complete

documentation: http://docs.jquery.com/UI/Button

demo: http://jqueryui.com/demos/button/

 

 

---

 

 

1 - Description:

 

A standard set of button types that can be used across all widgets. Buttons can be basic (A1), have a menu (A2), a split button which opens a menu only when the right hand arrow is clicked (A3) or toggle buttons (A4) that behave like a radiobutton set where only one can be depressed at once. Buttons in a UI usually have different visual styles to indicate importance (A5) such in a save/cancel dialog and may need to be multiple sizes (A6).

 

Button content

Every button should have a text label, even if it's ultimately displayed as an icon only, by hiding the text label in an accessible way.

 

Button types

There are a range of button primitive types we need to support, each with slightly different functionality and behavior. For each button type below, they can have any of the 4 button content styles above:

• Basic button (A1)
• Button with menu (A2) - clicking the button will open a menu. Two variations:
• No feedback - choosing a menu option simply closes the menu, button remains unchanged (comonly used for an action menu)
• Button label feedback - choosing a menu option updates the button label (like a select box)
• Split button (A3) - this button has 2 separate clickable regions: the left label works like the basic button, while clicking the right hand arrow will open a menu. Same menu options apply so the menu selection can update the button label (see Outlook's "Create new X" split button)
• Grouped buttons (A4)
• Standard button - these are normal buttons, but are visually connected together (no margins inbetween, common outer rounded corners)
• Toggle: Single select - works like a radiobutton set: clicking one deselects all others
• Toggle: Multi-select - works like a checkbox set: multiple can be clicked to the on/selected state

 

Typical use cases - buttons can appear in a wide variety of contexts so we need to ensure that they can easily be added to a lot of places:

• Dialogs - may be grouped together (cancel/save) and aligned left or right in the dialog
• Date picker - in the re-factor, we will support a flexible bottom button bar that will hold 1-3 (max?) buttons, should be able to align one or a group left and another right
• Headers - usually right aligned but could be anywhere
• Toolbars - this is a separate plugin, but it needs to be considered since it is generally a container for buttons
• In tables and grids - action buttons per row, in row detail panels, in toolbars above and below the grid
• Next to form inputs, should be easily styled to match height of input
• Sitting anywhere on a page by themselves

 

Example buttons

Filament Group created an article with a core set of CSS framework buttons (not comprehensive to what we want to build for UI but a start)

http://www.filamentgroup.com/lab/styling_buttons_and_toolbars_with_the_jquery_ui_css_framework/

 

Ext JS 3 button examples, very full set of every scenario except button groups:

http://extjs.com/deploy/ext-3.0-rc1.1/examples/button/buttons.html

 

---

 

2 - Visual Design:

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

Buttons can be created from any of the following:

• <button>, <button type="button">, <button type="submit">, <button type="reset">
• <input type="button">, <input type="submit">, <input type="reset">
• <label for="my-button"><input type="checkbox" id="my-button">
• <label for="my-button"><input type="radio" id="my-button">
• <a>

 

When using an input of type button, submit or reset, support is limited to plain text labels with no icons.

When using a checkbox or radio button, the label will transformed into a button.

 

Options:

• text (Boolean, default: true)
• Whether to show any text
• When set to false (display no text), icons must be enabled, otherwise it'll be ignored
• icons (Options, default: { primary: null, secondary: null })
• Icons to display, with or without text (see text option)
• Value for the primary and secondary properties must be a classname (String), eg. "ui-icon-gear"
• For using only a primary icon: icons: {primary:'ui-icon-locked'}
• For using both primary and secondary icon: icons: {primary:'ui-icon-gear',secondary:'ui-icon-triangle-1-s'}
• label (String, default: null)
• Text to show on the button
• When not specified (null), use's the element's html content
• or its value attribute when it's an input element of type submit or reset
• or the html content of the associated label element if its an input of type radio or checkbox

Methods:

• refresh
• to be called manually when form is reset or button checked or disabled state is changed programatically

Events:

• click
• The native click event
• with the exception of radio/checkbox buttons, where the click event on the input is triggered by the widget

 

 

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

<button type="submit">Button</button>

<input type="submit" value="Submit" />
<a href="#">Link</a>

<input id="remember" type="checkbox" name="remember"/><label for="remember">Remember me</label>

 

     4.2 Recommended transformed HTML markup

 

 

http://jquery-ui.googlecode.com/svn/branches/dev/tests/static/button/default.html#

 

     4.3 Accessibility recommendation

 

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

• Apply role="button"
• For checkbox buttons
• Can be marked up either as role="checkbox" & aria-checked="true/false", or role="button" & aria-pressed="true/false". Since there is already a checkbox widget and the checkbox button looks like an actual button, the latter option is recommended.
• For Radio Buttons:
• Must use role="radio" and aria-checked="true/false" rather than aria-pressed
• must either be contained by an element with role="radiogroup", or this element must reference each radio button through aria-owns (in this case the element could be a hidden div). The radiogroup element must specify an accessible name for the group, using an "aria-labelledby", "aria-label" or "title" attribute.
• Only the selected radio button must be part of the tab order
• The selected button can be changed using the keyboard's arrow keys.
• High Contrast Mode
• The icons in icon buttons become invisible when high contrast mode is enabled. One solution would be to (when high contrast mode is detected) disable the styles that normally position the icon button's label text off screen. This would turn the icon button into a regular text button when high contrast mode is enabled (which also means that the width would have to be set to auto, making the button much wider than it normally is. An alternative solution would be to inject a high contrast version of the background image as an actual image element to the DOM (although each icon would have to be stored as a separate image).

 

     4.4 CSS & Theme

 

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

 

---

 

5 - Latest version of plugin:

 

http://jquery-ui.googlecode.com/svn/branches/dev/tests/visual/button/default.html

 

---

 

6 - Open issues being discussed

 

 

• when clicking one of the icon-only anchors on the visual test page, the display gets very slow (it takes some time until the active state shows up)