index.mustache revision 800a6a9307a3bbe026f640d20ef73c3d627efc37
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek 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>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<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>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright// Use an existing node
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button({
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright srcNode: '#myButton'
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek GathrightOr, you can also create an unattached node and append to a parent container:
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathrightvar button = new Y.Button(); // Dynamically create the node
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathrightvar node = button.getNode(); // Get the Y.Node instance
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek GathrightY.one('#container').append(node); // Append it to #container
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<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>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright<button id='myButton' class='yui3-button' 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>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright// Create a toggle button
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathrightbutton.getNode().on('click', function(){
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright button.set('selected', !button.get('selected'));
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright<h3>Benefits</h3>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek 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>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek 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>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek 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 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>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright <li><strong>Groups</strong> - `Y.ButtonGroup` allows you to group `Y.Button` instances together to create checkbox & radio groups, giving your users a nicer experience when compared to the standard radio or checkbox controls.</li>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright<h2>Anatomy of Button</h2>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright<p>YUI's Button component introduces 3 modules:</p>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright <li>`button-base` - Exports the Y.Button factory.</li>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright <li>`button-group` - Exports the Y.ButtonGroup factory.</li>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright <li>`cssbutton` - Imports various classes to provide default styles for your buttons.</li>
800a6a9307a3bbe026f640d20ef73c3d627efc37Derek Gathright<p>These can all be included with `use('button', ...)`, or you can specify modules individually. This approach is recommended if you do not need functionality of all three.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Events</h3>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek 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>
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button({
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright srcNode: '#myButton'
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathrightnode.on('click', function(){
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright alert('Hello!');
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<p>If you are more interested in listening to a `button`'s attribute change events, that can be done at creation.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathrightvar button = new Y.Button({
e2f644c80c2428330032af20658279d458938f20Derek Gathright srcNode: '#myButton',
e2f644c80c2428330032af20658279d458938f20Derek Gathright type: 'toggle',
e2f644c80c2428330032af20658279d458938f20Derek Gathright selectedChange: function(){
e2f644c80c2428330032af20658279d458938f20Derek Gathright Y.log('This will fire when the toggled state changed')
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek 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>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Styling</h3>
c270014f773974dbe11b6e0ff39990e5896caf1bDerek 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 `cssbutton` sub-module. This can be done dynamically with `use('cssbutton')`, or statically with a `<link>` tag.</p>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<p>Including this CSS 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>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek 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 CSS3 styles.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Events</h3>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<p>Here are the events emitted from a Y.Button instance </p>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<p>`button.on('eventName', fn)` will fire <strong>before</strong> the attribute & UI are updated.
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<br>`button.after('eventName', fn)` will fire <strong>after</strong> the attribute & UI are updated.</p>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <th>Event</th>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <th>Description</th>
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`selectedChange`</td>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright Fires for toggle buttons to notify the subscriber the selected state is about to be, or has been updated.
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`disabledChange`</td>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright Fires to notify the subscriber the disabled state is about to be, or has been updated.
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`typeChange`</td>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright Fires to inform the subscriber that the button's type is about to be, or has been updated.
e2f644c80c2428330032af20658279d458938f20Derek Gathright <td>`labelChange`</td>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright Fires to inform the subscriber that the button's label is about to be, or has been updated.
e2f644c80c2428330032af20658279d458938f20Derek Gathright<h3>Configuration</h3>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright<p>Here are the attributes that can be set on instantiation.</p>
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>
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright Any single event, or group of events to listen for.
d6c63bd07b2e1b034b608fb8af3ae94e6c03ee08Derek Gathright <br> Note: These are attribute change events, not DOM 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