<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Button</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
<link rel="stylesheet" href="../assets/css/main.css">
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
<script src="../../build/yui/yui-min.js"></script>
</head>
<body>
<!--
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
-->
<div id="doc">
<div id="hd">
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
</div>
<a href="#toc" class="jump">Jump to Table of Contents</a>
<h1>Button</h1>
<div class="yui3-g">
<div class="yui3-u-3-4">
<div id="main">
<div class="content"><div class='intro'>
<p>YUI's Button component is a mixed-module approach to providing a simple-to-use button that normalizes and enhances the Web browser's default button component.</p>
</div>
<h2 id="getting-started">Getting Started</h2>
<p>
To include the source files for Button and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>
<pre class="code prettyprint"><script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('button', function (Y) {
// Button is available and ready for use. Add implementation
// code here.
});
</script></pre>
<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
</p>
<h2 id="using-button---quick-start">Using Button - Quick Start</h2>
<h3 id="button-widgets">Button Widgets</h3>
<h4 id="html">HTML</h4>
<p>
<strong>Note:</strong> be sure to add the <code>yui3-skin-sam</code> classname to the
page's <code><body></code> element or to a parent element of the widget in order to apply
the default CSS skin. See <a href="http://yuilibrary.com/yui/docs/tutorials/skins/">Understanding Skinning</a>.
</p>
<pre class="code prettyprint"><body class="yui3-skin-sam"> <!-- You need this skin class -->
<button id="myButton">One</button></pre>
<h4 id="javascript">JavaScript</h4>
<pre class="code prettyprint">// Create some button widgets
YUI().use('button', function(Y){
// A push button widget
var button = new Y.Button({
srcNode: '#myButton'
});
// A toggle button widget
var toggleButton = new Y.ToggleButton({
srcNode: '#myToggleButton'
});
});</pre>
<h3 id="node-plugin">Node Plugin</h3>
<pre class="code prettyprint">// If you want something a little more light-weight than a widget...
YUI().use('button-plugin', function(Y){
var button = new Y.Plugin.Button.createNode("#testButton", {
label: "I'm a disabled button",
disabled: true
});
});</pre>
<h3 id="button-groups">Button Groups</h3>
<h4 id="html2">HTML</h4>
<p>
<strong>Note:</strong> be sure to add the <code>yui3-skin-sam</code> classname to the
page's <code><body></code> element or to a parent element of the widget in order to apply
the default CSS skin. See <a href="http://yuilibrary.com/yui/docs/tutorials/skins/">Understanding Skinning</a>.
</p>
<pre class="code prettyprint"><body class="yui3-skin-sam"> <!-- You need this skin class -->
<div id="container">
<button class='yui3-button'>One</button>
<button class='yui3-button'>Two</button>
<button class='yui3-button'>Three</button></pre>
<h4 id="javascript2">JavaScript</h4>
<pre class="code prettyprint">// And if you want to manage a group of buttons
YUI().use('button-group', function(Y){
var buttonGroup = new Y.ButtonGroup({
srcNode: '#container' // Should contain <button> children
});
});</pre>
<h2 id="modules">Modules</h2>
<p>YUI's Button component introduces 5 modules:</p>
<ul>
<li><a href="#cssbutton"><code>cssbutton</code></a> - Includes various <code>yui3-button</code> styles to provide a normalized CSS base for buttons.</li>
<li><a href="#button"><code>button</code></a> - Exports the <code>Y.Button</code> & <code>Y.ToggleButton</code> widgets.</li>
<li><a href="#buttongroup"><code>button-group</code></a> - Exports the <code>Y.ButtonGroup</code> widget.</li>
<li><a href="#buttonplugin"><code>button-plugin</code></a> - Exports the <code>Y.Plugin.Button.createNode</code> factory.</li>
<li><code>button-core</code> - Exports <code>Y.ButtonCore</code>, a base used by all other Button component modules.</li>
</ul>
<h3 id="which-one-to-use">Which one to use?</h3>
<ul>
<li><code>use('cssbutton')</code> if you only want a CSS stylesheet to enhance button(-like) nodes</li>
<li><code>use('button-plugin')</code> if you only need to enhance a DOM node with button functionality</li>
<li><code>use('button')</code> if you want a button widget</li>
<li><code>use('button-group')</code> if you want a widget to manage a group of buttons</li>
<li><code>button-core</code> is not intended to be used stand-alone</li>
</ul>
<div id="cssbutton">
<h3 id="usecssbutton">use('cssbutton')</h3>
<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 <code>use('button', ...)</code>, you can just include the <code>cssbutton</code> module. This can be done dynamically with <code>use('cssbutton')</code>, or statically with a <code>link</code> tag.</p>
<pre class="code prettyprint"><link rel="stylesheet" href="http://yui.yahooapis.com/3.10.3/build/cssbutton/cssbutton.css"></pre>
<p>Loading this stylesheet will include the following classes:</p>
<ul>
<li>yui3-button</li>
<li>yui3-button-disabled</li>
<li>yui3-button-hover, yui3-button:hover</li>
<li>yui3-button-active, yui3-button:active</li>
<li>yui3-button-primary, yui3-button-selected</li>
</ul>
<p>These styles are designed to progressively enhance. In legacy browsers, you'll get styles that appear as basic buttons, and in new browsers you'll get buttons using modern styles. cssbutton is intended to provide a base and be overridable with custom styles. Such as <code>background-color</code>.</p>
<h5 id="background-color">Background Color</h5>
<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 a single <code>background-color</code> style to your buttons.</p>
</div>
<div id="buttonplugin">
<h3 id="usebutton-core">use('button-core')</h3>
<p>This module serves as the foundation for all Button component JavaScript modules and exports <code>Y.ButtonCore</code>. While you can use it stand-alone if you like, it is typically a foundational building block for all other Button classes.</p>
</div>
<div id="buttonplugin">
<h3 id="usebutton-plugin">use('button-plugin')</h3>
<p>This module exports the <code>Y.Plugin.Node.createNode</code> factory, which simplifies the process of plugging nodes with <code>Y.ButtonCore</code>.</p>
</div>
<div id="button">
<h3 id="usebutton">use('button')</h3>
<h4 id="ybutton">Y.Button</h4>
<p><code>Y.Button</code> combines <code>Y.ButtonCore</code> with <code>Y.Widget</code>, to give you basic button functionality, but with the benefits of having a <a href='/yui/docs/widget/'>Widget</a> instance. This can be used as a building block for different types of advanced buttons.</p>
<h4 id="ytogglebutton">Y.ToggleButton</h4>
<p><code>Y.ToggleButton</code> does everything that <code>Y.Button</code> does (by extending it), and adds the concept of a selected state, which is referred to as either 'pressed' or 'checked', depending on the <code>type</code> attribute of the instance. This distinction is made for proper ARIA support.</p>
<h4 id="benefits">Benefits</h4>
<p>So what do you get from <code>Y.Button</code>/<code>Y.ToggleButton</code> over just creating or plugging a <code><button></code> node?</p>
<ul>
<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 <code>aria-pressed</code> & <code>aria-checked</code>, also appropriate roles like <code>button</code>, <code>checked</code>, <code>radio</code>, etc...</li>
<li><strong>State management</strong> - Instances automatically apply classes, such as <code>yui3-button-selected</code> and <code>yui3-button-disabled</code> which are useful for styling purposes. Also, <code>Y.ToggleButton</code> will fire a 'pressedChange' or 'checkedChange' event (depending on <code>type</code>) when the button's state changes from selected to unselected, or vice-versa. This event eliminates the typical case of listening for all 'click' events and then verifying a state changed actually did occur.</li>
</ul>
</div>
<div id="buttongroup">
<h3 id="usebutton-group">use('button-group')</h3>
<p><code>Y.ButtonGroup</code> 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 <code>Y.ButtonCore</code>, not <code>Y.Button</code></p>
</div>
<h2 id="reference">Reference</h2>
<p><strong>Note</strong>: This is not an exhaustive list. See the API documentation for a complete listing.</p>
<h3 id="attributes">Attributes</h3>
<h4 id="ybuttoncore">Y.ButtonCore</h4>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Data type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>label</td>
<td>string</td>
<td>
Sets the button's <code>innerHTML</code> or <code>value</code> attribute depending on node type
</td>
</tr>
<tr>
<td>disabled</td>
<td>boolean</td>
<td>
Sets the button's disabled state to true/false
</td>
</tr>
</tbody>
</table>
<h4 id="node-plugin2">Node Plugin</h4>
<p>Inherited from <code>Y.ButtonCore</code></p>
<h4 id="ybutton2">Y.Button</h4>
<p>Identical to <code>Y.ButtonCore</code></p>
<h4 id="ytogglebutton2">Y.ToggleButton</h4>
<p>In addition to the inherited <code>Y.Button</code> attributes...</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Data type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>string</td>
<td>
<p>Sets the type of a toggleable button.</p>
<p>Possible values:
<ul>
<li>'toggle' (default)</li>
<li>'checkbox' </li>
</ul>
</p>
<p>The difference is that a 'toggle' button will use <a href='http://www.w3.org/TR/wai-aria/states_and_properties#aria-pressed'>aria-pressed</a>, and a 'checkbox' button will use <a href='http://www.w3.org/TR/wai-aria/states_and_properties#aria-checked'>aria-checked</a>.</p> </td>
</tr>
</tbody>
</table>
<h4 id="ybuttongroup">Y.ButtonGroup</h4>
<p>In addition to the inherited <code>Y.ButtonCore</code> attributes...</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Data type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>string</td>
<td>
<p>Sets the type of button group</p>
<p>Possible values:
<ul>
<li>'push' (default) - No buttons have a selectable state</li>
<li>'radio' - Only one button is selectable at a time</li>
<li>'checkbox' - Multiple buttons can be selected at a time</li>
</ul>
</p>
</td>
</tr>
</tbody>
</table>
<h3 id="change-events">Change Events</h3>
<h4 id="ybuttoncore2">Y.ButtonCore</h4>
<table>
<thead>
<tr>
<th>Event</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>labelChange</td>
<td>
Fires to inform the subscriber that the button's label is about to be, or has been updated.
</td>
</tr>
<tr>
<td>disabledChange</td>
<td>
Fires to notify the subscriber the disabled state is about to be, or has been updated.
</td>
</tr>
</tbody>
</table>
<h4 id="node-plugin3">Node Plugin</h4>
<p>Inherited from <code>Y.ButtonCore</code></p>
<h4 id="ybutton3">Y.Button</h4>
<p>Identical to <code>Y.ButtonCore</code></p>
<h4 id="ytogglebutton3">Y.ToggleButton</h4>
<p>In addition to the inherited <code>Y.Button</code> events...</p>
<table>
<thead>
<tr>
<th>Event</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>pressedChange</td>
<td>
Fires for toggle buttons to notify the subscriber the selected state is about to be, or has been updated.
</td>
</tr>
<tr>
<td>checkedChange</td>
<td>
Identical to <code>"pressedChange"</code>, but only applicable for buttons with a configuration attribute <code>"type: 'checkbox'"</code>.
</td>
</tr>
</tbody>
</table>
<h4 id="ybuttongroup2">Y.ButtonGroup</h4>
<p>In addition to the inherited <code>Y.ButtonCore</code> events...</p>
<table>
<thead>
<tr>
<th>Event</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>selectionChange</td>
<td>
Fires when a button within the group is either selected or unselected. The event payload contains a reference <code>'originEvent'</code> to the original event, which can be used to obtain the target button.
</td>
</tr>
</tbody>
</table>
<p>
Note:
<br><code>.on('eventName', fn)</code> will fire <strong>before</strong> the attribute & UI are updated.
<br><code>.after('eventName', fn)</code> will fire <strong>after</strong> the attribute & UI are updated.
</p>
</div>
</div>
</div>
<div class="yui3-u-1-4">
<div class="sidebar">
<div id="toc" class="sidebox">
<div class="hd">
<h2 class="no-toc">Table of Contents</h2>
</div>
<div class="bd">
<ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#using-button---quick-start">Using Button - Quick Start</a>
<ul class="toc">
<li>
<a href="#button-widgets">Button Widgets</a>
<ul class="toc">
<li>
<a href="#html">HTML</a>
</li>
<li>
<a href="#javascript">JavaScript</a>
</li>
</ul>
</li>
<li>
<a href="#node-plugin">Node Plugin</a>
</li>
<li>
<a href="#button-groups">Button Groups</a>
<ul class="toc">
<li>
<a href="#html2">HTML</a>
</li>
<li>
<a href="#javascript2">JavaScript</a>
</li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#modules">Modules</a>
<ul class="toc">
<li>
<a href="#which-one-to-use">Which one to use?</a>
</li>
<li>
<a href="#usecssbutton">use('cssbutton')</a>
<ul class="toc">
<li>
<a href="#background-color">Background Color</a>
</li>
</ul>
</li>
<li>
<a href="#usebutton-core">use('button-core')</a>
</li>
<li>
<a href="#usebutton-plugin">use('button-plugin')</a>
</li>
<li>
<a href="#usebutton">use('button')</a>
<ul class="toc">
<li>
<a href="#ybutton">Y.Button</a>
</li>
<li>
<a href="#ytogglebutton">Y.ToggleButton</a>
</li>
<li>
<a href="#benefits">Benefits</a>
</li>
</ul>
</li>
<li>
<a href="#usebutton-group">use('button-group')</a>
</li>
</ul>
</li>
<li>
<a href="#reference">Reference</a>
<ul class="toc">
<li>
<a href="#attributes">Attributes</a>
<ul class="toc">
<li>
<a href="#ybuttoncore">Y.ButtonCore</a>
</li>
<li>
<a href="#node-plugin2">Node Plugin</a>
</li>
<li>
<a href="#ybutton2">Y.Button</a>
</li>
<li>
<a href="#ytogglebutton2">Y.ToggleButton</a>
</li>
<li>
<a href="#ybuttongroup">Y.ButtonGroup</a>
</li>
</ul>
</li>
<li>
<a href="#change-events">Change Events</a>
<ul class="toc">
<li>
<a href="#ybuttoncore2">Y.ButtonCore</a>
</li>
<li>
<a href="#node-plugin3">Node Plugin</a>
</li>
<li>
<a href="#ybutton3">Y.Button</a>
</li>
<li>
<a href="#ytogglebutton3">Y.ToggleButton</a>
</li>
<li>
<a href="#ybuttongroup2">Y.ButtonGroup</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="This example shows how you can easily style button and non-button DOM elements to appear as buttons">
<a href="cssbutton.html">Styling elements with cssbutton</a>
</li>
<li data-description="This example shows a simple, light solution to enhance <button> nodes">
<a href="button-plugin.html">Enhancing <button> nodes with button-plugin</a>
</li>
<li data-description="This example demonstrates how to create button widgets">
<a href="button-basic.html">Basic button widgets</a>
</li>
<li data-description="This example demonstrates how to create a widget containing a group of buttons">
<a href="button-group.html">Managing groups of buttons with button-group</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script>
YUI.Env.Tests = {
examples: [],
project: '../assets',
assets: '../assets/button',
name: 'button',
title: 'Button',
newWindow: '',
auto: false
};
YUI.Env.Tests.examples.push('cssbutton');
YUI.Env.Tests.examples.push('button-plugin');
YUI.Env.Tests.examples.push('button-basic');
YUI.Env.Tests.examples.push('button-group');
</script>
<script src="../assets/yui/test-runner.js"></script>
</body>
</html>