index.mustache revision 1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<div class='intro'>
e9738690feeb7eae0899f34e5d0feec68bdbd48cDerek Gathright <p>{{description}}</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright{{>getting-started}}
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h2>Using Button</h2>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h3>Quick Start</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'
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Change the push button's label
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright button.set('label', "I'm a YUI Button!");
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Activate the toggle button's 'pressed' state
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright toggleButton.set('pressed', true);
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright// Or, if you want something a little more light-weight...
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek GathrightYUI().use('button-plugin', function(Y){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Plug an existing node
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright var button = new Y.Plugin.Button.createNode("#testButton", {
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright label: "I'm a disabled button",
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright disabled: true
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright button.set('disabled', false);
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright button.set('label', 'Not anymore!');
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright button.on('click', function(){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Y.log('I was clicked!');
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright// And if you want to manage a group of buttons
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek GathrightYUI().use('button-group', function(Y){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Use an existing node to create a toggle button widget
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var buttonGroup = new Y.ButtonGroup({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#container' // Should contain <button> children
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright // Get an array of buttons that have a selected state
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var buttons = ButtonGroup.getSelectedButtons();
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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>These styles are designed to progressively enhance. In legacy browsers, you'll get styles that appear a bit nicer than native buttons, and in modern browsers you'll get buttons using modern CSS3 styles. These are intended to be base styles and all overridable.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h5>Background Color</h5>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek 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 one style, `background-color` and apply it to your buttons.</p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright<div id="buttonplugin">
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <h3>use('button-core')</h3>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek 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 as 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>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek Gathright <p>`Y.Button` essentially combines Y.ButtonCore with Y.Widget, to give you basic button functionality, but with the benefits of having a Y.Widget instance. This can become a building block for different types of buttons, for instance, a toggle button. </p>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek 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.</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>
1cdc9668bdd7d912d1be5b9f576c1fc35fdb20c2Derek 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' (depending on `type`) event only when the button state changes from selected to unselected, or vice-versa, eliminating the typical case of listening for 'click' and then checking to see if a state changed.</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>
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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright 'toggle' (default),
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <br>'checkbox' (multi-select)
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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright 'push' (default),
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <br>'radio' (single-select),
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <br>'checkbox' (multi-select)
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h3>Events</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <br>`.on('eventName', fn)` will fire <strong>before</strong> the attribute & UI are updated.
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <br>`.after('eventName', fn)` will fire <strong>after</strong> the attribute & UI are updated.
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.