All: Document classes option

Fixes #256
jquery · jzaefferer · Apr 20, 2015 · Mar 19, 2015 · Apr 20, 2015 · Apr 20, 2015
commit 0a9749065d0d4c036f7a335b34598e72c0aa124e
diff --git a/entries/accordion.xml b/entries/accordion.xml
@@ -39,8 +39,13 @@
 			<li>
 				<code>ui-accordion</code>: The outer container of the accordion.
 				<ul>
-					<li><code>ui-accordion-header</code>: The headers of the accordion. The headers will additionally have a <code>ui-accordion-icons</code> class if they contain <a href="#option-icons"><code>icons</code></a>.</li>
-					<li><code>ui-accordion-content</code>: The content panels of the accordion.</li>
+					<li>
+						<code>ui-accordion-header</code>: The headers of the accordion. The active header will additionally have a <code>ui-accordion-content-active</code> class, the inactive headers will have a <code>ui-accordion-header-collapsed</code> class. The headers will also have a <code>ui-accordion-icons</code> class if they contain <a href="#option-icons"><code>icons</code></a>.
+						<ul>
+							<li><code>ui-accordion-header-icon</code>: Icon elements within each accordion header.</li>
+						</ul>
+					</li>
+					<li><code>ui-accordion-content</code>: The content panels of the accordion. The active content panel will additionally have a <code>ui-accordion-content-active</code> class.</li>
 				</ul>
 			</li>
 		</ul>
@@ -86,6 +91,15 @@
 				</desc>
 			</type>
 		</option>
+		<option name="classes" type="Object">
+			<default>{
+	"ui-accordion-header": "ui-corner-top",
+	"ui-accordion-header-collapsed": "ui-corner-all",
+	"ui-accordion-content": "ui-corner-bottom"
+}</default>
+			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		</option>
 		<option name="collapsible" type="Boolean" default="false" example-value="true">
 			<desc>Whether all the sections can be closed at once. Allows collapsing the active section.</desc>
 		</option>
@@ -108,7 +122,11 @@
 				</ul>
 			</desc>
 		</option>
-		<option name="icons" type="Object" default='{ "header": "ui-icon-triangle-1-e", "activeHeader": "ui-icon-triangle-1-s" }' example-value='{ "header": "ui-icon-plus", "activeHeader": "ui-icon-minus" }'>
+		<option name="icons" type="Object" example-value='{ "header": "ui-icon-plus", "activeHeader": "ui-icon-minus" }'>
+			<default>{
+	"header": "ui-icon-triangle-1-e",
+	"activeHeader": "ui-icon-triangle-1-s"
+}</default>
 			<desc>
 				<p>Icons to use for headers, matching <a href="/theming/icons/">an icon provided by the jQuery UI CSS Framework</a>. Set to <code>false</code> to have no icons displayed.</p>
 				<ul>

diff --git a/entries/autocomplete.xml b/entries/autocomplete.xml
@@ -32,7 +32,7 @@
 
 		<ul>
 			<li><code>ui-autocomplete</code>: The <a href="/menu/#theming">menu</a> used to display matches to the user.</li>
-			<li><code>ui-autocomplete-input</code>: The input element that the Autocomplete widget was instantiated with.</li>
+			<li><code>ui-autocomplete-input</code>: The input element that the autocomplete widget was instantiated with. While requesting data to display to the user, the <code>ui-autocomplete-loading</code> class is also added to this element.</li>
 		</ul>
 
 		<h3>Dependencies</h3>
@@ -55,6 +55,10 @@
 		<option name="autoFocus" type="Boolean" default="false" example-value="true">
 			<desc>If set to <code>true</code> the first item will automatically be focused when the menu is shown.</desc>
 		</option>
+		<option name="classes" type="Object" default="{}">
+			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		</option>
 		<option name="delay" type="Integer" default="300" example-value="500">
 			<desc>The delay in milliseconds between when a keystroke occurs and when a search is performed. A zero-delay makes sense for local data (more responsive), but can produce a lot of load for remote data, while being less responsive.</desc>
 		</option>

diff --git a/entries/button.xml b/entries/button.xml
@@ -39,6 +39,13 @@
 	<note id="functional-css"/>
 	<added>1.8</added>
 	<options>
+		<option name="classes" type="Object">
+			<default>{
+	"ui-button": "ui-corner-all",
+}</default>
+			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		</option>
 		<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<option name="icons" default="{ primary: null, secondary: null }" example-value='{ primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }'>
 			<desc>

diff --git a/entries/dialog.xml b/entries/dialog.xml
@@ -55,7 +55,7 @@
 
 		<ul>
 			<li>
-				<code>ui-dialog</code>: The outer container of the dialog.
+				<code>ui-dialog</code>: The outer container of the dialog. If the <a href="#option-draggable"><code>draggable</code> option</a> is set, the <code>ui-dialog-dragging</code> class is added during a drag. If the <a href="#option-resizable"><code>resizable</code> option</a> is set, the <code>ui-dialog-resizing</code> class is added during a resize. If the <a href="#option-buttons"><code>buttons</code> option</a> is set, the <code>ui-dialog-buttons</code> class is added.
 				<ul>
 					<li>
 						<code>ui-dialog-titlebar</code>: The title bar containing the dialog's title and close button.
@@ -125,6 +125,14 @@
 				<desc>Each element of the array must be an object defining the attributes, properties, and event handlers to set on the button. In addition, a key of <code>icons</code> can be used to control <a href="/button/#option-icons">button's <code>icons</code> option</a>, and a key of <code>showText</code> can be used to control <a href="/button/#option-text">button's <code>text</code> option</a>.</desc>
 			</type>
 		</option>
+		<option name="classes" type="Object">
+			<default>{
+	"ui-dialog": "ui-corner-all",
+	"ui-dialog-titlebar": "ui-corner-all",
+}</default>
+			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		</option>
 		<option name="closeOnEscape" default="true" example-value="false">
 			<desc>Specifies whether the dialog should close when it has focus and the user presses the escape (ESC) key.</desc>
 			<type name="Boolean" />

diff --git a/entries/draggable.xml b/entries/draggable.xml
@@ -5,6 +5,13 @@
 	<longdesc>
 		<p>Make the selected elements draggable by mouse. If you want not just drag, but drag &amp; drop, see the <a href="/droppable/">jQuery UI Droppable plugin</a>, which provides a drop target for draggables.</p>
 
+		<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+
+		<ul>
+			<li><code>ui-draggable</code>: The draggable element. When the draggable is disabled, the <code>ui-draggable-disabled</code> class is added. While dragging, the <code>ui-draggable-dragging</code> class is added.</li>
+			<li><code>ui-draggable-handle</code>: The handle of the draggable, specified using the <a href="#option-handle"><code>handle</code> option</a>. By default, the draggable element itself is also the handle.</li>
+		</ul>
+
 		<h3>Dependencies</h3>
 		<ul>
 			<li><a href="/category/ui-core/">UI Core</a></li>
@@ -41,6 +48,10 @@
 		<option name="cancel" type="Selector" default='"input,textarea,button,select,option"' example-value='".title"'>
 			<desc>Prevents dragging from starting on specified elements.</desc>
 		</option>
+		<option name="classes" type="Object" default="{}">
+			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		</option>
 		<option name="connectToSortable" type="Selector" default="false" example-value='"#my-sortable"'>
 			<desc>Allows the draggable to be dropped onto the specified sortables. If this option is used, a draggable can be dropped onto a sortable list and then becomes part of it. Note: The <a href="#option-helper"><code>helper</code></a> option must be set to <code>"clone"</code> in order to work flawlessly. Requires the <a href="/sortable/">jQuery UI Sortable plugin</a> to be included.</desc>
 		</option>

diff --git a/entries/droppable.xml b/entries/droppable.xml
@@ -5,6 +5,12 @@
 	<longdesc>
 		<p>The jQuery UI Droppable plugin makes selected elements droppable (meaning they accept being dropped on by <a href="/draggable/">draggables</a>). You can specify which draggables each will accept.</p>
 
+		<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+
+		<ul>
+			<li><code>ui-droppable</code>: The droppable element. When a draggable that can be dropped on this dropppable is activated, the <code>ui-droppable-active</code> class is added. When dragging a draggable over this droppable, the <code>ui-droppable-hover</code> class is added.</li>
+		</ul>
+
 		<h3>Dependencies</h3>
 		<ul>
 			<li><a href="/category/ui-core/">UI Core</a></li>
@@ -29,6 +35,10 @@
 		<option name="addClasses" type="Boolean" default="true" example-value="false">
 			<desc>If set to <code>false</code>, will prevent the <code>ui-droppable</code> class from being added. This may be desired as a performance optimization when calling <code>.droppable()</code> init on hundreds of elements.</desc>
 		</option>
+		<option name="classes" type="Object" default="{}">
+			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		</option>
 		<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<option name="greedy" type="Boolean" default="false" example-value="true">
 			<desc>By default, when an element is dropped on nested droppables, each droppable will receive the element. However, by setting this option to <code>true</code>, any parent droppables will not receive the element. The <code>drop</code> event will still bubble normally, but the <code>event.target</code> can be checked to see which droppable received the draggable element.</desc>

diff --git a/entries/jQuery.widget.xml b/entries/jQuery.widget.xml
@@ -192,6 +192,38 @@
 			<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 			<xi:include href="../includes/widget-option-hide.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 			<xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<option name="classes" default="{}">
+				<desc>
+					<p>Additional (thematic) classes to add to the widget, in addition to the structural classes. The structural classes are used as keys of this option and the thematic classes are the values. See the <a href="#method-_addClass"><code>_addClass()</code> method</a> for using this in custom widgets. Check out the documentation of individual widgets to see which classes they support.</p>
+					<p>The primary motivation of this option is to map structural classes to theme classes. In other words, any class prefixed with namespace and widget, like <code>"ui-progressbar-"</code>, is considered a structural class. These are always added to the widget. In contrast to that, any class not specific to the widget is considered a theme class. These could be part of jQuery UI's CSS framework, but can also come from other CSS frameworks or be defined in custom stylesheets.</p>
+					<p class="warning">Setting the <code>classes</code> option after creation will override all default properties. To only change specific values, use deep setters, e.g. <code>.option( "classes.ui-progressbar-value", null )</code>.</p>
+				</desc>
+				<type name="Object" />
+				<example>
+					<desc>Initialize a progressbar widget with the <code>classes</code> option specified, changing the theming for the <code>ui-progressbar</code> class:</desc>
+					<code>
+$( ".selector" ).progressbar({
+	classes: {
+		"ui-progressbar": "highlight"
+	}
+});
+				</code>
+				</example>
+				<example>
+					<desc>Get or set the <code>classes</code> option, after initialization:</desc>
+					<code>
+// Getter
+var classes = $( ".selector" ).widget( "option", "classes" );
+
+// Setter, override all classes
+$( ".selector" ).widget( "option", "classes", { "custom-header": "icon-warning" } );
+
+// Setter, override just one class
+$( ".selector" ).widget( "option", "classes.custom-header", "icon-warning" );
+				</code>
+				</example>
+			</option>
+
 		</options>
 		<methods suppress-auto-examples="true">
 			<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
@@ -200,6 +232,109 @@
 			<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 			<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 			<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+			<method name="_addClass">
+				<desc>
+					Add classes to an element of the widget.
+					<p>This provides a hook for the user to add additional classes or replace default styling classes, through the <a href="#option-classes"><code>classes</code> option</a>.</p>
+					<p>It also provides automatic removal of these classes when a widget is destroyed, as long as you're using <a href="#method-_addClass"><code>_addClass()</code></a>, <a href="#method-_removeClass"><code>_removeClass()</code></a> and <a href="#method-_toggleClass"><code>_toggleClass()</code></a> together. This can heavily simplify the implementation of custom <a href="#method-_destroy"><code>_destroy()</code></a> methods.</p>
+				</desc>
+				<argument name="element" type="jQuery" optional="true">
+					<desc>The element to add the classes to. Defaults to <code>this.element</code>.</desc>
+				</argument>
+				<argument name="keys" type="String">
+					<desc>
+						The classes to add, as a space-delimited list. If a property of the <a href="#option-classes"><code>classes</code> option</a> matches a key, the value will be added as well.
+						<p>When you only need the <code>extra</code> argument, you can skip this argument by specifying <code>null</code>.</p>
+					</desc>
+				</argument>
+				<argument name="extra" type="String" optional="true">
+					<desc>Additional classes to add, required for layout or other reasons. Unlike the <code>keys</code> argument, these aren't associated with any properties of the <a href="#option-classes"><code>classes</code> option</a>. Just like <code>keys</code>, they will also be automatically removed when destroying the widget.</desc>
+				</argument>
+				<example>
+					<desc>Add the <code>ui-progressbar</code> class to the widget's element (<code>this.element</code>). Will also add any additional classes specified through the <a href="#option-classes"><code>classes</code> option</a> for the given class.</desc>
+					<code><![CDATA[
+this._addClass( "ui-progressbar" );
+]]></code>
+				</example>
+				<example>
+					<desc>Add the <code>demo-popup-header</code> class to the specified element (here referencing <code>this.popup</code>). Will also add any additional classes specified through the <a href="#option-classes"><code>classes</code> option</a> for the given class. In addition, it will always add the <code>ui-front</code> class.</desc>
+					<code><![CDATA[
+this._addClass( this.popup, "demo-popup-header", "ui-front" );
+]]></code>
+				</example>
+				<example>
+					<desc>Adds the <code>ui-helper-hidden-accessible</code> class to the specified element. Uses <code>null</code> for the <code>keys</code> argument to skip it.</desc>
+					<code><![CDATA[
+this._addClass( this.liveRegion, null, "ui-helper-hidden-accessible" );
+]]></code>
+				</example>
+			</method>
+			<method name="_removeClass">
+				<desc>
+					Remove classes from an element of the widget.
+					<p>The arguments are the same as for the <a href="#method-_addClass"><code>_addClass()</code> method</a>, the same semantics apply, just in reverse.</p>
+				</desc>
+				<argument name="element" type="jQuery" optional="true">
+					<desc>The element to remove the classes from. Defaults to <code>this.element</code>.</desc>
+				</argument>
+				<argument name="keys" type="String">
+					<desc>
+						The classes to remove, as a space-delimited list. If a property of the <a href="#option-classes"><code>classes</code> option</a> matches a key, the value will be removed as well.
+						<p>When you only need the <code>extra</code> argument, you can skip this argument by specifying <code>null</code>.</p>
+					</desc>
+				</argument>
+				<argument name="extra" type="String" optional="true">
+					<desc>Additional classes to remove, required for layout or other reasons. Unlike the <code>keys</code> argument, these aren't associated with any properties of the <a href="#option-classes"><code>classes</code> option</a>.</desc>
+				</argument>
+				<example>
+					<desc>Remove the <code>ui-progressbar</code> class from the widget's element (<code>this.element</code>). Will also remove any additional classes specified through the <a href="#option-classes"><code>classes</code> option</a> for the given class.</desc>
+					<code><![CDATA[
+this._removeClass( "ui-progressbar" );
+]]></code>
+				</example>
+				<example>
+					<desc>Remove the <code>demo-popup-header</code> class from the specified element (here referencing <code>this.popup</code>). Will also remove any additional classes specified through the <a href="#option-classes"><code>classes</code> option</a> for the given class. In addition, it will also remove the <code>ui-front</code> class.</desc>
+					<code><![CDATA[
+this._removeClass( this.popup, "demo-popup-header", "ui-front" );
+]]></code>
+				</example>
+				<example>
+					<desc>Remove the <code>ui-helper-hidden-accessible</code> class from the specified element. Uses <code>null</code> for the <code>keys</code> argument to skip it.</desc>
+					<code><![CDATA[
+this._removeClass( this.liveRegion, null, "ui-helper-hidden-accessible" );
+]]></code>
+				</example>
+			</method>
+			<method name="_toggleClass">
+				<desc>
+					Toggle classes of an element of the widget.
+					<p>The arguments are the same as for the <a href="#method-_addClass"><code>_addClass()</code></a> and <a href="#method-_removeClass"><code>_removeClass()</code></a> methods, except for the additional boolean argument that specifies to add or remove classes.</p>
+					<p class="warning">Unlike jQuery's <code>.toggleClass()</code> method, the boolean <code>add</code> argument is always required.</p>
+				</desc>
+				<argument name="element" type="jQuery" optional="true">
+					<desc>The element to toogle the classes on. Defaults to <code>this.element</code>.</desc>
+				</argument>
+				<argument name="keys" type="String">
+					<desc>
+						The classes to toogle, as a space-delimited list. If a property of the <a href="#option-classes"><code>classes</code> option</a> matches a key, the value will be toggled as well.
+						<p>When you only need the <code>extra</code> argument, you can skip this argument by specifying <code>null</code>.</p>
+					</desc>
+				</argument>
+				<argument name="extra" type="String" optional="true">
+					<desc>Additional classes to toggle, required for layout or other reasons. Unlike the <code>keys</code> argument, these aren't associated with any properties of the <a href="#option-classes"><code>classes</code> option</a>. Just like <code>keys</code>, they will also be automatically removed when destroying the widget.</desc>
+				</argument>
+				<argument name="add" type="Boolean">
+					<desc>
+						<p>Indicates whether to add or remove the specified classes, where a boolean <code>true</code> indicates that classes should be added, a boolean <code>false</code> indicates that classes should be removed.</p>
+					</desc>
+				</argument>
+				<example>
+					<desc>Toggle the <code>ui-state-disabled</code> class on the widget's element (<code>this.element</code>).</desc>
+					<code><![CDATA[
+this._toggleClass( null, "ui-state-disabled", !!value );
+]]></code>
+				</example>
+			</method>
 			<method name="_create">
 				<desc>
 					The <code>_create()</code> method is the widget's constructor.