index.mustache revision e2f644c80c2428330032af20658279d458938f20
e2f644c80c2428330032af20658279d458938f20Derek Gathright<div class="intro">
e2f644c80c2428330032af20658279d458938f20Derek Gathright <p>The Button component for YUI 3 is a light-weight, Y.Base wrapper around DOM elements you'd like treated like a button. This includes things like look & feel, state management, and accessibility.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright{{>getting-started}}
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h2>Using Button</h2>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Quick Start</h3>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>There are two ways to create a Y.Button instance.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright// Or, use an existing node
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button({
e2f644c80c2428330032af20658279d458938f20Derek Gathright srcNode: "#myButton"
e2f644c80c2428330032af20658279d458938f20Derek GathrightYou can also create an unattached node and
e2f644c80c2428330032af20658279d458938f20Derek Gathright// Dynamically create the node
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button();
e2f644c80c2428330032af20658279d458938f20Derek GathrightY.one('#container').append(node);
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>In either case, you will receive a Y.Button instance that contains a few attributes, and wraps around a Y.Node instance. The markup generated will look something similar to:</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<button id="myButton" class="yui3-button" role="button"
e2f644c80c2428330032af20658279d458938f20Derek Gathright aria-selected="false" aria-pressed="false">My Button</button>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>At this point, you can modify `button`'s attributes, manipulate its state, or listen for change events.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Events</h3>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>Most commonly with button elements, you want to listen for any clicks that occur. That can be achieved with something like this...</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button({
e2f644c80c2428330032af20658279d458938f20Derek Gathright srcNode: "#myButton"
e2f644c80c2428330032af20658279d458938f20Derek Gathrightbutton.on('click', function(){
e2f644c80c2428330032af20658279d458938f20Derek Gathright alert("Hello!");
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>You can also pass in groups of events at creation:</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button({
e2f644c80c2428330032af20658279d458938f20Derek Gathright srcNode: '#myButton',
e2f644c80c2428330032af20658279d458938f20Derek Gathright type: 'toggle',
e2f644c80c2428330032af20658279d458938f20Derek Gathright click: function(){
e2f644c80c2428330032af20658279d458938f20Derek Gathright Y.log('This will fire when the button is clicked.')
e2f644c80c2428330032af20658279d458938f20Derek Gathright focus: function(){
e2f644c80c2428330032af20658279d458938f20Derek Gathright Y.log('The button is now focused')
e2f644c80c2428330032af20658279d458938f20Derek Gathright selectedChange: function(){
e2f644c80c2428330032af20658279d458938f20Derek Gathright Y.log('This will fire when the toggled state changed')
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>Any event handlers can also be assigned by using the `on` property in the configuration object. Valid events include any <a href="">DOM events</a>, as well as Y.Button attribute change events (e.g. 'selectedChange').</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Benefits</h3>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>So what do you get from Y.Button over just creating your own, via `new Y.Node.create('<button></button>')`</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <li><strong>Accessibility</strong> - Your buttons automatically create and manage their own ARIA states. This includes `aria-selected` and `aria-pressed`. Y.Button instances also automatically get the `role='button'` attribute to properly identify their purpose (as a button) to screen readers even if they are not a `<button>` or `<input type="button">` element.</li>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<li><strong>State management</strong> - Y.Button instances automatically apply classes, such as yui3-button-selected, yui3-button-disabled, and yui3-button-focused, which are useful for styling purposes. Also, assigning a type of 'toggle' will fire a 'selectedChange' event only when it's state changes from selected to unselected, or vice-versa, eliminating the classical case of listening for 'click' and then checking to see if the state changed.</li>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p><em>Note: In the future, Y.Button instances will be capable of being assigned to groups and managed via a new ButtonGroup module.</em></p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Styling</h3>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<p>YUI's Button component was designed with the idea in mind that you may only want button styles, no JS functionality. Instead of `use('button')`, you can just include the `cssbuttons` sub-module. This can be done either dynamically by `use('cssbuttons')` or statically with a <link> tag. Including this module will load in a stylesheet consisting of the following classes:</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <li>yui3-button</li>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <li>yui3-button:hover</li>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <li>yui3-button:active</li>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <li>yui3-button-disabled</li>
e2f644c80c2428330032af20658279d458938f20Derek 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 the latest styles that CSS3 has to offer.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Events</h3>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <th>Event</th>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <th>Description</th>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`selectedChange`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`disabledChange`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`typeChange`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`labelChange`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Configuration</h3>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <th>Event</th>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <th>Description</th>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`srcNode`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright The source node
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`label`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright The textual representation of the element
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`on`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright Any single event, or group of events
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`disabled`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright Whether or not the button should be disabled by default
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`selected`</td>
e2f644c80c2428330032af20658279d458938f20Derek Gathright Whether or not the button should be selected by default