|
192 | 192 | <xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
193 | 193 | <xi:include href="../includes/widget-option-hide.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
194 | 194 | <xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 195 | + <option name="classes" default="{}"> |
| 196 | + <desc> |
| 197 | + <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> |
| 198 | + <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> |
| 199 | + <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> |
| 200 | + </desc> |
| 201 | + <type name="Object" /> |
| 202 | + <example> |
| 203 | + <desc>Initialize a progressbar widget with the <code>classes</code> option specified, changing the theming for the <code>ui-progressbar</code> class:</desc> |
| 204 | + <code> |
| 205 | +$( ".selector" ).progressbar({ |
| 206 | + classes: { |
| 207 | + "ui-progressbar": "highlight" |
| 208 | + } |
| 209 | +}); |
| 210 | + </code> |
| 211 | + </example> |
| 212 | + <example> |
| 213 | + <desc>Get or set the <code>classes</code> option, after initialization:</desc> |
| 214 | + <code> |
| 215 | +// Getter |
| 216 | +var classes = $( ".selector" ).widget( "option", "classes" ); |
| 217 | + |
| 218 | +// Setter, override all classes |
| 219 | +$( ".selector" ).widget( "option", "classes", { "custom-header": "icon-warning" } ); |
| 220 | + |
| 221 | +// Setter, override just one class |
| 222 | +$( ".selector" ).widget( "option", "classes.custom-header", "icon-warning" ); |
| 223 | + </code> |
| 224 | + </example> |
| 225 | + </option> |
| 226 | + |
195 | 227 | </options> |
196 | 228 | <methods suppress-auto-examples="true"> |
197 | 229 | <xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
|
200 | 232 | <xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
201 | 233 | <xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
202 | 234 | <xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 235 | + <method name="_addClass"> |
| 236 | + <desc> |
| 237 | + Add classes to an element of the widget. |
| 238 | + <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> |
| 239 | + <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> |
| 240 | + </desc> |
| 241 | + <argument name="element" type="jQuery" optional="true"> |
| 242 | + <desc>The element to add the classes to. Defaults to <code>this.element</code>.</desc> |
| 243 | + </argument> |
| 244 | + <argument name="keys" type="String"> |
| 245 | + <desc> |
| 246 | + 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. |
| 247 | + <p>When you only need the <code>extra</code> argument, you can skip this argument by specifying <code>null</code>.</p> |
| 248 | + </desc> |
| 249 | + </argument> |
| 250 | + <argument name="extra" type="String" optional="true"> |
| 251 | + <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> |
| 252 | + </argument> |
| 253 | + <example> |
| 254 | + <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> |
| 255 | + <code><![CDATA[ |
| 256 | +this._addClass( "ui-progressbar" ); |
| 257 | +]]></code> |
| 258 | + </example> |
| 259 | + <example> |
| 260 | + <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> |
| 261 | + <code><![CDATA[ |
| 262 | +this._addClass( this.popup, "demo-popup-header", "ui-front" ); |
| 263 | +]]></code> |
| 264 | + </example> |
| 265 | + <example> |
| 266 | + <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> |
| 267 | + <code><![CDATA[ |
| 268 | +this._addClass( this.liveRegion, null, "ui-helper-hidden-accessible" ); |
| 269 | +]]></code> |
| 270 | + </example> |
| 271 | + </method> |
| 272 | + <method name="_removeClass"> |
| 273 | + <desc> |
| 274 | + Remove classes from an element of the widget. |
| 275 | + <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> |
| 276 | + </desc> |
| 277 | + <argument name="element" type="jQuery" optional="true"> |
| 278 | + <desc>The element to remove the classes from. Defaults to <code>this.element</code>.</desc> |
| 279 | + </argument> |
| 280 | + <argument name="keys" type="String"> |
| 281 | + <desc> |
| 282 | + 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. |
| 283 | + <p>When you only need the <code>extra</code> argument, you can skip this argument by specifying <code>null</code>.</p> |
| 284 | + </desc> |
| 285 | + </argument> |
| 286 | + <argument name="extra" type="String" optional="true"> |
| 287 | + <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> |
| 288 | + </argument> |
| 289 | + <example> |
| 290 | + <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> |
| 291 | + <code><![CDATA[ |
| 292 | +this._removeClass( "ui-progressbar" ); |
| 293 | +]]></code> |
| 294 | + </example> |
| 295 | + <example> |
| 296 | + <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> |
| 297 | + <code><![CDATA[ |
| 298 | +this._removeClass( this.popup, "demo-popup-header", "ui-front" ); |
| 299 | +]]></code> |
| 300 | + </example> |
| 301 | + <example> |
| 302 | + <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> |
| 303 | + <code><![CDATA[ |
| 304 | +this._removeClass( this.liveRegion, null, "ui-helper-hidden-accessible" ); |
| 305 | +]]></code> |
| 306 | + </example> |
| 307 | + </method> |
| 308 | + <method name="_toggleClass"> |
| 309 | + <desc> |
| 310 | + Toggle classes of an element of the widget. |
| 311 | + <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> |
| 312 | + <p class="warning">Unlike jQuery's <code>.toggleClass()</code> method, the boolean <code>add</code> argument is always required.</p> |
| 313 | + </desc> |
| 314 | + <argument name="element" type="jQuery" optional="true"> |
| 315 | + <desc>The element to toogle the classes on. Defaults to <code>this.element</code>.</desc> |
| 316 | + </argument> |
| 317 | + <argument name="keys" type="String"> |
| 318 | + <desc> |
| 319 | + 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. |
| 320 | + <p>When you only need the <code>extra</code> argument, you can skip this argument by specifying <code>null</code>.</p> |
| 321 | + </desc> |
| 322 | + </argument> |
| 323 | + <argument name="extra" type="String" optional="true"> |
| 324 | + <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> |
| 325 | + </argument> |
| 326 | + <argument name="add" type="Boolean"> |
| 327 | + <desc> |
| 328 | + <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> |
| 329 | + </desc> |
| 330 | + </argument> |
| 331 | + <example> |
| 332 | + <desc>Toggle the <code>ui-state-disabled</code> class on the widget's element (<code>this.element</code>).</desc> |
| 333 | + <code><![CDATA[ |
| 334 | +this._toggleClass( null, "ui-state-disabled", !!value ); |
| 335 | +]]></code> |
| 336 | + </example> |
| 337 | + </method> |
203 | 338 | <method name="_create"> |
204 | 339 | <desc> |
205 | 340 | The <code>_create()</code> method is the widget's constructor. |
|
0 commit comments