From 8e91c2eff56c182cad6bfcab59c69443643f5f81 Mon Sep 17 00:00:00 2001 From: TJ VanToll Date: Sun, 30 Nov 2014 11:33:45 -0500 Subject: [PATCH 1/2] =?UTF-8?q?jQuery=20UI:=20Article=20on=20the=20classes?= =?UTF-8?q?=20option=E2=80=94new=20to=20jQuery=20UI=201.12?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- order.json | 3 +- .../widget-factory/classes-option.md | 134 ++++++++++++++++++ 2 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 page/jquery-ui/widget-factory/classes-option.md diff --git a/order.json b/order.json index ee998761..38e12a24 100644 --- a/order.json +++ b/order.json @@ -116,7 +116,8 @@ "why-use-the-widget-factory", "how-to-use-the-widget-factory", "widget-method-invocation", - "extending-widgets" + "extending-widgets", + "classes-option" ] }, { diff --git a/page/jquery-ui/widget-factory/classes-option.md b/page/jquery-ui/widget-factory/classes-option.md new file mode 100644 index 00000000..330fad96 --- /dev/null +++ b/page/jquery-ui/widget-factory/classes-option.md @@ -0,0 +1,134 @@ + + +As of the 1.12 release, the jQuery UI widget factory includes a means of managing CSS class names through the [`classes` option](http://api.jqueryui.com/jquery.widget/#option-classes). This article will give you an overview of how the `classes` option works, and discuss what you can do with it. + +## Syntax overview + +The `classes` option is used to map structural class names to custom class names that you define. To see what this means let's look at an example. The code below uses the `classes` option to create a red dialog: + +``` + + +``` + +Here, the presentational `custom-red` class name is associated with the structural `ui-dialog` class name. Now, whenever the dialog applies the `ui-dialog` class name, it will also add a `custom-red` class name. You can associate multiple class names by including multiple space-delimited class names in the object's value. For instance the following code creates a dialog that is big and red: + +``` + + +``` + +*Note: To get a full list of the class names you can use with the `classes` option, you can log the default values stored at `$.namespace.wigetName.prototype.options.classes`. For instance, the dialog widget's default values are available at `$.ui.dialog.prototype.options.classes`. Additionally, the API documentation for all jQuery UI widgets list the class names they use; here are dialog's: .* + +The `classes` option works like any other widget factory option, which means all the widget factory option mechanisms still apply. For instance, the following code uses the [`option()` method](http://api.jqueryui.com/jquery.widget/#method-option) to remove all class names currently associated with the `ui-dialog` class name: + +``` +dialog.dialog( "option", "classes.ui-dialog", "" ); +``` + +And the following creates a [widget extension](http://learn.jquery.com/jquery-ui/widget-factory/extending-widgets/) that automatically associates the `custom-red` and `custom-big` class names with the `ui-dialog` class name: + +``` + + +``` + +As an added benefit, the widget factory also removes any class names specified in the `classes` option when the widget is destroyed. + +## Theming + +As the previous examples show, the `classes` option provides a quick way to associate custom class names with class names used within a widget. This approach works for simple cases, but it can also be used to adapt third-party themes to work with widget-factory-built widgets. For example, if you're using [Bootstrap](http://getbootstrap.com/) and jQuery UI together, you can use the following code to create a jQuery UI dialog that uses Bootstrap's theming: + +``` +$.extend( $.ui.dialog.prototype.options.classes, { + "ui-dialog": "modal-content", + "ui-dialog-titlebar": "modal-header", + "ui-dialog-title": "modal-title", + "ui-dialog-titlebar-close": "close", + "ui-dialog-content": "modal-body", + "ui-dialog-buttonpane": "modal-footer" +}); +``` + +For more examples of this approach, check out [Alexander Schmitz's repo](https://github.com/arschmitz/jqueryui-bootstrap-adapter) that adapts jQuery UI to work with Boostrap using the `classes` option. + +## Using the `classes` option in your own widgets + +Custom widgets can take advantage of the `classes` option just like the jQuery UI widgets do. In fact, the widget factory provides a number of new helper methods to make implementing your own `classes` option relatively easy. As an example consider the following custom redBox widget, *before* the `classes` option: + +``` + + +``` + +Adding the `classes` option to this widget allows users to do two things: associate new class names with the `custom-red-box` class name, as well as control how the `ui-corner-all` class name is used. The code below shows an updated implementation of the `redBox` widget that makes these use cases possible: + +``` + + +``` + +There are two changes to note here. The first is the specification of the `classes` property in the `options` object. This configures the default mapping of structural class names to presentational class names. Here the structural `custom-red-box` class name is mapped to a presentational `ui-corner-all` class name. + +The second thing to note is the use of the widget factory's new `_addClass()` and `_removeClass()` methods. The methods are shorthands that accept a structural class name and apply it, and its associated presentational class names, to an element. You can specify the element by passing it as the first argument of `_addClass()`/`_removeClass()` (or `_toggleClass()`, which hasn't been mentioned yet, but it also available), or you can omit the element as this example does, in which case the classes are applied to or removed from the widget's main element (`this.element`). For more examples of how these methods work, refer to the API documentation of [`_addClass()`]((http://api.jqueryui.com/jquery.widget/#method-_addClass), [`_removeClass()`]((http://api.jqueryui.com/jquery.widget/#method-_removeClass), and [`_toggleClass()`]((http://api.jqueryui.com/jquery.widget/#method-_toggleClass). + +In general, using the `classes` options in your widgets gives your widgets' users flexibility in how your widgets' class names are managed, and lets them adapt to a wide variety of themes. From 072569b659108cf8276704c7a5b979dcfed39fb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Scott=20Gonz=C3=A1lez?= Date: Thu, 15 Sep 2016 09:06:55 -0400 Subject: [PATCH 2/2] update --- .../widget-factory/classes-option.md | 67 +++---------------- 1 file changed, 10 insertions(+), 57 deletions(-) diff --git a/page/jquery-ui/widget-factory/classes-option.md b/page/jquery-ui/widget-factory/classes-option.md index 330fad96..f5504f47 100644 --- a/page/jquery-ui/widget-factory/classes-option.md +++ b/page/jquery-ui/widget-factory/classes-option.md @@ -7,7 +7,7 @@ As of the 1.12 release, the jQuery UI widget factory includes a means of managin ## Syntax overview -The `classes` option is used to map structural class names to custom class names that you define. To see what this means let's look at an example. The code below uses the `classes` option to create a red dialog: +The `classes` option is used to map structural class names to theme-related class names that you define. To see what this means let's look at an example. The code below uses the `classes` option to create a red dialog: ``` ``` -*Note: To get a full list of the class names you can use with the `classes` option, you can log the default values stored at `$.namespace.wigetName.prototype.options.classes`. For instance, the dialog widget's default values are available at `$.ui.dialog.prototype.options.classes`. Additionally, the API documentation for all jQuery UI widgets list the class names they use; here are dialog's: .* +*Note: To get a full list of the class names you can use with the `classes` option, check the API documentation for the jQuery UI widget you're interested in. For example, here's the list of classes for the dialog width: .* The `classes` option works like any other widget factory option, which means all the widget factory option mechanisms still apply. For instance, the following code uses the [`option()` method](http://api.jqueryui.com/jquery.widget/#method-option) to remove all class names currently associated with the `ui-dialog` class name: ``` -dialog.dialog( "option", "classes.ui-dialog", "" ); +dialog.dialog( "option", "classes.ui-dialog", null ); ``` -And the following creates a [widget extension](http://learn.jquery.com/jquery-ui/widget-factory/extending-widgets/) that automatically associates the `custom-red` and `custom-big` class names with the `ui-dialog` class name: +And the following creates a [widget extension](http://learn.jquery.com/jquery-ui/widget-factory/extending-widgets/) that automatically associates the `custom-red` class with the `ui-dialog` class: ``` -``` - -Adding the `classes` option to this widget allows users to do two things: associate new class names with the `custom-red-box` class name, as well as control how the `ui-corner-all` class name is used. The code below shows an updated implementation of the `redBox` widget that makes these use cases possible: - -``` - - -``` - -There are two changes to note here. The first is the specification of the `classes` property in the `options` object. This configures the default mapping of structural class names to presentational class names. Here the structural `custom-red-box` class name is mapped to a presentational `ui-corner-all` class name. - -The second thing to note is the use of the widget factory's new `_addClass()` and `_removeClass()` methods. The methods are shorthands that accept a structural class name and apply it, and its associated presentational class names, to an element. You can specify the element by passing it as the first argument of `_addClass()`/`_removeClass()` (or `_toggleClass()`, which hasn't been mentioned yet, but it also available), or you can omit the element as this example does, in which case the classes are applied to or removed from the widget's main element (`this.element`). For more examples of how these methods work, refer to the API documentation of [`_addClass()`]((http://api.jqueryui.com/jquery.widget/#method-_addClass), [`_removeClass()`]((http://api.jqueryui.com/jquery.widget/#method-_removeClass), and [`_toggleClass()`]((http://api.jqueryui.com/jquery.widget/#method-_toggleClass). - -In general, using the `classes` options in your widgets gives your widgets' users flexibility in how your widgets' class names are managed, and lets them adapt to a wide variety of themes. +The introduction of the `classes` option takes us one step further in the split between structural and theme-related classes, making it easier than ever to make jQuery UI widgets match the look and feel of your existing site. At the same time, this allows jQuery UI to be used alongside other CSS frameworks, just like jQuery can be used alongside other JavaScript frameworks.