~smagoun/whoopsie/whoopsie-lp1017637

The Get Utility makes it easy to dynamically load JavaScript and CSS resources and be notified when they've finished loading. Get is used internally by the <a href="../yui/index.html">YUI Loader</a> to load YUI modules and by the <a href="../jsonp/index.html">JSONP module</a> to make JSONP requests. The Get Utility is transactional in nature and is capable of loading multiple resources either serially or in parallel.

</p>

</div>

<h2 id="getting-started">Getting Started</h2>

<p>

To include the source files for Get and its dependencies, first load

the YUI seed file if you haven't already loaded it.

</p>

<p>

Next, create a new YUI instance for your application and populate it with the

modules you need by specifying them as arguments to the <code>YUI().use()</code> method.

YUI will automatically load any dependencies required by the modules you

specify.

</p>

// Create a new YUI instance and populate it with the required modules.

YUI().use('get', function (Y) {

// Get is available and ready for use. Add implementation

// code here.

});

</script></pre>

<p>

For more information on creating YUI instances and on the

<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the

documentation for the <a href="../yui/index.html">YUI Global Object</a>.

</p>

<h2 id="using-the-get-utility">Using the Get Utility</h2>

<h3 id="loading-css-and-javascript">Loading CSS and JavaScript</h3>

<p>

To load a JavaScript resource, pass a URL (both relative and absolute URLs are fine) and a callback function to the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#method_js"><code>Y.Get.js()</code></a> method. Get will execute the callback function when the resource has finished loading. If an error occurs, the first argument passed to the callback will be an array of error objects.

</p>

<p>

<code>Y.Get</code> is a static class, so you don't need to instantiate it before calling its methods.

</p>

<pre class="code prettyprint">// Load a single JavaScript resource.

Y.Get.js('http://example.com/file.js', function (err) {

if (err) {

Y.log('Error loading JS: ' + err[0].error, 'error');

return;

}

Y.log('file.js loaded successfully!');

});</pre>

<p>

Loading CSS works the same way as JS, but you call the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#method_css"><code>css()</code></a> method instead of <code>js()</code>:

</p>

<pre class="code prettyprint">// Load a single CSS resource.

Y.Get.css('file.css', function (err) {

if (err) {

Y.log('Error loading CSS: ' + err[0].error, 'error');

return;

}

100

101

Y.log('file.css loaded successfully!');

102

});</pre>

103

104

105

106

107

<p>

108

If you want to load more than one resource in a single transaction and be notified when all of them have finished loading, you may pass an array of URLs to <code>css()</code> or <code>js()</code>.

109

</p>

110

111

<pre class="code prettyprint">// Load multiple JS resources and execute the callback after all have finished

112

// loading.

113

Y.Get.js(['one.js', 'two.js', 'http://example.com/three.js'], function (err) {

114

if (err) {

115

Y.Array.each(err, function (error) {

116

Y.log('Error loading JS: ' + error.error, 'error');

117

});

118

return;

119

}

120

121

Y.log('All JS files loaded successfully!');

122

});</pre>

123

124

125

<p>

126

You can even mix and match both JavaScript and CSS files in the same transaction by calling <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#method_load"><code>Y.Get.load()</code></a>, which will guess the type of each URL by looking at the file extension.

127

</p>

128

129

<pre class="code prettyprint">// Load both CSS and JS in a single transaction and execute the callback after

130

// all resources have finished loading.

131

Y.Get.load(['widget.js', 'widget.css'], function (err) {

132

if (err) {

133

Y.Array.each(err, function (error) {

134

Y.log('Error loading file: ' + error.error, 'error');

135

});

136

return;

137

}

138

139

Y.log('All CSS and JS files loaded successfully!');

140

});</pre>

141

142

143

<p>

144

This should be enough to get you started using the Get Utility, but keep reading to learn about Get's more advanced functionality.

145

</p>

146

147

<h3 id="serial-vs-parallel-loading">Serial vs. Parallel Loading</h3>

148

149

<p>

150

The <code>css()</code>, <code>js()</code>, and <code>load()</code> methods execute <em>asynchronously</em>, which means that they return instantly rather than blocking subsequent code until the operation finishes. This is why it's necessary to provide a callback function if you want to be notified when loading is complete.

151

</p>

152

153

<p>

154

It's also important to understand when resources will be loaded <em>serially</em> (one after another) versus in <em>parallel</em> (all at the same time). Loading resources in parallel is always faster than loading them serially, but can sometimes be dangerous because resources won't always finish loading in the same order they were requested.

155

</p>

156

157

<p>

158

The Get Utility always does the safest thing by default:

159

</p>

160

161

<ul>

162

<li>

163

<p>

164

Transactions are processed serially. This means that only one transaction is in progress at a time, and it must finish before the next transaction will begin. Each call to <code>css()</code>, <code>js()</code>, or <code>load()</code> creates a transaction, although a single transaction may involve multiple requests.

165

</p>

166

</li>

167

168

<li>

169

<p>

170

Within a transaction, CSS resources are always loaded in parallel. This is because, with CSS, load order has no effect on the end result, since style precedence is determined by the order of <code><link></code> nodes in the DOM.

171

</p>

172

</li>

173

174

<li>

175

<p>

176

Within a transaction, JS resources are loaded in parallel in Firefox and Opera, because these browsers are capable of preserving script execution order regardless of load order. In all other browsers, JS resources are loaded serially unless the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#property_options"><code>async</code> option</a> is set to <code>true</code>.

177

</p>

178

</li>

179

180

<li>

181

<p>

182

When the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#property_options"><code>async</code> option</a> is set to <code>true</code>, JS resources are loaded in parallel regardless of the browser, and execution order is not guaranteed.

183

</p>

184

</li>

185

186

</ul>

187

188

<h3 id="working-with-transactions">Working With Transactions</h3>

189

190

<p>

191

A transaction object is an instance of the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.Transaction.html"><code>Y.Get.Transaction</code></a> class. It contains methods and properties that allow you to inspect and manipulate a transaction, which encompasses one or more CSS or JS requests and a set of config options associated with those requests.

192

</p>

193

194

<p>

195

The <code>css()</code>, <code>js()</code>, and <code>load()</code> methods each return a transaction object. This same transaction object is also passed as the second argument to the completion callback.

196

</p>

197

198

<pre class="code prettyprint">// Load a script and assign the transaction object to a var.

199

var tx = Y.Get.js('hello.js', function (err, tx) {

200

// The transaction object is also passed as the second arg to completion

201

// callbacks.

202

});</pre>

203

204

205

<p>

206

It's not necessary to hold onto a transaction object unless you want to be able to abort a request before it finishes or manually purge <code><script></code> or <code><link></code> nodes created by the transaction.

207

</p>

208

209

<h4 id="aborting-transactions">Aborting Transactions</h4>

210

211

<p>

212

You can abort a transaction in progress by calling the transaction's <a href="http://yuilibrary.com/yui/docs/api/classes/Get.Transaction.html#method_abort"><code>abort()</code></a> method.

213

</p>

214

215

<pre class="code prettyprint">var tx = Y.Get.js(['one.js', 'two.js'], function (err) {

216

if (err) {

217

Y.log(err[0].error, 'error');

218

}

219

});

220

221

tx.abort(); // Results in the log message "Aborted."</pre>

222

223

224

<p>

225

Pass a string to the <code>abort()</code> method to customize the error message passed to callbacks.

226

</p>

227

228

<p>

229

Note that since browsers don't expose a safe API for aborting in-progress JS and CSS requests, the Get Utility can't actually stop requests that have already started. Calling <code>abort()</code> will immediately cause callbacks to execute and will cancel any pending requests within the transaction that haven't yet begun, but if there are any requests already in progress, the browser will finish them silently.

230

</p>

231

232

<h4 id="purging-inserted-nodes">Purging Inserted Nodes</h4>

233

234

<p>

235

If you plan to load lots of JavaScript resources—for example, maybe your app makes frequent JSONP requests to a remote API—you'll end up creating lots of <code><script></code> nodes behind the scenes. Each node on the page uses a small amount of memory, and since the actual script nodes aren't usually needed once the JS has been executed, it's a good idea to clean them up occasionally by purging them.

236

</p>

237

238

<p>

239

By default, the Get Utility will automatically purge script nodes after every 20 requests. This number is relatively high since purging incurs a slight processing cost. If you want to manually purge the nodes inserted by a transaction instead of waiting for the automatic purge, you can do so by calling the transaction's <code>purge()</code> method.

240

</p>

241

242

<pre class="code prettyprint">Y.Get.js(['one.js', 'two.js'], function (err, tx) {

243

// Purge all the DOM nodes created by this transaction.

244

tx.purge();

245

});</pre>

246

247

248

<p>

249

You can customize the automatic purge threshold by setting the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#property_options"><code>purgethreshold</code></a> config option, and you can disable automatic purging completely by setting the <a href="http://yuilibrary.com/yui/docs/api/classes/Get.html#property_options"><code>autopurge</code></a> option to <code>false</code>.

250

</p>

251

252

<p>

253

Note that the Get Utility will not automatically purge CSS <code><link></code> nodes by default, since removing a <code><link></code> node from the DOM also removes any styles it applied. Calling <code>purge()</code> manually on a transaction that included CSS requests will purge the <code><link></code> nodes and remove styles, so be careful.

254

</p>

255

256

<h4 id="manually-executing-transactions">Manually Executing Transactions</h4>

257

258

<p>

259

As described in <a href="#serial-vs-parallel-loading">Serial vs. Parallel Loading</a>, the Get Utility executes transactions serially (one after the other) to ensure that they don't conflict with one another. If for some reason you want multiple transactions to execute in parallel and you're willing to take your life into your own hands, you can manually start a transaction by calling its <code>execute()</code> method.

260

</p>

261

262

<pre class="code prettyprint">var txOne = Y.Get.js(['foo.js', 'bar.js']),

263

txTwo = Y.Get.js(['baz.js', 'quux.js']);

264

265

// txOne is started automatically, and we can manually start txTwo in parallel.

266

txTwo.execute();</pre>

267

268

269

<p>

270

Calling <code>execute()</code> on a transaction that's already in progress or has already finished is safe and won't restart the transaction.

271

</p>

272

273

<p>

274

An additional feature of <code>execute()</code> is that it accepts a callback function, which works just like the callback function passed to <code>css()</code>, <code>js()</code>, or <code>load()</code>. In fact, you can even call <code>execute()</code> multiple times to register multiple callback functions, and they'll be queued and executed in order once the transaction finishes. If you call <code>execute()</code> with a callback function on a transaction that's already finished, the callback will be executed immediately.

275

</p>

276

277

<h3 id="configuration-options">Configuration Options</h3>

278

279

<p>

280

The Get Utility supports the following config options. All options may be set at the transaction level. Some options may also be set at the request level (i.e., for a specific URL within a transaction). Options that may be set at the request level are indicated by a "Y" in the "Request?" column.

281

</p>

282

283

<table>

284

<thead>

285

<tr>

286

287

<th>Default</th>

288

<th>Request?</th>

289

<th>Description</th>

290

</tr>

291

</thead>

292

293

<tbody>

294

<tr>

295

<td><code>async</code></td>

296

<td><code>false</code></td>

297

298

<td>

299

Whether or not to load scripts asynchronously, meaning they're requested in parallel and execution order is not guaranteed. Has no effect on CSS, since CSS is always loaded asynchronously.

300

</td>

301

</tr>

302

303

<tr>

304

<td><code>attributes</code></td>

305

<td>

306

307

{

308

charset: "utf-8",

309

id : <em>auto</em>

310

}

311

</pre>

312

</td>

313

314

<td>

315

HTML attribute name/value pairs that should be added to inserted nodes. By default, the <code>charset</code> attribute will be set to "utf-8" and nodes will be given an auto-generated <code>id</code> attribute, but you can override these with your own values if desired.

316

</td>

317

</tr>

318

319

<tr>

320

<td><code>autopurge</code></td>

321

<td>

322

323

<code>false</code> for CSS

324

</td>

325

326

<td>

327

Whether or not to automatically purge inserted nodes after the purge threshold is reached. This is <code>true</code> by default for JavaScript, but <code>false</code> for CSS since purging a CSS node will also remove any styling applied by the referenced file.

328

</td>

329

</tr>

330

331

<tr>

332

<td><code>context</code></td>

333

<td><em>transaction object</em></td>

334

335

<td>

336

<code>this</code> object to use when calling callback functions. Defaults to the transaction object.

337

</td>

338

</tr>

339

340

<tr>

341

342

<td><code>undefined</code></td>

343

344

<td>

345

Arbitrary data object to pass to "on*" callbacks.

346

</td>

347

</tr>

348

349

<tr>

350

351

<td><code>Y.config.doc</code></td>

352

353

<td>

354

Document into which nodes should be inserted. By default, the current document is used.

355

</td>

356

</tr>

357

358

<tr>

359

<td><code>insertBefore</code></td>

360

361

362

<td>

363

HTML element or id string of an element before which all generated nodes should be inserted. If not specified, Get will automatically determine the best place to insert nodes for maximum compatibility.

364

</td>

365

</tr>

366

367

<tr>

368

<td><code>onEnd</code></td>

369

<td><code>undefined</code></td>

370

371

<td>

372

Callback to execute after a transaction is complete, regardless of whether it succeeded or failed.

373

</td>

374

</tr>

375

376

<tr>

377

<td><code>onFailure</code></td>

378

<td><code>undefined</code></td>

379

380

<td>

381

Callback to execute after a transaction fails, times out, or is aborted.

382

</td>

383

</tr>

384

385

<tr>

386

<td><code>onProgress</code></td>

387

<td><code>undefined</code></td>

388

389

<td>

390

Callback to execute after each individual request in a transaction either succeeds or fails.

391

</td>

392

</tr>

393

394

<tr>

395

<td><code>onSuccess</code></td>

396

<td><code>undefined</code></td>

397

398

<td>

399

Callback to execute after a transaction completes successfully with no errors. Note that in browsers that don't support the <code>error</code> event on CSS <code><link></code> nodes, a failed CSS request may still be reported as a success because in these browsers it can be difficult or impossible to distinguish between success and failure for CSS resources.

400

</td>

401

</tr>

402

403

<tr>

404

<td><code>onTimeout</code></td>

405

<td><code>undefined</code></td>

406

407

<td>

408

Callback to execute after a transaction times out.

409

</td>

410

</tr>

411

412

<tr>

413

<td><code>pollInterval</code></td>

414

415

416

<td>

417

Polling interval (in milliseconds) for detecting CSS load completion in browsers that don't support the <code>load</code> event on <code><link></code> nodes. This isn't used for JavaScript.

418

</td>

419

</tr>

420

421

<tr>

422

<td><code>purgethreshold</code></td>

423

424

425

<td>

426

Number of nodes to insert before triggering an automatic purge when <code>autopurge</code> is <code>true</code>.

427

</td>

428

</tr>

429

430

<tr>

431

<td><code>timeout</code></td>

432

<td><code>undefined</code></td>

433

434

<td>

435

Number of milliseconds to wait before aborting a transaction. When a timeout occurs, the <code>onTimeout</code> callback is called, followed by <code>onFailure</code> and finally <code>onEnd</code>. By default, there is no timeout.

436

</td>

437

</tr>

438

439

<tr>

440

441

442

443

<td>

444

Resource type ("css" or "js"). This option is set automatically by the <code>css()</code> and <code>js()</code> functions and will be ignored there, but may be useful when using the <code>load()</code> function. If not specified, the type will be inferred from the URL, defaulting to "js" if the URL doesn't contain a recognizable file extension.

445

</td>

446

</tr>

447

</tbody>

448

</table>

449

450

<h4 id="using-transaction-specific-options">Using Transaction-Specific Options</h4>

451

452

<p>

453

Transaction-specific configuration options apply only to a single transaction. To specify one or more transaction-specific options, just pass a config object as the second argument to <code>css()</code>, <code>js()</code> or <code>load()</code>.

454

</p>

455

456

<pre class="code prettyprint">Y.Get.js('intl-jp.js', {

457

attributes: {

458

'charset': 'shift-jis', // custom charset attribute for inserted DOM nodes

459

'class' : 'intl' // custom 'class' attribute for inserted DOM nodes

460

461

462

timeout: 10000 // timeout after 10 seconds

463

}, function (err) {

464

// ...

465

});</pre>

466

467

468

<p>

469

You may have noticed that in the example above, the options object is the second argument and the callback is the third argument, whereas previous examples pass a callback as the second argument and no options object. The <code>css()</code>, <code>js()</code>, and <code>load()</code> methods support both signatures for convenience. The only required argument is the first one.

470

</p>

471

472

<h4 id="using-request-specific-options">Using Request-Specific Options</h4>

473

474

<p>

475

Certain config options (see <a href="#configuration-options">the table above</a> for a complete list) can be specified on a per-request basis, meaning they'll apply only to a single URL.

476

</p>

477

478

<p>

479

To specify request-specific options, pass an object or array of objects to <code>css()</code>, <code>js()</code>, or <code>load()</code> instead of passing a string or array of strings. Each object must have a <code>url</code> property specifying the URL to load, and may also contain request-specific options. You can freely mix and match string URLs and objects if desired.

480

</p>

481

482

<pre class="code prettyprint">Y.Get.js([

483

{url: 'thing-one.js', attributes: {id: 'thing-one'}},

484

{url: 'thing-two.js', attributes: {id: 'thing-two'}, async: true}

485

], function (err) {

486

// ...

487

});</pre>

488

489

490

<p>

491

When both request-specific options and transaction-specific options are specified, the options will be merged per request, with request-specific options taking precedence when there are collisions.

492

</p>

493

494

<h3 id="granular-callbacks">Granular Callbacks</h3>

495

496

<p>

497

While the callback parameter of the <code>css()</code>, <code>js()</code>, and <code>load()</code> methods makes it easy to define a combined success/failure callback for a transaction, there are times when more granularity is needed. Perhaps you want to use separate callbacks for success and failure, or perhaps you want to be notified of the progress of each request in a transaction rather than waiting until the entire transaction is complete. That's where granular callbacks come in.

498

</p>

499

500

<p>

501

The Get Utility supports five different granular callbacks per transaction: <code>onEnd</code>, <code>onFailure</code>, <code>onProgress</code>, <code>onSuccess</code>, and <code>onTimeout</code>. See <a href="#configuration-options">Configuration Options</a> for descriptions of when each callback is called.

502

</p>

503

504

<p>

505

Granular callbacks receive the transaction object as an argument.

506

</p>

507

508

<pre class="code prettyprint">Y.Get.js('kittens.js', {

509

onFailure: function () {

510

Y.log('Failure!');

511

512

513

onSuccess: function () {

514

Y.log('Success!');

515

}

516

});</pre>

517

518

519

<p>

520

You can pass arbitrary data to your callbacks by setting the <code>data</code> option on the transaction.

521

</p>

522

523

<pre class="code prettyprint">Y.Get.js(['one.js', 'two.js', 'three.js'], {

524

data: {progress: 0},

525

526

onProgress: function (tx) {

527

tx.data.progress += 1;

528

Y.log('Loaded ' + tx.data.progress + ' file(s)');

529

}

530

});</pre>

531

532

533

<p>

534

By default, the <code>this</code> object inside a granular callback refers to the transaction object, but you can customize it by setting the <code>context</code> option.

535

</p>

536

537

<pre class="code prettyprint">Y.Get.js('puppies.js', {

538

context: {bark: 'ruff ruff!'},

539

540

onSuccess: function () {

541

Y.log(this.bark);

542

}

543

});</pre>

544

545

546

<h2 id="using-jsonp-apis">Using JSONP APIs</h2>

547

548

<p>

549

A common way to consume a web service that returns JSON data is to use a convention called <a href="http://en.wikipedia.org/wiki/JSONP">JSONP</a>. The remote service returns data wrapped in a JavaScript function call (the name of which is supplied in the request), so retrieving the data is simple as loading and executing the JSONP URL as if it were a script. When the returned JS executes, the data is passed to the named function.

550

</p>

551

552

<p>

553

The Get Utility can be used to consume JSONP APIs by loading JSONP URLs as scripts. However, the <a href="../jsonp/index.html">JSONP Utility</a> (which uses Get under the hood) provides a simplified API for making JSONP requests, so we recommend using that component for JSONP rather than using Get directly.

554

</p>

555

556

<h2 id="how-is-the-get-utility-different-from-io">How is the Get Utility Different From IO?</h2>

557

558

<p>

559

In simple terms, the Get Utility loads new JS or CSS resources into a document by creating new DOM nodes and setting the <code>src</code> or <code>href</code> attribute. Files loaded in this manner are processed (and, in the case of scripts, executed) as soon as they load.

560

</p>

561

562

<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. This makes the Get Utility ideal for loading scripts or CSS progressively (lazy loading) or for retrieving cross-domain JSON data from trusted sources, but somewhat less ideal for more sophisticated communication.

563

</p>

564

565

<p>

566

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). 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.

567

</p>

568

569

<p>

570

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.

571

</p>

572

</div>

573

</div>

574

</div>

575

576

577

578

579

580

581

<h2 class="no-toc">Table of Contents</h2>

582

</div>

583

584

585

586

<li>

587

<a href="#getting-started">Getting Started</a>

588

</li>

589

<li>

590

<a href="#using-the-get-utility">Using the Get Utility</a>

591

592

<li>

593

<a href="#loading-css-and-javascript">Loading CSS and JavaScript</a>

594

595

<li>

596

597

</li>

598

<li>

599

600

</li>

601

<li>

602

603

</li>

604

</ul>

605

</li>

606

<li>

607

<a href="#serial-vs-parallel-loading">Serial vs. Parallel Loading</a>

608

</li>

609

<li>

610

<a href="#working-with-transactions">Working With Transactions</a>

611

612

<li>

613

<a href="#aborting-transactions">Aborting Transactions</a>

614

</li>

615

<li>

616

<a href="#purging-inserted-nodes">Purging Inserted Nodes</a>

617

</li>

618

<li>

619

<a href="#manually-executing-transactions">Manually Executing Transactions</a>

620

</li>

621

</ul>

622

</li>

623

<li>

624

<a href="#configuration-options">Configuration Options</a>

625

626

<li>

627

<a href="#using-transaction-specific-options">Using Transaction-Specific Options</a>

628

</li>

629

<li>

630

<a href="#using-request-specific-options">Using Request-Specific Options</a>

631

</li>

632

</ul>

633

</li>

634

<li>

635

<a href="#granular-callbacks">Granular Callbacks</a>

636

</li>

637

</ul>

638

</li>

639

<li>

640

<a href="#using-jsonp-apis">Using JSONP APIs</a>

641

</li>

642

<li>

643

<a href="#how-is-the-get-utility-different-from-io">How is the Get Utility Different From IO?</a>

644

</li>

645

</ul>

646

</div>

647

</div>

648

649

650

651

652

653

</div>

654

</div>

655

</div>

656

</div>

657

658

659

660

661

</body>

662

</html>

Older »