d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<div class='intro'>
e9738690feeb7eae0899f34e5d0feec68bdbd48cDerek Gathright <p>{{description}}</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright{{>getting-started}}
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright<h2>Using Button - Quick Start</h2>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright<h3>Button Widgets</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright// Create some button widgets
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek GathrightYUI().use('button', function(Y){
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright // A push button widget
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var button = new Y.Button({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#myButton'
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright // A toggle button widget
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var toggleButton = new Y.ToggleButton({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#myToggleButton'
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright<h3>Node Plugin</h3>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright// If you want something a little more light-weight than a widget...
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek GathrightYUI().use('button-plugin', function(Y){
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright var button = new Y.Plugin.Button.createNode("#testButton", {
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright label: "I'm a disabled button",
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright disabled: true
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright<h3>Button Groups</h3>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright// And if you want to manage a group of buttons
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek GathrightYUI().use('button-group', function(Y){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var buttonGroup = new Y.ButtonGroup({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#container' // Should contain <button> children
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright<h2>Modules</h2>
e9738690feeb7eae0899f34e5d0feec68bdbd48cDerek Gathright<p>YUI's Button component introduces 5 modules:</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li><a href="#cssbutton">`cssbutton`</a> - Includes various `yui3-button` styles to provide a normalized CSS base for buttons.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li><a href="#button">`button`</a> - Exports the `Y.Button` & `Y.ToggleButton` widgets.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li><a href="#buttongroup">`button-group`</a> - Exports the `Y.ButtonGroup` widget.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li><a href="#buttonplugin">`button-plugin`</a> - Exports the `Y.Plugin.Button.createNode` factory.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`button-core` - Exports `Y.ButtonCore`, a base used by all other Button component modules.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h3>Which one to use?</h3>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <li>`use('cssbutton')` if you only want a CSS stylesheet to enhance button(-like) nodes</li>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <li>`use('button-plugin')` if you only need to enhance a DOM node with button functionality</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`use('button')` if you want a button widget</li>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <li>`use('button-group')` if you want a widget to manage a group of buttons</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`button-core` is not intended to be used stand-alone</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<div id="cssbutton">
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h3>use('cssbutton')</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>YUI's Button component was designed with the idea in mind that sometimes you may only want button styles, without the need for any JavaScript functionality. Instead of `use('button', ...)`, you can just include the `cssbutton` module. This can be done dynamically with `use('cssbutton')`, or statically with a `link` tag.</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<link rel="stylesheet" href="http://yui.yahooapis.com/{{yuiVersion}}/build/cssbutton/cssbutton.css">
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>Loading this stylesheet will include the following classes:</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>yui3-button</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>yui3-button-disabled</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>yui3-button-hover, yui3-button:hover</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>yui3-button-active, yui3-button:active</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>yui3-button-primary, yui3-button-selected</li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>These styles are designed to progressively enhance. In legacy browsers, you'll get styles that appear as basic buttons, and in new browsers you'll get buttons using modern styles. cssbutton is intended to provide a base and be overridable with custom styles. Such as `background-color`.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h5>Background Color</h5>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>A feature of cssbutton is that it uses transparent gradients to create a colored effect. So if you would like a button that has a light to dark red gradient, you do not need to specify all the styles for proper cross-browser gradients, you only need to specify a single `background-color` style to your buttons.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright<div id="buttonplugin">
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h3>use('button-core')</h3>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>This module serves as the foundation for all Button component JavaScript modules and exports `Y.ButtonCore`. While you can use it stand-alone if you like, it is typically a foundational building block for all other Button classes.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright<div id="buttonplugin">
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h3>use('button-plugin')</h3>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <p>This module exports the `Y.Plugin.Node.createNode` factory, which simplifies the process of plugging nodes with `Y.ButtonCore`.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright<div id="button">
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h3>use('button')</h3>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>`Y.Button` combines `Y.ButtonCore` with `Y.Widget`, to give you basic button functionality, but with the benefits of having a <a href='/yui/docs/widget/'>Widget</a> instance. This can be used as a building block for different types of advanced buttons.</p>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>`Y.ToggleButton` does everything that `Y.Button` does (by extending it), and adds the concept of a selected state, which is referred to as either 'pressed' or 'checked', depending on the `type` attribute of the instance. This distinction is made for proper ARIA support.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h4>Benefits</h4>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <p>So what do you get from `Y.Button`/`Y.ToggleButton` over just creating or plugging a `<button>` node?</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <li><strong>Accessibility</strong> - Your buttons automatically create and manage their own ARIA <a href='http://www.w3.org/TR/wai-aria/states_and_properties'>states</a> & <a href='http://www.w3.org/TR/wai-aria/roles'>roles</a>. This includes states like `aria-pressed` & `aria-checked`, also appropriate roles like `button`, `checked`, `radio`, etc...</li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <li><strong>State management</strong> - Instances automatically apply classes, such as `yui3-button-selected` and `yui3-button-disabled` which are useful for styling purposes. Also, `Y.ToggleButton` will fire a 'pressedChange' or 'checkedChange' event (depending on `type`) when the button's state changes from selected to unselected, or vice-versa. This event eliminates the typical case of listening for all 'click' events and then verifying a state changed actually did occur.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<div id="buttongroup">
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h3>use('button-group')</h3>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <p>`Y.ButtonGroup` is a constructor that is used to generate widgets containing a group of buttons. To avoid widgets inside of widgets, this class is built on top of `Y.ButtonCore`, not `Y.Button`</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h2>Reference</h2>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright<p><strong>Note</strong>: This is not an exhaustive list. See the API documentation for a complete listing.</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h3>Attributes</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Attribute</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Data type</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Description</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>label</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>string</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Sets the button's `innerHTML` or `value` attribute depending on node type
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>disabled</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>boolean</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Sets the button's disabled state to true/false
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h4>Node Plugin</h4>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>Inherited from `Y.ButtonCore`</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>Identical to `Y.ButtonCore`</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>In addition to the inherited `Y.Button` attributes...</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Attribute</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Data type</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Description</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>type</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>string</td>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>Sets the type of a toggleable button.</p>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>Possible values:
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <li>'toggle' (default)</li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <li>'checkbox' </li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>The difference is that a 'toggle' button will use <a href='http://www.w3.org/TR/wai-aria/states_and_properties#aria-pressed'>aria-pressed</a>, and a 'checkbox' button will use <a href='http://www.w3.org/TR/wai-aria/states_and_properties#aria-checked'>aria-checked</a>.</p> </td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>In addition to the inherited `Y.ButtonCore` attributes...</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Attribute</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Data type</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Description</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>type</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>string</td>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>Sets the type of button group</p>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <p>Possible values:
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <li>'push' (default) - No buttons have a selectable state</li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <li>'radio' - Only one button is selectable at a time</li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <li>'checkbox' - Multiple buttons can be selected at a time</li>
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright<h3>Change Events</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Event</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Description</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>labelChange</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Fires to inform the subscriber that the button's label is about to be, or has been updated.
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>disabledChange</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Fires to notify the subscriber the disabled state is about to be, or has been updated.
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h4>Node Plugin</h4>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>Inherited from `Y.ButtonCore`</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>Identical to `Y.ButtonCore`</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>In addition to the inherited `Y.Button` events...</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Event</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Description</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>pressedChange</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Fires for toggle buttons to notify the subscriber the selected state is about to be, or has been updated.
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>checkedChange</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Identical to `"pressedChange"`, but only applicable for buttons with a configuration attribute `"type: 'checkbox'"`.
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<p>In addition to the inherited `Y.ButtonCore` events...</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Event</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <th>Description</th>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <td>selectionChange</td>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Fires when a button within the group is either selected or unselected. The event payload contains a reference `'originEvent'` to the original event, which can be used to obtain the target button.
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <br>`.on('eventName', fn)` will fire <strong>before</strong> the attribute & UI are updated.
7f2b731c52d0326179ad6ef2f4611ba088dcee22Derek Gathright <br>`.after('eventName', fn)` will fire <strong>after</strong> the attribute & UI are updated.