type: widget

release: 0.0

status: in development

documentation: url || N/A

demo: http://jquery-ui.googlecode.com/svn/branches/labs/button/demo.html

 

 

---

 

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

Markup, style behavior notes

Support the ability to apply a button appearance to any element (div, span) with most emphasis on making this look consistent between links and button elements across browsers

Styles for buttons should be carefully coded to render padding, margins, text size and other style attributes consistently across all elements (a, button, div, span) and button types (basic, button, split button, grouped buttons) so buttons of various types can be used together in toolbars and look consistent

All buttons by default should have the ui-widget and ui-state-default framework classes by default. Hovering over a button should add the class ui-state-hover and clicking should add the class ui-state-active (then pop back to default if it's not a toggle??). Active state should not have a hover or focus on mouseover.

Consider a way to re-map classes and events for touchscreen apps. Since these don't typically support the hover interaction and rely on a strong depressed appearance when clicked for feedback, we could have an option that maps the classes this way: ui-state-default to start, on click/mousedown swap to ui-state-hover then to ui-state-active briefly, then back to ui-state-default (if not a toggle).This might address some developer's concerns about there not being a clicked/depressed state.

Consider allowing users to identify buttons that don't use the ui-state-default class for buttons so they just appear as text and/or icons then transition to the ui-state-hover appearance on mouseover. Useful for toolbars and for places where you want a more low-key button style.

To provide a shift in emphasis between buttons, the ui-priority-primary class can be applied to make the text weight bold. The ui-priority-secondary class can be added to secondary buttons (cancel) which will set the button opacity to ~80% and the font weight to normal. Other than testing that all button types render well with these additional classes, no other testing or scripting is needed

Buttons can be disabled. The ui-state-disabled class should be added to set the opacity to roughly 35% and make it look dimmed. In addition, any mouse and keyboard events must be killed on a disabled button. Tab index too?

Buttons should auto-stretch their width to fit the length of their content. A width can optionally be set via CSS, but it is too cumbersome (and breakable) to ask developers to have to set widths on each button

Buttons should be coded in ems so they will scale gracefully to fit any length fo content or text size

Multiple buttons should be able to sit next to each other in a row and appear in linear order as the code source with minimum developer effort. This can be tricky to accomplish if you also want to have flexible width buttons

Consider providing an optional class to make "mini" versions of all our buttons that would simply scale them down by 70-80% across the board for use in places where a more compact size is needed.

 

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:

 

(Detailed descrition of how the script will be structured: defaults, options, architecture, extensibility, etc.)

status legends:

     âˆš - implemented

     ± - partially implemented / still some bugs to solve

     ¤ - currently under devellopment

    ∅ - todo / not yet implemented

     x - still thinking / need discussion

 

Options:

 

• ± label (string, default: null) [ implementation lack the rendering of input elements and so to check for value attribute ]
  • button display text
  • if null:
    • ∅for input[type=button], input[type=submit], input[type=reset]: element's "value" attribute value is used.
    • √ for other initial elements: element's innerHTML.
    • √ falls back to empty string if it cannot be determined.
• √ icon (string, default: null)
  • √ button icon: ui-icon-name class or icon url 
  • √ if null: check for options in class attribute (see specification paragraph for details )
  • √ if still null: ui-icon-none class is added to the icon (icon-none is kept for rendering consistency even if none/empty)

• √ orientation (string, default: "auto", possible values: "l", "r", "t", "b","i" for left, right, top, bottom and icon only)
  • ± icon placement regarding the label. setted to i (icon only) must behave like auto + hide the label [ at this time it remove the label content and it can't be retrieved, should be reversible ].
  • √ auto should check for parent ui-buttonset settings and default to left if not found
• √ size (string, default "auto", possible values: "tiny", "small", "normal", "big", "huge")
  • √ auto should check for parent ui-buttonset settings and default to normal if not found.
• ± x buttonMode (string, default: null, possible values: null | 'toggle' | 'normal' | [ 'split' | 'menu' ]) [ for now only normal and toggle is supported, regarding work done on selectmenu: http://jqueryui.pbworks.com/Selectmenu is there any interest in managing mode menu in buttons ? ]
  • button behavior
  • if null: check toggle or ui-button-toggle class existense on the initial element, otherwise set the specified buttonMode. 
• √ active (boolean, default: false)
  • only make sense with buttonMode == 'toggle', if true then the toggle button will be activated by default.
• √ disabled (boolean, default null)
  • √ if null then should check for attribute disabled then default to false if not found
  • √ must block click, focus events and add ui-state-disabled class
• √  checkButtonset (boolean, default: false)
  • automatically look for a parent buttonset element to wear additional styles and event handlers.
• √ OverrideDefaultState (string: default:false) [name need to be discussed]
  • let user override the value for the class used for default state ( if flase then ui-state-default is used ). An empty string for no class at all  is accepted.

Callbacks :

• √  setactive (event name: buttonsetactive)
  •  triggered when activable button (such as toggles) see their active option sets

 

Methods:

• √ disable() 
  • disables the button.
• √ enable() 
  • enables the button.
• √ toggle()
  • force toggle button to change state
• √ destroy()
• [ other methods? ] 

 

Keyboard:

• √ ENTER | SPACE - press the button if it is focused.
• √ TAB | SHIFT+TAB - focus next|previous control (not the next|previous button in the buttonset - this must be checked explicitly).
• ∅ RIGHT | LEFT - select a button in a buttonset.

 

Specificiations:

• in order to assist user some basic options can be directly setted in the class attribute of the original elements. all of them are optionnal but the order is meaningfull. So  buttonMode, active, size, orientation and icon can be set all at once in class name just like that: class="ui-button-toggle-active-big-r-info" and will render as an activated toggle button with size big  and an info icon on the right. 

 

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

     The most typical situation would be to transform a link or button element into a UI button but you should be able to call this on any element.

 

     <button class="ui-button" type="submit">Button</button>
     <a href="#" class="ui-button">Link</a>

     <span class="ui-button-toggle-small-r-info">toggle button</span>

 

     4.2 Recommended transformed HTML markup

 

     See Filament group article for most basic types. Still need static mockups for the split and menu buttons - anyone want to take a stab at it? There is already menu static markup to start with.

 

     <button class="ui-button ui-widget ui-state-default ui-corner-all" type="submit">Button</button>
     <a href="#" class="ui-button ui-state-default ui-corner-all">Link</a>

     <span class="ui-button-toggle-small-r-info ui-button ui-widget ui-state-default ui-corner-all ui-button-size-small ui-button-orientation-r">
          <span class="ui-button-label">toggle button</span>
          <span class="ui-button-icon"><span class="ui-icon ui-icon-info"/></span>/span>

     </span>

 

     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) 

 

     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:

svn repository:  http://jquery-ui.googlecode.com/svn/branches/labs/button/

 

---

 

6 - Open issues being discussed

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 

     Button elements extra padding:

     There's still a problem to keep original button elements consistent with other original markup. Most browsers add some extra padding to button elements.

     We can with some css hack or browser detections achieve a better rendering of the buttons but the problem start to be more complicated when playing with the differents size (tiny,small,normal,big,huge) and original font-size of parent element.

     It becomes really hard to predict what padding should be used.

     For now this will be left as is as better rendering on buggy browsers engine will certainly break others rendering engines that does pretty good job (ie: midori, opera), ie6 and ie7 may be the most buggy and still be problematic.

     So any css hacker that could help on that particular problem is really welcome ;)

     Input elements replacement

     I face some trouble with input element replacement, as removing them from the body will automaticly call the destroy widget method. I'm trying at this time to do it by simply hiding them, but this lead to another problem, two elements (original one and replacement one) with the same id. This is not good. Also as said by scott on mailing list, is this a good thing to remove the original element from the document....? I'm not sure about this.

---