UI Documentation - WIP - Contribution welcome

order.yml

@@ -92,6 +92,16 @@
     - about-deferreds
     - jquery-deferreds
     - examples
+- jquery-ui:
+  - getting-started
+  - how-jquery-ui-works
+  - theming:
+    - themeroller
+    - api
+    - write-a-theme
+  - widget-factory:
+    - why-use-the-widget-factory
+    - how-to-use-the-widget-factory
 - jquery-mobile:
   - getting-started
   - theme-roller

page/jquery-ui.md

@@ -0,0 +1,11 @@
+---
+title: jQuery UI
+customFields:
+ -
+    key: "icon"
+    value: "magnet"
+---
+
+[jQuery UI](http://jqueryui.com) is a curated set of user interface interactions, effects, widgets, and themes built on top of the jQuery JavaScript Library. Whether you're building highly interactive web applications or you just need to add a date picker to a form control, jQuery UI is the perfect choice.
+
+jQuery UI contains many widgets that maintain state and therefore have a slightly different usage pattern than typical jQuery plugins. All of jQuery UI's widgets use the same patterns, so if you learn how to use one, then you'll know how to use all of them.

page/jquery-ui/getting-started.md

@@ -0,0 +1,114 @@
+---
+title: Getting Started with jQuery UI
+level: beginner
+---
+
+### What is jQuery UI?
+jQuery UI is a widget and interaction library built on top of the jQuery JavaScript Library that you can use to build highly interactive web applications.  This guide is designed to get you up to speed on how jQuery UI works. Follow along below to get started.
+
+### Start by checking out the demos
+To get a feel for what jQuery UI is capable of, check out the [UI Demos](http://jqueryui.com/demos/).
+
+In the demos section, the navigation lists all of the interactions and widgets that jQuery UI offers. Choose an interaction or widget and you'll be presented with several demo configurations for that particular plugin. Each demo allows you to view source code, change themes, and the URL can always be bookmarked. For example, check out the [accordion widget's fill space demo page](http://jqueryui.com/accordion/#fillspace).
+
+### Build your custom jQuery UI download
+Once you have a basic understanding of what jQuery UI is and what it does, you're ready to try it out! It's time to head over to the [Download Builder](http://jqueryui.com/download/) on the jQuery UI website to download a copy of jQuery UI. jQuery UI's download builder allows you to choose the components you would like to download and get a custom version of the library for your project. There are 3 easy steps to building your custom jQuery UI download:
+
+#### Step 1: Choose which components you need
+The main column of the Download Builder lists all of the javascript components in jQuery UI categorized into groups: core, interations, widgets, and effects. Some components in jQuery UI depend on other components. Just check the boxes for the widgets you'd like to download and any required dependencies will automatically be checked as well. The components you select will all be combined into a custom jQuery UI javascript file.
+
+![Configuring a download](/resources/jquery-ui/configure.png)
+
+#### Step 2: Select a theme (or roll your own custom theme)
+In the right column of the download builder, you'll find a field where you can choose from a number of pre-designed themes for your jQuery UI widgets. 
+You can either choose from the various themes we provide, or you can design your own custom theme using ThemeRoller (more on that later).
+
+**Advanced Theme Settings:** *The theme section of the download builder also offers some advanced configuration settings for your theme. If you plan to use multiple themes on a single page, these fields will come in handy. If you plan to only use one theme on a page, you can skip these settings entirely.*
+
+#### Step 3: Choose a version of jQuery UI
+The last step in the download builder is to select a version number. This is a very important step because jQuery UI versions are designed to work with specific versions of jQuery. The current versions are:
+
+* jQuery UI 1.10.0 - Requires jQuery 1.6+
+* jQuery UI 1.9.2 - Requires jQuery 1.6+
+
+#### Click Download!
+You're finished with the download builder! Click the download button and you'll get a customized zip file containing everything you selected.
+
+### After downloading: Intro to using jQuery UI
+Once you've downloaded jQuery UI, you'll get a zip containing the following files:
+
+* `/css/`
+* `/development-bundle/`
+* `/js/`
+* `index.html`
+
+### Basic overview: using jQuery UI on a web page
+Open up index.html in a text editor and you'll see that it links to a few dependencies: your theme, jQuery, and jQuery UI. Generally, you'll need to include these 3 files on any page to use jQuery UI widgets and interactions:
+
+
+```html
+<link type="text/css" href="css/themename/jquery-ui.custom.css" rel="Stylesheet" />	
+<script type="text/javascript" src="js/jquery.min.js"></script>
+<script type="text/javascript" src="js/jquery-ui.custom.min.js"></script>
+```
+
+Once you've included the necessary files, you can add some jQuery widgets to your page. For example, to make a datepicker widget, you'll add a text input element to your page and then call .datepicker(); on it. Like this:
+
+**HTML:**
+```html
+<input type="text" name="date" id="date">
+```
+
+**JS:**
+```javascript
+$('#date').datepicker();
+```
+
+![Example Screenshot](/resources/jquery-ui/ex-datepicker.png)
+
+#### That's it!
+For demos of all of the jQuery UI widgets and interactions. Check out the demos section of the jQuery UI website.
+
+### Customizing jQuery UI to your needs
+jQuery UI allows you to customize it in several ways. You've already seen how the download builder allows you to customize your copy of jQuery UI to include only the portions you want, but there are additional ways to customize that code to your implementation.
+
+### jQuery UI basics: using options
+Each plugin in jQuery UI has a default configuration which is catered to the most basic and common use case. But if you want a plugin to behave different from its default configuration, you can override each of its default settings using "options". Options are a set of properties passed into a jQuery UI widget as an argument. For example, the slider widget has an option for orientation, which allows you to specify whether the slider should be horizontal or vertical. To set this option for a slider on your page, you just pass it in as an argument, like this:
+
+
+```javascript
+$('#mySliderDiv').slider({
+  orientation: 'vertical'
+});
+```
+
+You can pass as many different options as you'd like by following each one with a comma (except the last one): 
+
+```javascript
+$('#mySliderDiv').slider({
+  orientation: 'vertical',
+  min: 0,
+  max: 150,
+  value: 50
+});
+```
+
+Just remember to surround your options with curly brackets `{ }`, and you're well on your way. Of course, the example above barely touches on what you can do with jQuery UI. To get detailed information on the entire set of jQuery UI widgets, visit the [jQuery UI documentation](http://jqueryui.com/demos/).
+
+### Visual customization: Designing a jQuery UI theme
+If you want to design your own theme, jQuery UI has a very slick application for just that purpose. It's called ThemeRoller, and you can always get to it by either clicking the "Themes" link in the jQuery UI navigation, or simply going to [jQuery UI Themeroller](http://jqueryui.com/themeroller/).
+
+ThemeRoller provides a custom interface for designing all of the elements used by jQuery UI widgets. As you tweak the "levers" in the left column, the widgets on the right will reflect your design. The Gallery tab of ThemeRoller offers a number of pre-designed themes (the same ones offered by the download builder) that you can tweak or download as they are.
+
+![Themeroller Example](/resources/jquery-ui/themeroller.png)
+
+### Downloading your theme
+When you click the "Download theme" button in ThemeRoller, you'll be directed to the Download Builder and your custom theme will be auto-selected in the Theme dropdown menu. You can configure your download package further from there. Once you download, you'll see that the example.html page is styled using your custom theme.
+
+**Quick tip:** *If you ever need to edit your theme, simply open the CSS file and find on line 43 where it says "To view and modify this theme, visit ..." That url will open the theme in ThemeRoller for editing.*
+
+### Support: Where can I get help?
+JQuery UI user and developer resources are kept up-to-date at the [Support Center](http://jqueryui.com/support). 
+
+### Developers Wanted!
+Want to join the jQuery UI team? We'd love your help! Visit the UI [Development Center](http://jqueryui.com/development) for details on how to get involved. 

page/jquery-ui/how-jquery-ui-works.md

@@ -0,0 +1,164 @@
+---
+title: How jQuery UI Works
+level: Beginner
+---
+
+jQuery UI contains many widgets that maintain [state](http://en.wikipedia.org/wiki/State_%28computer_science%29) and therefore may have a slightly different usage pattern than typical jQuery plugins you are already used to. While the initialization is the same as most jQuery plugins, jQuery UI's widgets are built on top of the [Widget Factory](/jquery-ui/widget-factory/) which provides the same general API to all of them. So if you learn how to use one, then you'll know how to use all of them! This document will walk you through the common functionality, using the [progressbar](http://jqueryui.com/progressbar/) widget for the code examples.
+
+## Initialization
+
+In order to track the state of the widget, we must introduce a full life cycle for the widget.
+The life cycle starts when the widget is initalized.
+To initialize a widget, we simply call the plugin on one or more elements.
+
+```
+  $( "#elem" ).progressbar();
+```
+
+This will initialize each element in the jQuery object, in this case the element with an id of "elem".
+Because we called the `progressbar()` method with no parameters, the widget is initialized with its default options.
+We can pass a set of options during initialization in order to override the default options.
+
+```
+  $( "#elem" ).progressbar({ value: 20 });
+```
+
+We can pass as many or as few options as we want during initialization.
+Any options that we don't pass will just use their default values.
+
+The options are part of the widget's state,
+so we can set options after initialization as well.
+We'll see this later with the `option` method.
+
+## Methods
+
+Now that the widget is initialized, we can query its state or perform actions on the widget.
+All actions after initialization take the form of a method call.
+To call a method on a widget, we pass the name of the method to the jQuery plugin.
+For example, to call the `value` method on our progressbar widget, we would use:
+
+```
+  $( "#elem" ).progressbar( "value" );
+```
+
+If the method accepts parameters, we can pass them after the method name.
+For example, to pass the parameter `40` to the `value` method, we can use:
+
+```
+  $( "#elem" ).progressbar( "value", 40 );
+```
+
+Just like other methods in jQuery, most widget methods return the jQuery object for chaining.
+
+```
+  $( "#elem" )
+    .progressbar( "value", 90 )
+    .addClass( "almost-done" );
+```
+
+### Common Methods
+
+Each widget will have its own set of methods based on the functionality that the widget provides.
+However, there are a few methods that exist on all widgets.
+
+#### option
+
+As we mentioned earlier, we can change options after initialization through the `option` method.
+For example, we can change the progressbar's value to 30 by calling the `option` method.
+
+```
+  $( "#elem" ).progressbar( "option", "value", 30 );
+```
+
+Note that this is different from the previous example where we were calling the `value` method.
+In this example, we're calling the `option` method and saying that we want to change the value option to 30.
+
+We can also get the current value for an option.
+
+```
+  $( "#elem" ).progressbar( "option", "value" );
+```
+
+In addition, we can update multiple options at once by passing an object to the `option` method.
+
+```
+  $( "#elem" ).progressbar( "option", {
+    value: 100,
+    disabled: true
+  });
+```
+
+You may have noticed that the `option` method has the same signature as getters and setters in jQuery core, such as `.css()` and `.attr()`.
+The only difference is that you have to pass the string "option" as the first parameter.
+
+#### disable
+
+As you might guess, the `disable` method disables the widget.
+In the case of progressbar, this changes the styling to make the progressbar look disabled.
+
+```
+  $( "#elem" ).progressbar( "disable" );
+```
+
+Calling the `disable` method is equivalent to setting the `disabled` option to `true`.
+
+#### enable
+
+The `enable` method is the opposite of the `disable` method.
+
+```
+  $( "#elem" ).progressbar( "enable" );
+```
+
+Calling the `enable` method is equivalent to setting the `disabled` option to `false`.
+
+#### destroy
+
+If you no longer need the widget, you can destroy it and return back to the original markup.
+This ends the life cycle of the widget.
+
+```
+  $( "#elem" ).progressbar( "destroy" );
+```
+
+Once you destroy a widget, you can no longer call any methods on it unless you initialize the widget again.
+If you're removing the element, either directly via `.remove()` or by modifying an ancestor with `.html()` or `.empty()`,
+the widget will automatically destroy itself.
+
+#### widget
+
+Some widgets generate wrapper elements, or elements disconnected from the original element.
+In these cases, the `widget` method will return the generated element.
+In cases like the progressbar, where there is no generated wrapper, the `widget` method returns the original element.
+
+```
+  $( "#elem" ).progressbar( "widget" );
+```
+
+## Events
+
+All widgets have events associated with their various behaviors to notify you when the state is changing.
+For most widgets, when the events are triggered, the names are prefixed with the widget name.
+For example, we can bind to progressbar's change event which is triggered whenever the value changes.
+
+```
+  $( "#elem" ).bind( "progressbarchange", function() {
+    alert( "The value has changed!" );
+  });
+```
+
+Each event has a corresponding callback, which is exposed as an option.
+We can hook into progressbar's `change` callback instead of binding to the `progressbarchange` event, if we wanted to.
+
+```
+  $( "#elem" ).progressbar({
+    change: function() {
+      alert( "The value has changed!" );
+    }
+  });
+```
+
+### Common Events
+
+While most events will be widget specific, all widgets have a `create` event.
+This event will be triggered immediately after the widget is created.

page/jquery-ui/theming.md

@@ -0,0 +1,34 @@
+---
+title: Theming jQuery UI
+level: intermediate
+---
+
+All jQuery UI plugins are designed to allow a developer to seamlessly integrate UI widgets into the look and feel of their site or application. Each plugin is styled with CSS and contains two layers of style information: standard [jQuery UI CSS Framework](/jquery-ui/theming/api/) styles and plugin-specific styles. 
+
+The jQuery UI CSS Framework provide semantic presentation classes to indicate the role of an element within a widget such as a header, content area, or clickable region. These are applied consistently across all widgets so a clickable tab, accordian or button will all have the same `ui-state-default` class applied to indicate that it is clickable. When a user mouses over one of these elements, this class is changed to `ui-state-hover`, then `ui-state-active` when selected. This level of class consistency makes it easy to ensure that all elements with a similar role or interaction state will look the same across all widgets.
+
+The CSS Framework styles are encapsulated in a single file called ui.theme.css and this is the file modified by the [ThemeRoller](/jquery-ui/theming/themeroller) application. Framework styles only include attributes that affect the look and feel (primarily color, background images and icons) so these are 'safe' styles that will not affect functionality of individual plugins. This separation means that a developer can create a custom look and feel by modifying the colors and images in theme.css file and know that as future plugins or bug fixes become available, these should work with the theme without modification.
+
+Since the framework styles only cover look and feel, plugin specific stylesheets are included that contain all the additional structural style rules required to make the widget functional, such as dimensions, padding, margins, positioning and floats. Stylesheets for each plugin are located in the themes/base folder of the download and are named to match the plugin such as "jquery.ui.accordion.css". These styles must be carefully edited because they work in conjunction with the scripting and provide overrides of framework styles as needed. 
+
+We encourage all developers creating jQuery plugins to leverage the jQuery UI CSS Framework because it will make it much easier for end users to theme and use your plugin.
+
+### Getting started
+
+There are three general approaches to theming jQuery UI plugins:
+
+* **Download a ThemeRoller theme**: The easiest way to build a theme is to use the [Themeroller](/jquery-ui/theming/themeroller) to generate and download a theme. This app will create a new `ui.theme.css` file and and images directory containing all necessary background images and icon sprites which can simply be dropped into your project. This approach will be the easiest to create and maintain but limits customization to the options provided in ThemeRoller.
+* **Modify the CSS files**: To get a bit more control over the look and feel, you may choose to start with the default theme (Smoothness) or a ThemeRoller-generated theme and then adjust the `ui.theme.css` file or any of the individual plugin stylesheets. For example, you could easily tweak the corner radius for all buttons to be different than the rest of the UI components or change the path for the icon sprite to use a custom set.  With a bit of style scoping, you can even use multiple themes together in a single UI. To keep maintenance simple, restricting changes to just the `ui.theme.css` file and images is recommended.
+* **Write completely custom CSS**: For the greatest amount of control, the CSS for each plugin can be written from scratch without using the framework classes or plugin-specific stylesheet. This may be necessary if the desired look and feel can't be achieved by modifying the CSS or if highly customized markup is used. This approach requires deep expertise in CSS and will require manual updates for future plugins.
+
+### Using ThemeRoller and Themes
+
+
+* [ThemeRoller application](http://jqueryui.com/themeroller/)
+* [ThemeRoller documentation](/jquery-ui/theming/themeroller) - How to use the ThemeRoller application
+
+### jQuery UI CSS Framework & Custom themes
+
+
+* [jQuery UI CSS Framework documentation](/jquery-ui/theming/api/) - Explore the full class API and icon set
+* [How to create custom themes](/jquery-ui/theming/custom-themes) - Tutorial for creating a theme from scratch