Skip to content

Commit 2a21fbf

Browse files
tjvantolltjvantoll
committed
jQuery UI: Adding guide to using jQuery UI with AMD.
Ref jquerygh-186 Closes jquerygh-462
1 parent 66154fe commit 2a21fbf

File tree

3 files changed

+131
-0
lines changed

3 files changed

+131
-0
lines changed

‎order.yml

+2
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,8 @@
101101
- widget-factory:
102102
- why-use-the-widget-factory
103103
- how-to-use-the-widget-factory
104+
- environments:
105+
- amd
104106
- jquery-mobile:
105107
- getting-started
106108
- theme-roller

‎page/jquery-ui/environments.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: Using jQuery UI
3+
level: intermediate
4+
---
5+
6+
In addition to being available on [CDN](http://code.jquery.com/)s and [Download Builder](http://jqueryui.com/download/), jQuery UI also integrates into a number of development environments.

‎page/jquery-ui/environments/amd.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Using jQuery UI with AMD
3+
level: intermediate
4+
---
5+
6+
As of jQuery UI 1.11, all of the library's source files support using AMD. This means that you can manage your jQuery UI dependencies without using [Download Builder](http://jqueryui.com/download/), and load jQuery UI's source files asynchronously using an AMD loader such as [RequireJS](http://requirejs.org/).
7+
8+
In this article we'll walk through the process of using AMD with jQuery UI. Let's start by discussing the files we'll need.
9+
10+
### Requirements
11+
12+
We'll need to download three things to get up and running: jQuery core, jQuery UI, and an AMD loader.
13+
14+
While any AMD loader will work, we'll use RequireJS in this article, which you can download from <http://requirejs.org/docs/download.html>. If you don't have a version of jQuery core handy, you can get it from <http://jquery.com/download/>, and you can download jQuery UI directly from <http://jqueryui.com/>.
15+
16+
### Directory Structure
17+
18+
Now that we have the files we need, we have to discuss where to place them. For this tutorial, we'll build a small application that uses the following directory structure.
19+
20+
<pre>
21+
├── index.html
22+
├── js
23+
│ ├── app.js
24+
│ ├── jquery-ui
25+
│ │ ├── accordion.js
26+
│ │ ├── autocomplete.js
27+
│ │ ├── button.js
28+
│ │ ├── core.js
29+
│ │ ├── datepicker.js
30+
│ │ ├── dialog.js
31+
│ │ └── ...
32+
│ ├── jquery.js
33+
│ └── require.js
34+
</pre>
35+
36+
As you can see, we're placing all JavaScript files in a `js` directory. `jquery.js` and `require.js` are direct children of `js`, and all of jQuery UI's files are within a `jquery-ui` directory. `app.js` will contain our application code.
37+
38+
With RequireJS you're free to use any directory structure you'd like, but with alternative structures you'll have to [change some configuration](http://requirejs.org/docs/api.html#config) so RequireJS knows how to find your dependencies.
39+
40+
### Loading the Application
41+
42+
Now that we have the files in place, let's use them. Here are the contents of our app's `index.html` file.
43+
44+
```
45+
<!doctype html>
46+
<html lang="en">
47+
<head>
48+
...
49+
</head>
50+
<body>
51+
52+
<script src="js/require.js" data-main="js/app"></script>
53+
54+
</body>
55+
</html>
56+
```
57+
58+
`require.js` is loaded in a `<script>` tag, which [by convention](http://requirejs.org/docs/start.html) asynchronously loads and executes the file specified in the `data-main` attribute - in this case `js/app.js`. If you put a `console.log()` statement in `app.js`, you can verify that it loads appropriately.
59+
60+
```
61+
/* app.js */
62+
console.log( "loaded" );
63+
```
64+
65+
Our boilerplate is now in place. Next, we have to load jQuery and jQuery UI.
66+
67+
### Requiring jQuery and jQuery UI
68+
69+
The `require()` function is AMD's mechanism for specifying and loading dependencies; therefore, we can add one to our `app.js` file to load the necessary files. The following loads jQuery UI's autocomplete widget.
70+
71+
```
72+
require([ "jquery-ui/autocomplete" ], function( autocomplete ) {
73+
...
74+
});
75+
```
76+
77+
When this code executes, RequireJS asynchronously loads `jquery-ui/autocomplete.js` as well as its dependencies: jQuery core (`jquery.js`), jQuery UI core (`jquery-ui/core.js`), the widget factory (`jquery-ui/widget.js`), the position utility (`jquery-ui/position.js`), and the menu widget (`jquery-ui/menu.js`).
78+
79+
When all dependencies are resolved and loaded, RequireJS invokes the callback function.
80+
81+
### Using jQuery UI's Files
82+
83+
All widgets built with the widget factory expose their constructor function when required with AMD; therefore we can use them to instantiate widgets on elements. The following creates a new `<input>`, initializes an autocomplete widget on it, then appends it to the `<body>`.
84+
85+
```
86+
require([ "jquery-ui/autocomplete" ], function( autocomplete ) {
87+
autocomplete({ source: [ "One", "Two", "Three" ] }, "<input>" )
88+
.element
89+
.appendTo( "body" );
90+
});
91+
```
92+
93+
Each widget's constructor function takes two arguments: the widget's options, and the element to initialize the widget on. Each widget has a default element that is used if no element is provided, which is stored at `$.namespace.widgetName.prototype.defaultElement`. Because `$.ui.autocomplete.prototype.defaultElement` is `<input>`, we can omit the second argument in our autocomplete example.
94+
95+
```
96+
require([ "jquery-ui/autocomplete" ], function( autocomplete ) {
97+
autocomplete({ source: [ "One", "Two", "Three" ] })
98+
.element
99+
.appendTo( "body" );
100+
});
101+
```
102+
103+
Even though we're loading jQuery UI's files with AMD, the files' plugins are still added to the global `jQuery` and `$` objects; therefore you can alternatively use the plugins to instantiate widgets. The following also creates the same autocomplete.
104+
105+
```
106+
require([ "jquery", "jquery-ui/autocomplete" ], function( $ ) {
107+
$( "<input>" )
108+
.autocomplete({ source: [ "One", "Two", "Three" ]})
109+
.appendTo( "body" );
110+
});
111+
```
112+
113+
### Datepicker
114+
115+
Since jQuery UI's datepicker widget is the only jQuery UI widget not built with the widget factory, it does not return a constructor function when required with AMD. Because of this, it's best to stick with datepicker's plugin to instantiate datepicker instances. The following requires datepicker, then uses its plugin to instantiate a datepicker instance on a newly created `<input>`.
116+
117+
```
118+
require([ "jquery", "jquery-ui/datepicker" ], function( $ ) {
119+
$( "<input>" )
120+
.appendTo( "body" )
121+
.datepicker();
122+
});
123+
```

0 commit comments

Comments
 (0)