index.mustache revision d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08
2362N/A <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>
2362N/A<p>There are two ways to create a Y.Button instance. The most common method is to assign it to an existing DOM node, like:</p>
2362N/Avar node = button.getNode();
829N/A<p>In either case, the object you receive from the constructor will be 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>
829N/A<p>At this point, you can modify `button`'s attributes, manipulate its state, or listen for change events.</p>
829N/A<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>
829N/Avar node = button.getNode();
829N/A<p>If you are more interested in listening to a `button`'s attribute change events, that can be done at creation.</p>
829N/A<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>
829N/A<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>
829N/A <li><strong>Accessibility</strong> - Your buttons automatically create and manage their own <a href='http://www.w3.org/TR/wai-aria/states_and_properties'>ARIA states</a>. 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>
829N/A<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 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 the state changed.</li>
829N/A<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>
829N/A<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 dynamically with `use('cssbuttons')`, or statically with a `<link>` tag.</p>
829N/A<p>Including this CSS module will load in a stylesheet consisting of the following classes:</p>
829N/A<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 CSS3 styles.</p>
829N/A<p>`button.on('eventName', fn)` will fire <strong>before</strong> the attribute & UI are updated.
829N/A<br>`button.after('eventName', fn)` will fire <strong>after</strong> the attribute & UI are updated.</p>