Skip to content

Commit 6ffbb44

Browse files
jzaeffererjzaefferer
committed
Button: Document rewrite, deprecate buttonset, document new widgets
Adds entries for checkboxradio and controlgroup, with links from both button and buttonset entries. Fixes jquery#260
1 parent d01d090 commit 6ffbb44

File tree

4 files changed

+213
-21
lines changed

4 files changed

+213
-21
lines changed

‎entries/button.xml

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,34 @@
55
<longdesc>
66
<p>Button enhances standard form elements like buttons, inputs and anchors to themeable buttons with appropriate hover and active styles.</p>
77

8-
<p>In addition to basic push buttons, radio buttons and checkboxes (inputs of type radio and checkbox) can be converted to buttons. Their associated label is styled to appear as the button, while the underlying input is updated on click. For the association to work properly, give the input an <code>id</code> attribute, and refer to that in the label's <code>for</code> attribute. Don't nest the input inside the label, as that <a href="http://www.paciellogroup.com/blog/2011/07/html5-accessibility-chops-form-control-labeling/">causes accessibility problems</a>.</p>
9-
10-
<p>In order to group radio buttons, you can use the <a href="/buttonset/">Buttonset</a> widget, which provides visual groupings of buttons.</p>
11-
128
<p>When using an input of type button, submit or reset, support is limited to plain text labels with no icons.</p>
139

10+
<p class="warning">Note: The button widget was rewritten in 1.12. Some options changed, you can find documentation for the old options in the <a href="/1.11/button/">1.11 button docs</a>. This widget used to bundle support for inputs of type radio and checkbox, this is now deprecated, use the <a href="/checkboxradio/">checkboxradio widget</a> instead. It also used to bundle the buttonset widget, this is also deprecated, use the <a href="/controlgroup/">controlgroup widget</a> instead.</p>
11+
1412
<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
1513

1614
<ul>
1715
<li>
18-
<code>ui-button</code>: The DOM element that represents the button. This element will additionally have one of the following classes depending on the <a href="#option-text">text</a> and <a href="#option-icons">icons</a> option: <code>ui-button-text-only</code>, <code>ui-button-icon-only</code>, <code>ui-button-icons-only</code>, <code>ui-button-text-icons</code>.
16+
<code>ui-button</code>: The DOM element that represents the button. This element will additionally have the <code>ui-button-icon-only</code> class, depending on the <a href="#option-showLabel">showLabel</a> and <a href="#option-icon">icon</a> options.
1917
<ul>
2018
<li>
21-
<code>ui-button-icon-primary</code>: The element used to display the button's primary icon. This will only be present if a primary icon is provided in the <a href="#option-icons">icons</a> option.
19+
<code>ui-button-icon</code>: The element used to display the button icon. This will only be present if an icon is provided in the <a href="#option-icon">icon</a> option.
2220
</li>
2321
<li>
24-
<code>ui-button-text</code>: The container around the textual content of the button.
25-
</li>
26-
<li>
27-
<code>ui-button-icon-secondary</code>: The element used to display the button's secondary icon. This will only be present if a secondary icon is provided in the <a href="#option-icons">icons</a> option.
22+
<code>ui-button-icon-space</code>: A separator element between icon and text content of the button. This will only be present if an icon is provided in the <a href="#option-icon">icon</a> option and the <a href="#option-iconPosition">iconPosition</a> option is set to <code>"beginning"</code> or <code>"end"</code>.
2823
</li>
2924
</ul>
3025
</li>
3126
</ul>
3227

3328
<h3>Dependencies</h3>
3429
<ul>
35-
<li><a href="/category/ui-core/">UI Core</a></li>
30+
<li><a href="/jQuery.ui.keyCode/">jQuery.ui.keyCode</a></li>
3631
<li><a href="/jQuery.widget/">Widget Factory</a></li>
3732
</ul>
3833
</longdesc>
3934
<note id="functional-css"/>
40-
<added>1.8</added>
35+
<added>1.8, rewritten: 1.12</added>
4136
<options>
4237
<option name="classes" type="Object">
4338
<default>{
@@ -47,14 +42,19 @@
4742
<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
4843
</option>
4944
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
50-
<option name="icons" default="{ primary: null, secondary: null }" example-value='{ primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }'>
45+
<option name="icon" default="null" example-value='{ icon: "ui-icon-gear" }'>
5146
<desc>
52-
<p>Icons to display, with or without text (see <a href="#option-text"><code>text</code></a> option). By default, the primary icon is displayed on the left of the label text and the secondary is displayed on the right. The positioning can be controlled via CSS.</p>
53-
54-
<p>The value for the <code>primary</code> and <code>secondary</code> properties must match <a href="/theming/icons/">an icon class name</a>, e.g., <code>"ui-icon-gear"</code>. For using only one icon: <code>icons: { primary: "ui-icon-locked" }</code>. For using two icons: <code>icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }</code>.</p>
47+
<p>Icon to display, with or without text (see <a href="#option-showLabel"><code>showLabel</code></a> option). By default, the icon is displayed on the left of the label text. The positioning can be controlled using the <a href="#option-iconPosition"><code>iconPosition</code></a> option.</p>
48+
<p>The value for this option must match <a href="/theming/icons/">an icon class name</a>, e.g., <code>"ui-icon-gear"</code>.</p>
5549
<p>When using an input of type button, submit or reset, icons are not supported.</p>
5650
</desc>
57-
<type name="Object" />
51+
<type name="String" />
52+
</option>
53+
<option name="iconPosition" default='"beginning"' example-value='{ iconPositon: "end" }'>
54+
<desc>
55+
<p>Where to display the <a href="#option-icon"><code>icon</code></a>: Valid values are "beginning", "end", "top" and "bottom". In a left-to-right (LTR) display, "beginning" refers to the left, in a right-to-left (RTL, e.g. in Hebrew or Arabic), it refers to the right.</p>
56+
</desc>
57+
<type name="String" />
5858
</option>
5959
<option name="label" default="null" example-value='"custom label"'>
6060
<desc>
@@ -63,8 +63,8 @@
6363
</desc>
6464
<type name="String" />
6565
</option>
66-
<option name="text" default="true" example-value="false">
67-
<desc>Whether to show the label. When set to <code>false</code> no text will be displayed, but the <a href="#option-icons"><code>icons</code></a> option must be enabled, otherwise the <code>text</code> option will be ignored.</desc>
66+
<option name="showLabel" default="true" example-value="false">
67+
<desc>Whether to show the label. When set to <code>false</code> no text will be displayed, but the <a href="#option-icon"><code>icon</code></a> option must be used, otherwise the <code>showLabel</code> option will be ignored.</desc>
6868
<type name="Boolean" />
6969
</option>
7070
</options>
@@ -76,7 +76,7 @@
7676
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7777
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7878
<method name="refresh">
79-
<desc>Refreshes the visual state of the button. Useful for updating button state after the native element's checked or disabled state is changed programmatically.</desc>
79+
<desc>Refreshes the visual state of the button. Useful for updating button state after the native element's disabled state is changed programmatically.</desc>
8080
</method>
8181
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
8282
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

‎entries/buttonset.xml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
<?xml version="1.0"?>
2-
<entry name="buttonset" type="widget" widget-element="button set element that contains the buttons">
2+
<entry name="buttonset" type="widget" widget-element="button set element that contains the buttons" deprecated="1.12">
33
<title>Buttonset Widget</title>
44
<desc>Themeable button sets.</desc>
55
<longdesc>
6+
<p class="warning">This widget is deprecated, use <a href="/controlgroup/">Controlgroup</a> instead.</p>
7+
68
<div class="note">
79
<code>.buttonset()</code> is bundled with <code>.button()</code>. Although they are separate widgets, they are combined into a single file. If you have <code>.button()</code> available, you also have <code>.buttonset()</code> available.
810
</div>

‎entries/checkboxradio.xml

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<?xml version="1.0"?>
2+
<entry name="checkboxradio" type="widget" widget-element="checkboxradio">
3+
<title>Checkboxradio Widget</title>
4+
<desc>Converts inputs of type radio and checkbox to themeable buttons.</desc>
5+
<longdesc>
6+
<p>Native HTML input elements are impossible to style consistently. This widget allows working around that limitation by positining the associated label on top of the hidden input, and emulating the checkbox or radio element itself using an (optional) icon. The original input still receives focus and all events, the label merely provides a themeable button on top.</p>
7+
8+
<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
9+
10+
<ul>
11+
<li>
12+
<code>ui-checkboxradio</code>: The input of type radio or checkbox. Will be hidden, with its associated label positioned on top.
13+
<ul>
14+
<li>
15+
<code>ui-checkboxradio-label</code>: The label associated with the input. If the input is checked, this will also get the <code>ui-checkboxradio-checked</code> class. If the input is of type radio, this will also get the <code>ui-checkboxradio-radio-label</code> class.
16+
</li>
17+
<li>
18+
<code>ui-checkboxradio-icon</code>: If the <a href="#option-icon"><code>icon</code></a> option is enabled, the generated icon has this class.
19+
</li>
20+
<li>
21+
<code>ui-checkboxradio-icon-space</code>: If the <a href="#option-icon"><code>icon</code></a> option is enabled, an extra element with this class as added between the text label and the icon.
22+
</li>
23+
</ul>
24+
</li>
25+
26+
</ul>
27+
28+
<h3>Dependencies</h3>
29+
<ul>
30+
<li><a href="/labels/">.labels()</a></li>
31+
<li><a href="/jQuery.widget/">Widget Factory</a></li>
32+
</ul>
33+
</longdesc>
34+
<note id="functional-css"/>
35+
<added>1.12</added>
36+
<options>
37+
<option name="classes" type="Object">
38+
<default>{
39+
"ui-checkboxradio-label": "ui-corner-all",
40+
"ui-checkboxradio-icon": "ui-corner-all"
41+
}</default>
42+
<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
43+
<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
44+
</option>
45+
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
46+
<option name="icon" default="true" example-value="false">
47+
<desc>Whether to show the checkbox or radio icon, depending on the input's type.</desc>
48+
<type name="Boolean" />
49+
</option>
50+
<option name="label" default="null" example-value='"custom label"'>
51+
<desc>Text to show in the button. When not specified (<code>null</code>), the HTML content of the associated <code>&lt;label&gt;</code> element is used.</desc>
52+
<type name="String" />
53+
</option>
54+
</options>
55+
<events>
56+
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
57+
</events>
58+
<methods>
59+
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
60+
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
61+
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
62+
<method name="refresh">
63+
<desc>Refreshes the visual state of the widget. Useful for updating after the native element's checked or disabled state is changed programmatically.</desc>
64+
</method>
65+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
66+
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
67+
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
68+
</methods>
69+
<example>
70+
<height>100</height>
71+
<desc>A simple jQuery UI checkboxradio</desc>
72+
<code><![CDATA[
73+
$( "input[type='radio']" ).checkboxradio();
74+
]]></code>
75+
<html><![CDATA[
76+
<fieldset>
77+
<legend>Select a Location: </legend>
78+
<label for="radio-1">New York</label>
79+
<input type="radio" name="radio-1" id="radio-1">
80+
<label for="radio-2">Paris</label>
81+
<input type="radio" name="radio-1" id="radio-2">
82+
<label for="radio-3">London</label>
83+
<input type="radio" name="radio-1" id="radio-3">
84+
</fieldset>
85+
]]></html>
86+
</example>
87+
<category slug="widgets"/>
88+
</entry>

‎entries/controlgroup.xml

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<?xml version="1.0"?>
2+
<entry name="controlgroup" type="widget" widget-element="controlgroup">
3+
<title>Controlgroup Widget</title>
4+
<desc>Themeable set of input widgets.</desc>
5+
<longdesc>
6+
<p>A controlgroup provides a visual grouping for <a href="/button/">button</a> and other input widgets. Controlgroup works by selecting all appropriate descendants, based on the <a href="#option-items">items</a> option, and applying their respective widgets, if loaded. If the widgets already exist, their <code>refresh()</code> method is called. You can enable and disable a controlgroup, which will enable and disable all contained widgets. Destroying a controlgroup also calls each widgets's <code>.destroy()</code> method.</p>
7+
8+
<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
9+
10+
<ul>
11+
<li>
12+
<code>ui-controlgroup</code>: The outer container of controlgroups. Depending on the <a href="#option-direction">direction</a> option, this element will additionally have the <code>ui-controlgroup-horizontal</code> or <code>ui-controlgroup-vertical</code> classes.
13+
<ul>
14+
<li>
15+
<code>ui-controlgroup-item</code>: Each item inside the group.
16+
</li>
17+
</ul>
18+
</li>
19+
20+
</ul>
21+
22+
<h3>Dependencies</h3>
23+
<ul>
24+
<li><a href="/jQuery.widget/">Widget Factory</a></li>
25+
</ul>
26+
</longdesc>
27+
<note id="functional-css"/>
28+
<added>1.12</added>
29+
<options>
30+
<option name="classes" type="Object" default="{}">
31+
<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
32+
<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
33+
</option>
34+
<option name="direction" default='"horizontal"' example-value='{ direction: "vertical" }'>
35+
<desc>
36+
<p>By default, controlgroup displays its widget's in a horizontal layout. Use this option to use a vertical layout instead.</p>
37+
</desc>
38+
<type name="String" />
39+
</option>
40+
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
41+
<option name="onlyVisible" default="true" example-value="false">
42+
<desc>Sets whether to exclude invisible children in the assignment of rounded corners. When set to false, all children of a controlgroup are taken into account when assigning rounded corners, including hidden children. Thus, if, for example, the controlgroup's first child is hidden, the controlgroup will, in effect, not have rounded corners on the top edge.</desc>
43+
<type name="Boolean" />
44+
</option>
45+
<option name="items">
46+
<default>{
47+
"button": "input[type=button], input[type=submit], input[type=reset], button, a",
48+
"controlgroupLabel": ".ui-controlgroup-label",
49+
"checkboxradio": "input[type='checkbox'], input[type='radio']",
50+
"selectmenu": "select",
51+
"spinner": ".ui-spinner-input"
52+
}</default>
53+
<desc>
54+
Which descendant elements to initialize as their respective widgets. Two elements have special behaviour:
55+
<ul>
56+
<li><code>controlgroupLabel</code>: Any elements matching the selector for this will be wrapped in a span with the <code>ui-controlgroup-label-contents</code> class.</li>
57+
<li><code>spinner</code>: This uses a class selector as the value. Requires either adding the class manually or initializing the spinner manually. Can be overridden to use <code>input[type=number]</code>, but that also requires custom CSS to remove the native number controls.</li>
58+
</ul>
59+
</desc>
60+
<type name="Object" />
61+
</option>
62+
</options>
63+
<events>
64+
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
65+
</events>
66+
<methods>
67+
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
68+
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
69+
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
70+
<method name="refresh">
71+
<desc>Process any widgets that were added or removed directly in the DOM. Results depend on the <a href="#option-items"><code>items</code></a> option.</desc>
72+
</method>
73+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
74+
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
75+
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
76+
</methods>
77+
<example>
78+
<height>100</height>
79+
<desc>A simple jQuery UI controlgroup</desc>
80+
<code><![CDATA[
81+
$( "#radio" ).controlgroup();
82+
]]></code>
83+
<html><![CDATA[
84+
<form>
85+
<fieldset>
86+
<legend>Favorite jQuery Project</legend>
87+
<div id="radio">
88+
<input type="radio" id="sizzle" name="project">
89+
<label for="sizzle">Sizzle</label>
90+
91+
<input type="radio" id="qunit" name="project" checked="checked">
92+
<label for="qunit">QUnit</label>
93+
94+
<input type="radio" id="color" name="project">
95+
<label for="color">Color</label>
96+
</div>
97+
</fieldset>
98+
</form>
99+
]]></html>
100+
</example>
101+
<category slug="widgets"/>
102+
</entry>

0 commit comments

Comments
 (0)