index.mustache revision d6fd645d5192ae6fff6d50db36de9f26bb4161d3
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){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Create a push button widget
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var button = new Y.Button({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#myButton'
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Create 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);
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright// Create some lighter-weight buttons by plugging nodes
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek GathrightYUI().use('button-plugin', function(Y){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Plug an existing node
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var button = new Y.Plugin.Button.nodeCreate("#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!');
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright// Create a button group widget
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
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright // Get an array of buttons that have a selected (pressed/checked) state
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var buttons = ButtonGroup.getSelectedButtons();
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h2>Anatomy</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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`use('cssbutton')` if you only want CSS-styled buttons</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`use('button')` if you want a button widget</li>
e9738690feeb7eae0899f34e5d0feec68bdbd48cDerek Gathright <li>`use('button-group')` if you want to manage a group of buttons (widget)</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`use('button-plugin')` if you only need a enhance a Y.Node instance with button functionality</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li>`button-core` is not intended to be used stand-alone</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<h2>Modules</h2>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<div id="cssbutton">
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h3>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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h4>Background Color</h4>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek 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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<div id="button">
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h3>button</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h5>Benefits of Y.Button</h5>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>So what do you get from Y.Button over just creating your own button node, via something like `new Y.Node.create('<button></button>')`</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek 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 <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>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <li><strong>Groups</strong> - `Y.ButtonGroup` allows you to group buttons together to create checkbox & radio groups, giving your users a nicer experience when compared to the standard `<input type='radio'>` or `<input type='checkbox'>` controls.</li>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h5>Events</h5>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>Most commonly with button elements, you want to listen for any clicks, or other <a href='/yui/docs/api/files/node_js_node-event.js.html#l8'>DOM events</a> that occur.</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var button = new Y.Button({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#myButton'
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright node.on('click', function(){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright alert('Hello!');
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>If you are more interested in listening to a `button`'s attribute change events, that can be done at creation.</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright var button = new Y.ToggleButton({
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright srcNode: '#myButton',
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright labelChange: function(){
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright Y.log('This will fire when the toggled state changes')
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>Any event handlers can also be assigned by using the `on` property in the configuration object. Valid events include any , as well as Y.Button attribute change events (e.g. 'selectedChange').</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek 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 button.</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<div id="buttonplugin">
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h3>button-plugin</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <p>This module exports the Y.Plugin.Node.createNode factory, which simplifies the process of plugging nodes.</p>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright<div id="buttongroup">
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek Gathright <h3>button-group</h3>
d6fd645d5192ae6fff6d50db36de9f26bb4161d3Derek 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`</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.