index.mustache revision 798013595916eab2771d53c9c08bb9c970f1b671
<div class="intro">
<p>The Get Utility provides a mechanism for attaching script and CSS resources
— including cross-domain resources — to the DOM after the page has
loaded.</p>
<p>Common use cases for the Get Utility include:</p>
<ul>
<li>
<p><strong>Cross-site data retrieval:</strong> Because XMLHttpRequest and the
<a href="../io/index.html">YUI IO Utility</a> (which uses
XMLHttpRequest) adhere to a strict <a
href="http://en.wikipedia.org/wiki/Same_origin_policy">same-origin
policy</a>, the retrieval of third-party data via XHR requires a server-side
proxy.</p>
<p>When you control or absolutely trust a cross-domain source, you can
eliminate the server-side proxy by loading a script file directly from the
external domain. That script file, which would typically contain
JSON-formatted data, is executed immediately upon load.</p>
<p>That said, it's crucial to
understand that if there is malicious code present in the loaded script there
is no safe way to protect your users from that malicious code; the
browser will execute the code with full privileges. <strong>Never expose
your users to JavaScript whose source is not absolutely
trustworthy.</strong>.</p>
</li>
<li>
<p><strong>Progressive loading of functionality:</strong> In rich web
applications, it's often useful to load some script and CSS resources only
when they become necessary (based on user action). The Get Utility provides
a flexible mechanism for bringing additional resources on-demand.</p>
<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>
</li>
</ul>
</div>
{{>getting-started}}
<h2>Using the Get Utility</h2>
<p>With the Get Utility present, you can make use of it to fetch JavaScript files using `Y.Get.script()`, and CSS files using `Y.Get.css()`. The `script()` and `css()` methods each take the following arguments:</p>
<dl>
<dt>urls (String|String[])</dt>
<dd>A string or an array of strings designating the URL(s) you wish to load into the page.</dd>
<dt>options (Object)</dt>
<dd>An optional object containing configuration information for the transaction; see the [[#Configuring a Transaction]] section below for the full list of configuraton options you can include here.</dd>
</dl>
<p>A sample request for a file might look like this:</p>
```
onSuccess: function () {
Y.log('file loaded');
}
});
```
<p>If you want to hold onto a transaction object for the request, assign the return value to a variable:</p>
```
var transaction = Y.Get.script('http://example.com/file.js', {
onSuccess: function () {
Y.log('file loaded');
}
});
```
<p>`transaction` will be an object with a single property, `tId`, which is a unique identifier of the transaction following the pattern "q0", "q1", "q2", etc.</p>
<p>It's only necessary to store the transaction object if you want to abort the request later.</p>
<h3>Configuring a Transaction</h3>
<p>The Get Utility is configured via the second argument to the `script()` or `css()` methods. This optional argument should be an object containing one or more of the following fields:</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`attributes`</td>
<td>Object</td>
<td>A hash of attributes to apply to the dynamically created nodes. You might use this to add `media="print"` to a CSS file, for example.</td>
</tr>
<tr>
<td>`autopurge`</td>
<td>Boolean</td>
<td>If `true`, script nodes will automatically be removed every 20 transactions (this number is globally configurable via the `Y.Get.PURGE_THRESH` 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:
`true` for script nodes, `false` for CSS nodes.</td>
</tr>
<tr>
<td>`context`</td>
<td>Object</td>
<td>The `this` object to use when executing callbacks. Default: the current YUI instance.</td>
</tr>
<tr>
<td>`data`</td>
<td>Any</td>
<td>Data to pass as an argument to `onSuccess` or `onFailure` callbacks. Default: `null`.</td>
</tr>
<tr>
<td>`onEnd`</td>
<td>Function</td>
<td>Callback function invoked when a transaction completes, no matter how the transaction ended.</td>
</tr>
<tr>
<td>`onFailure`</td>
<td>Function</td>
<td>Callback function invoked when an error is detected or `abort()` is called.</td>
</tr>
<tr>
<td>`onProgress`</td>
<td>Function</td>
<td>Callback function invoked after each node is inserted.</td>
</tr>
<tr>
<td>`onSuccess`</td>
<td>Function</th>
<td>Callback function invoked when the requested file(s) have loaded successfully.</td>
</tr>
<tr>
<td>`onTimeout`</td>
<td>Function</td>
<td>Callback function invoked if a timeout is detected.</td>
</tr>
<tr>
<td>`timeout`</td>
<td>Number</td>
<td>Number of milliseconds to wait for a file to finish loading before timing out.</td>
</tr>
<tr>
<td>`win`</td>
<td>Window</td>
<td>The window into which the loaded resource(s) should be inserted. Default: `Y.config.win`.</td>
</tr>
</tbody>
</table>
<h3>Making Use of Arguments Supplied to Your Callback</h3>
<p>As noted above, callback methods will have access to the `data` member supplied in the configuration object, assuming you provided one. But the `data` 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>
<table>
<thead>
<tr>
<th>Property</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`data`</td>
<td>Any</td>
<td>The `data` field you passed in the configuration object when the `script()` or `css()` method was called. Default: `null`.</td>
</tr>
<tr>
<td>`nodes`</td>
<td>Array</td>
<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>
</tr>
<tr>
<td>`purge`</td>
<td>Function</td>
<td>Calling the returned `purge()` 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>
</tr>
<tr>
<td>`tId`</td>
<td>String</td>
<td>The unique identifier for this transaction. This string is available as the `tId` member of the object returned to you upon calling the `script()` or `css()` method.</td>
</tr>
<tr>
<td>`win`</td>
<td>Window</td>
<td>The window object in which the nodes were created.</td>
</tr>
</tbody>
</table>
<p>All of these fields are accessible on the object passed to your `onSuccess` callback:</p>
```
onSuccess: function (e) {
// e contains all of the fields described in the table above.
e.purge(); // Removes the script node immediately after executing.
},
data: {
foo: 'bar',
baz: 'quux'
}
});
```
<h3>Using JSONP APIs</h3>
<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>
<p>The <a href="../jsonp/index.html">JSONP component</a> provides a simplified API for making JSONP requests using the Get Utility.</p>
<h3>How is the Get Utility Different From IO?</h3>
<p>The Get Utility inserts new script or CSS content into a window by creating new nodes and supplying a `src` or `href` attribute. Files inserted into the window in this manner are processed (and, in the case of scripts, executed) immediately upon load.</p>
<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>
<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>
<p>The basic version of the <a href="../io/index.html">IO Utility</a> (`io-base`) uses the `XMLHttpRequest` object to interact with the server. `XMLHttpRequest` 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>
<p>The IO Utility also supports cross domain requests through the `io-xdr` module. However, there are specific trust requirements as described in the documentation for the <a href="../io/index.html#xdr">IO Utility</a>. The `io-xdr` 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>
<h2>Known Issues</h2>
<ul>
<li><p>Gecko and WebKit-based browsers (Firefox, Chrome, and Safari) don't fire the DOM `load` event on a `<link>` node when a CSS file finishes loading. As a result, the Get Utility fires the `onSuccess` event immediately in these browsers. A workaround for this issue will be provided in a future release.</p></li>
</ul>