← Back to branch summary

~ubuntu-branches/ubuntu/raring/maas/raring-updates

« back to all changes in this revision

Viewing changes to src/maasserver/static/jslibs/yui/3.4.1/docs/get/index.html

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2012-07-03 17:42:37 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20120703174237-p8l0keuuznfg721k
Tags: 0.1+bzr709+dfsg-0ubuntu1
* New Upstream release
* debian/control:
  - Depends on python-celery, python-tempita, libjs-yui3-{full,min},
    libjs-raphael
* debian/maas.install:
  - Install apiclient, celeryconfig.py, maas-import-pxe-files, preseeds_v2.
  - Update to install various files from chroot, rather tha manually copy
    them from the source.
* debian/maas.links: symlink celeryconfig.py
* debian/maas.maas-celery.upstart: Add job.
* debian/rules:
  - Install celery upstart job.
  - Do not install jslibs as packages are now used.
  - Drop copying of maas_local_settings_sample.py as source now ships
    a maas_local_settings.py
* debian/patches:
  - 04-maas-http-fix.patch: Drop. Merged upstream.
  - 01-fix-database-settings.patch: Refreshed.
  - 99_enums_js.patch: Added until creation of enum.js / build process
    is fixed.
* debian/maas.postinst: Update bzr version to correctly handle upgrades.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/maasserver/static/jslibs/yui/3.4.1/docs/get/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>Get</title>
6
 
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
7
 
    <link rel="stylesheet" href="../assets/css/main.css">
8
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
9
 
    <script src="../../build/yui/yui-min.js"></script>
10
 
</head>
11
 
<body>
12
 
 
13
 
<div id="doc">
14
 
    <h1>Get</h1>
15
 
 
16
 
    
17
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
18
 
    
19
 
 
20
 
    <div class="yui3-g">
21
 
        <div id="main" class="yui3-u">
22
 
            <div class="content"><div class="intro">
23
 
<p>The Get Utility provides a mechanism for attaching script and CSS resources
24
 
&mdash; including cross-domain resources &mdash; to the DOM after the page has
25
 
loaded.</p>
26
 
 
27
 
<p>Common use cases for the Get Utility include:</p>
28
 
 
29
 
<ul>
30
 
  <li>
31
 
  <p><strong>Cross-site data retrieval:</strong> Because XMLHttpRequest and the
32
 
  <a href="../io/index.html">YUI IO Utility</a> (which uses
33
 
  XMLHttpRequest) adhere to a strict <a
34
 
  href="http://en.wikipedia.org/wiki/Same_origin_policy">same-origin
35
 
  policy</a>, the retrieval of third-party data via XHR requires a server-side
36
 
  proxy.</p>
37
 
 
38
 
  <p>When you control or absolutely trust a cross-domain source, you can
39
 
  eliminate the server-side proxy by loading a script file directly from the
40
 
  external domain. That script file, which would typically contain
41
 
  JSON-formatted data, is executed immediately upon load.</p>
42
 
 
43
 
  <p>That said, it's crucial to
44
 
  understand that if there is malicious code present in the loaded script there
45
 
  is no safe way to protect your users from that malicious code; the
46
 
  browser will execute the code with full privileges. <strong>Never expose
47
 
  your users to JavaScript whose source is not absolutely
48
 
  trustworthy.</strong>.</p>
49
 
  </li>
50
 
 
51
 
  <li>
52
 
  <p><strong>Progressive loading of functionality:</strong> In rich web
53
 
  applications, it's often useful to load some script and CSS resources only
54
 
  when they become necessary (based on user action). The Get Utility provides
55
 
  a flexible mechanism for bringing additional resources on-demand.</p>
56
 
 
57
 
  <p>If you're loading YUI resources specifically, you may want to use the <a href="../yui/index.html#loader">YUI Loader Utility</a>. Loader employs the Get Utility under the hood to bring in YUI components and has an intrinsic understanding of the YUI dependency tree.</p>
58
 
  </li>
59
 
</ul>
60
 
</div>
61
 
 
62
 
<h2 id="getting-started">Getting Started</h2>
63
 
 
64
 
<p>
65
 
To include the source files for Get and its dependencies, first load
66
 
the YUI seed file if you haven't already loaded it.
67
 
</p>
68
 
 
69
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
70
 
 
71
 
 
72
 
<p>
73
 
Next, create a new YUI instance for your application and populate it with the
74
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
75
 
YUI will automatically load any dependencies required by the modules you
76
 
specify.
77
 
</p>
78
 
 
79
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
80
 
YUI().use(&#x27;get&#x27;, function (Y) {
81
 
    &#x2F;&#x2F; Get is available and ready for use. Add implementation
82
 
    &#x2F;&#x2F; code here.
83
 
});</pre>
84
 
 
85
 
 
86
 
<p>
87
 
For more information on creating YUI instances and on the
88
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
89
 
documentation for the <a href="../yui/index.html">YUI Global object</a>.
90
 
</p>
91
 
 
92
 
 
93
 
<h2 id="using-the-get-utility">Using the Get Utility</h2>
94
 
 
95
 
<p>With the Get Utility present, you can make use of it to fetch JavaScript files using <code>Y.Get.script()</code>, and CSS files using <code>Y.Get.css()</code>.  The <code>script()</code> and <code>css()</code> methods each take the following arguments:</p>
96
 
 
97
 
<dl>
98
 
  <dt>urls (String|String[])</dt>
99
 
  <dd>A string or an array of strings designating the URL(s) you wish to load into the page.</dd>
100
 
 
101
 
  <dt>options (Object)</dt>
102
 
  <dd>An optional object containing configuration information for the transaction; see the <a href="#configuring-a-transaction">Configuring a Transaction</a> section below for the full list of configuraton options you can include here.</dd>
103
 
</dl>
104
 
 
105
 
<p>A sample request for a file might look like this:</p>
106
 
 
107
 
<pre class="code prettyprint">Y.Get.script(&#x27;http:&#x2F;&#x2F;example.com&#x2F;file.js&#x27;, {
108
 
  onSuccess: function () {
109
 
    Y.log(&#x27;file loaded&#x27;);
110
 
  }
111
 
});</pre>
112
 
 
113
 
 
114
 
<p>If you want to hold onto a transaction object for the request, assign the return value to a variable:</p>
115
 
 
116
 
<pre class="code prettyprint">var transaction = Y.Get.script(&#x27;http:&#x2F;&#x2F;example.com&#x2F;file.js&#x27;, {
117
 
  onSuccess: function () {
118
 
    Y.log(&#x27;file loaded&#x27;);
119
 
  }
120
 
});</pre>
121
 
 
122
 
 
123
 
<p><code>transaction</code> will be an object with a single property, <code>tId</code>, which is a unique identifier of the transaction following the pattern "q0", "q1", "q2", etc.</p>
124
 
 
125
 
<p>It's only necessary to store the transaction object if you want to abort the request later.</p>
126
 
 
127
 
<h3 id="configuring-a-transaction">Configuring a Transaction</h3>
128
 
 
129
 
<p>The Get Utility is configured via the second argument to the <code>script()</code> or <code>css()</code> methods.  This optional argument should be an object containing one or more of the following fields:</p>
130
 
 
131
 
<table>
132
 
  <thead>
133
 
    <tr>
134
 
      <th>Name</th>
135
 
      <th>Type</th>
136
 
      <th>Description</th>
137
 
    </tr>
138
 
  </thead>
139
 
 
140
 
  <tbody>
141
 
    <tr>
142
 
      <td><code>attributes</code></td>
143
 
      <td>Object</td>
144
 
      <td>A hash of attributes to apply to the dynamically created nodes.  You might use this to add <code>media=&quot;print&quot;</code> to a CSS file, for example.</td>
145
 
    </tr>
146
 
 
147
 
    <tr>
148
 
      <td><code>autopurge</code></td>
149
 
      <td>Boolean</td>
150
 
      <td>If <code>true</code>, script nodes will automatically be removed every 20 transactions (this number is globally configurable via the <code>Y.Get.PURGE_THRESH</code> property). Script nodes can be safely removed in most cases, as their contents (having executed) remain available. CSS nodes should not have this set to true as it will remove the CSS rules. Default:
151
 
      <code>true</code> for script nodes, <code>false</code> for CSS nodes.</td>
152
 
    </tr>
153
 
 
154
 
    <tr>
155
 
      <td><code>context</code></td>
156
 
      <td>Object</td>
157
 
      <td>The <code>this</code> object to use when executing callbacks. Default: the current YUI instance.</td>
158
 
    </tr>
159
 
 
160
 
    <tr>
161
 
      <td><code>data</code></td>
162
 
      <td>Any</td>
163
 
      <td>Data to pass as an argument to <code>onSuccess</code> or <code>onFailure</code> callbacks.  Default: <code>null</code>.</td>
164
 
    </tr>
165
 
 
166
 
    <tr>
167
 
      <td><code>onEnd</code></td>
168
 
      <td>Function</td>
169
 
      <td>Callback function invoked when a transaction completes, no matter how the transaction ended.</td>
170
 
    </tr>
171
 
 
172
 
    <tr>
173
 
      <td><code>onFailure</code></td>
174
 
      <td>Function</td>
175
 
      <td>Callback function invoked when an error is detected or <code>abort()</code> is called.</td>
176
 
    </tr>
177
 
 
178
 
    <tr>
179
 
      <td><code>onProgress</code></td>
180
 
      <td>Function</td>
181
 
      <td>Callback function invoked after each node is inserted.</td>
182
 
    </tr>
183
 
 
184
 
    <tr>
185
 
      <td><code>onSuccess</code></td>
186
 
      <td>Function</th>
187
 
      <td>Callback function invoked when the requested file(s) have loaded successfully.</td>
188
 
    </tr>
189
 
 
190
 
    <tr>
191
 
      <td><code>onTimeout</code></td>
192
 
      <td>Function</td>
193
 
      <td>Callback function invoked if a timeout is detected.</td>
194
 
    </tr>
195
 
 
196
 
    <tr>
197
 
      <td><code>timeout</code></td>
198
 
      <td>Number</td>
199
 
      <td>Number of milliseconds to wait for a file to finish loading before timing out.</td>
200
 
    </tr>
201
 
 
202
 
    <tr>
203
 
      <td><code>win</code></td>
204
 
      <td>Window</td>
205
 
      <td>The window into which the loaded resource(s) should be inserted.  Default: <code>Y.config.win</code>.</td>
206
 
    </tr>
207
 
  </tbody>
208
 
</table>
209
 
 
210
 
<h3 id="making-use-of-arguments-supplied-to-your-callback">Making Use of Arguments Supplied to Your Callback</h3>
211
 
 
212
 
<p>As noted above, callback methods will have access to the <code>data</code> member supplied in the configuration object, assuming you provided one.  But the <code>data</code> member is just one of several fields included in the object passed to a callback.  Here's a summary of the fields contained in that argument object:</p>
213
 
 
214
 
<table>
215
 
  <thead>
216
 
    <tr>
217
 
      <th>Property</th>
218
 
      <th>Type</th>
219
 
      <th>Description</th>
220
 
    </tr>
221
 
  </thead>
222
 
 
223
 
  <tbody>
224
 
    <tr>
225
 
      <td><code>data</code></td>
226
 
      <td>Any</td>
227
 
      <td>The <code>data</code> field you passed in the configuration object when the <code>script()</code> or <code>css()</code> method was called. Default: <code>null</code>.</td>
228
 
    </tr>
229
 
 
230
 
    <tr>
231
 
      <td><code>nodes</code></td>
232
 
      <td>Array</td>
233
 
      <td>An array containing references to DOM node(s) created in processing the transaction.  These will be script nodes for JavaScript and link nodes for CSS.</td>
234
 
    </tr>
235
 
 
236
 
    <tr>
237
 
      <td><code>purge</code></td>
238
 
      <td>Function</td>
239
 
      <td>Calling the returned <code>purge()</code> method will immediately remove the created nodes. This is safe and prudent for JavaScript nodes, which do not need to persist.  If CSS nodes are purged, the rules they contain are no longer available and the page will repaint accordingly.</td>
240
 
    </tr>
241
 
 
242
 
    <tr>
243
 
      <td><code>tId</code></td>
244
 
      <td>String</td>
245
 
      <td>The unique identifier for this transaction. This string is available as the <code>tId</code> member of the object returned to you upon calling the <code>script()</code> or <code>css()</code> method.</td>
246
 
    </tr>
247
 
 
248
 
    <tr>
249
 
      <td><code>win</code></td>
250
 
      <td>Window</td>
251
 
      <td>The window object in which the nodes were created.</td>
252
 
    </tr>
253
 
  </tbody>
254
 
</table>
255
 
 
256
 
<p>All of these fields are accessible on the object passed to your <code>onSuccess</code> callback:</p>
257
 
<pre class="code prettyprint">Y.Get.script(&#x27;http:&#x2F;&#x2F;json.org&#x2F;json.js&#x27;, {
258
 
  onSuccess: function (e) {
259
 
    &#x2F;&#x2F; e contains all of the fields described in the table above.
260
 
 
261
 
    e.purge(); &#x2F;&#x2F; Removes the script node immediately after executing.
262
 
    Y.log(e.data); &#x2F;&#x2F; Logs the data passed in the configuration object.
263
 
  },
264
 
 
265
 
  data: {
266
 
    foo: &#x27;bar&#x27;,
267
 
    baz: &#x27;quux&#x27;
268
 
  }
269
 
});</pre>
270
 
 
271
 
 
272
 
<h3 id="using-jsonp-apis">Using JSONP APIs</h3>
273
 
 
274
 
<p>A common way to consume a web service that returns JSON data is to use a convention called JSONP. The way it works is that the consumer of the web service supplies the name of a function to execute on the client. The web service response is expected to return a JavaScript response that executes this function and provides a JSON payload as a parameter to the function.</p>
275
 
 
276
 
<p>The <a href="../jsonp/index.html">JSONP component</a> provides a simplified API for making JSONP requests using the Get Utility.</p>
277
 
 
278
 
<h3 id="how-is-the-get-utility-different-from-io">How is the Get Utility Different From IO?</h3>
279
 
 
280
 
<p>The Get Utility inserts new script or CSS content into a window by creating new nodes and supplying a <code>src</code> or <code>href</code> attribute.  Files inserted into the window in this manner are processed (and, in the case of scripts, executed) immediately upon load.</p>
281
 
 
282
 
<p>While query parameters can be passed in the URL, no data can be sent to the server via HTTP POST using this method; the Get Utility can only make HTTP GET requests.</p>
283
 
 
284
 
<p>As noted above, the Get Utility is ideal for loading your own scripts or CSS progressively (lazy loading) or for retrieving cross-domain JSON data from sources in which you have total trust.</p>
285
 
 
286
 
<p>The basic version of the <a href="../io/index.html">IO Utility</a> (<code>io-base</code>) uses the <code>XMLHttpRequest</code> object to interact with the server. <code>XMLHttpRequest</code> is limited by a strict <a href="http://en.wikipedia.org/wiki/Same_origin_policy">same origin policy</a>, but it supports a greater range of HTTP methods (including POST).</p> As a result, IO is a more appropriate choice for rich two-way communication between browser and server and gives you more control over data before it's processed within the browser.</p>
287
 
 
288
 
<p>The IO Utility also supports cross domain requests through the <code>io-xdr</code> module.  However, there are specific trust requirements as described in the documentation for the <a href="../io/index.html#xdr">IO Utility</a>. The <code>io-xdr</code> submodule may be a better choice than the Get Utility for cross-domain communication if the service you are accessing can be configured to trust the server that is hosting your application.</p>
289
 
 
290
 
<h2 id="known-issues">Known Issues</h2>
291
 
 
292
 
<ul>
293
 
  <li><p>Gecko and WebKit-based browsers (Firefox, Chrome, and Safari) don't fire the DOM <code>load</code> event on a <code>&lt;link&gt;</code> node when a CSS file finishes loading. As a result, the Get Utility fires the <code>onSuccess</code> event immediately in these browsers. A workaround for this issue will be provided in a future release.</p></li>
294
 
</ul>
295
 
</div>
296
 
        </div>
297
 
 
298
 
        <div id="sidebar" class="yui3-u">
299
 
            
300
 
                <div id="toc" class="sidebox">
301
 
                    <div class="hd">
302
 
                        <h2 class="no-toc">Table of Contents</h2>
303
 
                    </div>
304
 
 
305
 
                    <div class="bd">
306
 
                        <ul class="toc">
307
 
<li>
308
 
<a href="#getting-started">Getting Started</a>
309
 
</li>
310
 
<li>
311
 
<a href="#using-the-get-utility">Using the Get Utility</a>
312
 
<ul class="toc">
313
 
<li>
314
 
<a href="#configuring-a-transaction">Configuring a Transaction</a>
315
 
</li>
316
 
<li>
317
 
<a href="#making-use-of-arguments-supplied-to-your-callback">Making Use of Arguments Supplied to Your Callback</a>
318
 
</li>
319
 
<li>
320
 
<a href="#using-jsonp-apis">Using JSONP APIs</a>
321
 
</li>
322
 
<li>
323
 
<a href="#how-is-the-get-utility-different-from-io">How is the Get Utility Different From IO?</a>
324
 
</li>
325
 
</ul>
326
 
</li>
327
 
<li>
328
 
<a href="#known-issues">Known Issues</a>
329
 
</li>
330
 
</ul>
331
 
                    </div>
332
 
                </div>
333
 
            
334
 
 
335
 
            
336
 
 
337
 
            
338
 
        </div>
339
 
    </div>
340
 
</div>
341
 
 
342
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
343
 
<script>prettyPrint();</script>
344
 
 
345
 
</body>
346
 
</html>