~bac/juju-gui/trunkcopy

The <code>io()</code> method on the YUI instance is the static method for making an HTTP request. This method accepts two arguments: the uri and the configuration object.

</p>

<ul>

<li><strong>uri:</strong> This parameter specifies the URI for the transaction</li>

<li><strong>configuration:</strong> This parameter is an object of keys and values of configurations specific to the transaction. Please see: <a href="#the-configuration-object">The Configuration Object</a> for more information on all available configuration properties.</li>

</ul>

<p>

<code>io()</code> returns an object with the following members:

</p>

<ul>

<li><strong>id:</strong> This is the unique identifier of the transaction.</li>

<li><strong>abort():</strong> Aborts the specific transaction.</li>

<li><strong>isInProgress():</strong> Returns a boolean value indicating whether the transaction has completed.</li>

</ul>

<p>

This is an example GET transaction, handling the response at the earliest opportunity.

</p>

<pre class="code prettyprint">// Create a YUI instance using io-base module.

YUI().use("io-base", function(Y) {

var uri = "get.php?foo=bar";

// Define a function to handle the response data.

function complete(id, o, args) {

var id = id; // Transaction ID.

var data = o.responseText; // Response data.

var args = args[1]; // 'ipsum'.

};

// Subscribe to event "io:complete", and pass an array

// as an argument to the event handler "complete", since

// "complete" is global. At this point in the transaction

// lifecycle, success or failure is not yet known.

Y.on('io:complete', complete, Y, ['lorem', 'ipsum']);

100

// Make an HTTP request to 'get.php'.

101

// NOTE: This transaction does not use a configuration object.

102

var request = Y.io(uri);

103

});</pre>

104

105

106

107

<h2 id="using-io">Using IO</h2>

108

109

<h3 id="the-io-modules">The IO modules</h3>

110

<p>IO's core and supplementary features are split into several modules, to allow greater flexibility in selecting the desired features.</p>

111

<table>

112

<thead>

113

<tr><th>Module</th><th>Description</th></tr>

114

</thead>

115

<tbody>

116

<tr>

117

118

<td>This is the base module, containing the basic functionality needed for making HTTP requests.</td>

119

</tr>

120

<tr>

121

122

<td>This module extends io-base, to add cross-domain request capabilities using alternate HTTP transports.</td>

123

</tr>

124

<tr>

125

126

127

<td>This module extends io-base, to add the ability to serialize HTML form data for POST transactions.</td>

128

</tr>

129

<tr>

130

<td><code>io-upload-iframe</code></td>

131

<td>This module extends io-base, to allow file uploads with an HTML form, using an iframe as the transaction transport.</td>

132

</tr>

133

134

<tr>

135

<td><code>io-queue</code></td>

136

<td>This module extends io-base, to provide a basic queue interface for io.</td>

137

</tr>

138

<tr>

139

<td><code>io-nodejs</code></td>

140

<td>Conditional module that provides a transport for Node.js.</td>

141

</tr>

142

</tbody>

143

</table>

144

145

146

<h3 id="the-configuration-object">The Configuration Object</h3>

147

148

<p>This object is the second argument of <code>io()</code>. Its properties define transaction parameters and transaction response handling. The configuration object and all configuration properties are optional. The following table describes all configuration properties used by IO.</p>

149

150

<table>

151

<thead>

152

<tr>

153

<th>Property</th>

154

<th>Description</th>

155

</tr>

156

</thead>

157

<tbody>

158

<tr>

159

<td>method (string)</td>

160

<td>Defines the HTTP method for the transaction. If this property is undefined or omitted, the default value is GET.</td>

161

</tr>

162

<tr>

163

<td>data (string)</td>

164

<td>Data to be sent with the transaction, defined as a string of key-value pairs(e.g., <code>"foo=bar&baz=boo"</code>.) Data can also be defined as a single-level object(e.g., { 'foo':'bar', 'baz':'boo' }), which is then serialized into a key-value string. To use this capability, the sub-module <code>querystring-stringify-simple</code>, an optional dependency for io-base, must be declared in <code>Y.use()</code>.</td>

165

</tr>

166

<tr>

167

<td>headers (object)</td>

168

<td>Specific HTTP headers and values to be sent with the transaction (e.g., <code>{ 'Content-Type': 'application/xml; charset=utf-8' } </code>).</td>

169

</tr>

170

<tr>

171

<td>on (object)</td>

172

<td>This object can be used to register transaction event handlers for the set of supported io events, listed below. These events fire in addition to the global io events. All events handlers are optional.

173

174

<li><strong>start:</strong> <em>event handler</em></li>

175

<li><strong>complete:</strong> <em>event handler</em></li>

176

<li><strong>success:</strong> <em>event handler</em></li>

177

<li><strong>failure:</strong> <em>event handler</em></li>

178

<li><strong>end:</strong> <em>event handler</em></li>

179

</ul>

180

NOTE: These events are accessible only to the transaction's subscribers, whereas global IO events are accessible by all subscribers.

181

</td>

182

</tr>

183

<tr>

184

<td>context (object)</td>

185

<td>Defines the execution context of the event handler functions for the transaction. If undefined, a default value of <code>Y(the YUI instance)</code> is used.</td>

186

</tr>

187

<tr>

188

<td>form (object)</td>

189

<td>This object instructs io to use the labels and values of the specified HTML form as data.

190

191

<li><strong>id:</strong> This property can be defined as the id(String) of an HTML form or an object reference of the HTML form.</li>

192

<li><strong>useDisabled:</strong> When set to <strong>true</strong>, disabled field values are included as part of the data. The default value is false.</li>

193

</ul>

194

</td>

195

</tr>

196

<tr>

197

<td>xdr (object)</td>

198

<td>Defines the transport to be used for cross-domain requests (e.g., <code>{ use:'flash' }</code> ). The transaction will use the specified transport instead of the default transport, when specified in the transaction's configuration object.

199

200

<li><strong>use:</strong> This property specifies the type of transport to be used; the io-xdr module provides 'native' and 'flash' transports.</li>

201

<li><strong>dataType:</strong> When set to <strong>'xml'</strong>, io will return the response data as an XML document, if necessary.</li>

202

</ul>

203

</td>

204

</tr>

205

<tr>

206

<td>sync (boolean)</td>

207

<td>When set to <code>true</code>, the transaction will be processed synchronous, and will halt all code execution until the transaction is complete.</td>

208

</tr>

209

<tr>

210

<td>arguments (object)</td>

211

<td><p>Object, array, string, or number passed to all registered, transaction event handlers. This value is available as the second argument in the "start" and "end" event handlers; and, it is the third argument in the "complete", "success", and "failure" event handlers.</p></td>

212

</tr>

213

<tr>

214

<td>timeout</td>

215

<td>This value, defined as milliseconds, is a time threshold for the transaction (e.g., <code>{ timeout: 2000 }</code> ). When this limit is reached, and the transaction's Complete event has not yet fired, the transaction will be aborted.</td>

216

</tr>

217

</tbody>

218

</table>

219

220

<p>This is an example of a configuration object, with a set of properties defined.</p>

221

222

<pre class="code prettyprint">/*

223

* This is an example configuration object with all properties defined.

224

225

* method: This transaction will use HTTP POST.

226

* data: "user=yahoo" is the POST data.

227

* headers: Object of HTTP request headers for this transaction. The

228

* first header defines "Content-Type" and the second is a

229

* custom header.

230

* on: Object of defined event handlers for "start", "complete",

231

* and "end". These handlers are methods of an object

232

* named "Dispatch".

233

* context: Event handlers will execute in the proper object context,

234

* so usage 'this' will reference Dispatch.

235

* form: Object specifying the HTML form to be serialized into a key-value

236

* string and sent as data; and, informing io to include disabled

237

* HTML form fields as part of the data. If input type of "file"

238

* is present, setting the upload property to "true" will create an

239

* alternate transport, to submit the HTML form with the

240

* selected files.

241

* xdr: Instructs io to use the defined transport, in this case Flash,

242

* to make a cross-domain request for this transaction.

243

* arguments: Object of data, passed as an argument to the event

244

* handlers.

245

246

var cfg = {

247

method: 'POST',

248

data: 'user=yahoo',

249

headers: {

250

'Content-Type': 'application/json',

251

252

on: {

253

start: Dispatch.start,

254

complete: Dispatch.complete,

255

end: Dispatch.end

256

257

context: Dispatch,

258

form: {

259

id: formObject,

260

useDisabled: true,

261

upload: true

262

263

xdr: {

264

use: 'flash',

265

dataType: 'xml'

266

267

arguments: {

268

start: 'foo',

269

complete: 'bar',

270

end: 'baz'

271

}

272

};</pre>

273

274

275

<h3 id="the-response-object">The Response Object</h3>

276

<p>

277

When a transaction, using the XHR object as a transport, is complete, the response data are passed as an object to the event handler.

278

</p>

279

<table>

280

<thead>

281

<tr><th>Field</th><th>Description</th></tr>

282

</thead>

283

<tbody>

284

<tr>

285

<td><strong>status</strong></td>

286

287

<td>The HTTP status code of the transaction.</td>

288

</tr>

289

<tr>

290

<td><strong>statusText</strong></td>

291

<td>The HTTP status message.</td>

292

</tr>

293

<tr>

294

295

<td><strong>getResponseHeader(<em>headername</em>)</strong></td>

296

<td>Returns the string value of the specified header label.</td>

297

</tr>

298

<tr>

299

<td><strong>getAllResponseHeaders()</strong></td>

300

<td>All response HTTP headers are available as a string. Each key-value pair is delimited by "\n".</td>

301

302

</tr>

303

<tr>

304

<td><strong>responseText</strong></td>

305

<td>The response data as a decoded string.</td>

306

</tr>

307

<tr>

308

<td><strong>responseXML</strong></td>

309

<td>The response data as an XML document.</td>

310

</tr>

311

</tbody>

312

</table>

313

314

<p>

315

NOTE: Transactions involving file upload or cross-domain requests, using alternate transports, will only populate the <code>responseText</code> or <code>responseXML</code> field. The HTTP status and response headers are either inaccessible or unavailable to these alternate transports.

316

</p>

317

318

<h3 id="events">Events</h3>

319

<p>

320

IO events provide access to state and data during a transaction's lifecycle. There are two aspects to io events: global and transaction. Global events are always fired by io for all transactions, and these events are accessible to all event subscribers. Transaction events are created and fired if they have handlers defined in the configuration object. Global events are identified by the <code>io:eventname</code> pattern.

321

</p>

322

<p>

323

The following table describes the available io events and provides examples of how to subscribe to them globally:

324

</p>

325

<table>

326

<thead>

327

<tr><th>Event</th><th>Description</th></tr>

328

</thead>

329

<tbody>

330

<tr>

331

<td><strong>io:start</strong></td>

332

<td>

333

<p>Fires when a request is made to a resource. The event handler's arguments signature is:</p>

334

335

<pre class="code prettyprint">function onStart(transactionid, arguments) {

336

// transactionid : The transaction's ID.

337

// arguments: Array ['foo','bar'].

338

}

339

340

// Subscribe to "io.start".

341

Y.on('io:start', onStart, Y, { start: ['foo','bar']; );</pre>

342

343

</td>

344

</tr>

345

<tr>

346

<td><strong>io:complete</strong></td>

347

<td>

348

<p>Fires after "io:start", when the transaction is complete and response data are available. This is the earliest opportunity to access any response data. The event handler's arguments signature is:</p>

349

<pre class="code prettyprint">function onComplete(transactionid, response, arguments) {

350

// transactionid : The transaction's ID.

351

// response: The response object.

352

// arguments: Object containing an

353

array { complete: ['foo', 'bar'] }.

354

}

355

356

// Subscribe to "io.complete".

357

Y.on('io:complete', onComplete, Y, { complete: ['foo', 'bar'] } );</pre>

358

359

</td>

360

</tr>

361

<tr>

362

<td><strong>io:success</strong></td>

363

<td>

364

<p>Fires after the "complete" event, when the response HTTP status resolves to 2xx. The event handler's arguments signature is:</p>

365

<pre class="code prettyprint">function onSuccess(transactionid, response, arguments) {

366

// transactionid : The transaction's ID.

367

// response: The response object.

368

// arguments: Boolean value "true".

369

}

370

371

// Subscribe to "io.success".

372

Y.on('io:success', onSuccess, Y, true);</pre>

373

374

</td>

375

</tr>

376

<tr>

377

<td><strong>io:failure</strong></td>

378

<td>

379

<p>Fires after the "complete" event, when the response HTTP status resolves to 4xx. 5xx, undefined, or a non-standard HTTP status. This event also includes 'abort' and 'timeout' conditions. The event handler's arguments signature is:</p>

380

<pre class="code prettyprint">function onFailure(transactionid, response, arguments) {

381

// transactionid : The transaction's ID.

382

// response: The response object. Only status and

383

// statusText are populated when the

384

// transaction is terminated due to abort

385

// or timeout. The status will read

386

// 0, and statusText will return "timeout"

387

// or "abort" depending on the mode of

388

// termination.

389

// arguments: String "Transaction Failed".

390

}

391

// Subscribe to "io.failure".

392

Y.on('io:failure', onFailure, Y, 'Transaction Failed');</pre>

393

394

</td>

395

</tr>

396

<tr>

397

398

<td>

399

<p>Fires at the conclusion of a transaction, after "success" or "failure" has been determined.. The event handler's arguments signature is:</p>

400

<pre class="code prettyprint">function onEnd(transactionid, arguments) {

401

// transactionid : The transaction's ID.

402

// arguments: Number 0.

403

}

404

405

// Subscribe to "io.end".

406

Y.on('io:end', onEnd, Y, 0);</pre>

407

408

</td>

409

</tr>

410

<tr>

411

<td><strong>io:xdrReady</strong></td>

412

<td>

413

Fires when the flash XDR transport is ready for use. This event only fires once, when the transport initialization is complete.

414

</td>

415

</tr>

416

</tbody>

417

</table>

418

419

<p>The following example demonstrates an IO transaction with an event handler subscribed to "io:complete".</p>

420

<pre class="code prettyprint">// Create a YUI instance using io module.

421

YUI().use("io-base", function(Y) {

422

423

* Create a function as the event handler for the event "io:complete".

424

425

* The function will receive the following arguments:

426

* - The ID of the transaction

427

* - Object containing the response data.

428

* - Argument one defined when subscribing to the event(e.g., "foo").

429

* - Argument two defined when subscribing to the event(e.g., "bar").

430

431

function onComplete(transactionId, responseObject, arg1, arg2) {

432

433

* The argument 'responseObject' is the response object. Its

434

* properties are:

435

* - status

436

* - statusText

437

* - getResponseHeader(headerName)

438

* - getAllResponseHeaders

439

* - responseText

440

* - responseXML

441

442

* NOTE: In an XDR transaction, only the responseText or the responseXML property is defined.

443

444

};

445

446

447

* Subscribe to the event "io:complete", using Y.on.

448

449

* - 'io:complete' : Subscribe to this io event.

450

* - onComplete : The event handler to be subscribed to 'io:complete'.

451

* - Y : The execution context of the event handler, in this case, the YUI sandbox.

452

* since the doComplete is defined as a global function.

453

* - 'foo' : The first argument received by the event handler.

454

* - 'bar' : The second argument received by the event handler.

455

* Additional arguments can be defined, as desired.

456

457

Y.on('io:complete', onComplete, Y, "foo", "bar");

458

459

// Starts the transaction.

460

var request = Y.io(uri);

461

});</pre>

462

463

464

<h3 id="synchronous-transactions">Synchronous Transactions</h3>

465

<p>For same-domain requests, YUI io can be instructed to send a synchronous request, which will halt all script execution until the transaction is complete. When the transaction is complete, the response data are directly accessible through the object returned by Y.io(), and the data are also accessible through all io events. When making synchronous requests, abort() and isInProgress() are not available.</p>

466

467

<pre class="code prettyprint">// Create a YUI instance using the io-base module.

468

YUI().use("io-base", function(Y) {

469

var cfg,

470

request;

471

// Create a configuration object for the synchronous transaction.

472

cfg = {

473

sync: true,

474

arguments: { 'foo' : 'bar' }

475

};

476

477

478

* var request will contain the following fields, when the

479

* transaction is complete:

480

* - id

481

* - status

482

* - statusText

483

* - getResponseHeader()

484

* - getAllResponseHeaders()

485

* - responseText

486

* - responseXML

487

* - arguments

488

489

request = Y.io(uri, cfg);

490

});</pre>

491

492

493

<h3 id="cross-domain-transactions">Cross-Domain Transactions</h3>

494

<p>By default, <code>io</code> uses the XMLHttpRequest object as the transport for HTTP transactions. It can also be configured to use an alternate transport to make cross-domain, HTTP transactions. Currently, io can make use of Flash as an alternate transport. To prepare io for Flash-based, cross-domain transactions, the transport <code>io.swf</code> must be deployed and accessible to YUI io. (The file "io.swf" can be found in YUI io's build directory in the YUI3 download at: http://yuilibrary.com/downloads/.) For each transaction, the configuration object's <code>xdr</code> object must be defined as <code>{ use: 'flash' }</code> so io will use the designated transport instead of using the default XMLHttpRequest transport.</p>

495

<p>

496

As <code>io.swf</code> is written in ActionScript 3, Flash Player 9 or better is required (version <strong>9.0.124</strong> or better is recommended). Additionally, a cross-domain policy file must be deployed at the resource to grant the client access to the remote domain. A cross-domain request will not be successful without this policy file hosted at the resource. The following example file grants permissive access to the host from all requests, but the host will only accept custom HTTP headers originating from <code>yahoo.com</code>.

497

</p>

498

499

500

<!DOCTYPE cross-domain-policy SYSTEM

501

"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

502

<cross-domain-policy>

503

<allow-access-from domain="*"/>

504

<allow-http-request-headers-from domain="*.yahoo.com" headers="*"/>

505

</cross-domain-policy></pre>

506

507

<p>

508

For more information on cross-domain policy file specifications, see the following articles at Adobe Developer Connection.

509

</p>

510

<ul>

511

<li><a href="http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html">Cross-Domain Policy File Specifications</a>.</li>

512

<li><a href="http://kb.adobe.com/selfservice/viewContent.do?externalId=kb403030">HTTP Headers Blacklist</a>.</li>

513

</ul>

514

<p>

515

The following example demonstrates a cross-domain transaction, starting with the initialization of the XDR transport and subscribing to three global io events.

516

</p>

517

518

<pre class="code prettyprint">// Create a YUI instance using the io cross-domain submodule

519

YUI().use("io-xdr", function(Y) {

520

// Create a configuration object with the src property defined,

521

// src: The path to "io.swf" relative to the HTML file.

522

var xdrCfg = {

523

src:'io.swf'

524

};

525

526

// Initialize the cross-domain transport

527

Y.io.transport(xdrCfg);

528

529

// Define the configurations to be used for each transaciton..

530

var cfg = {

531

xdr: { use: 'flash'}, // Instruct io to use the flash XDR transport.

532

data: 'foo=bar&baz=boo', // Key-value string of data.

533

timeout: 3000, // Abort the transaction, if it is still pending, after 3000ms.

534

// An object passed, as an argument, to the event handlers.

535

arguments: {

536

start: 'foo',

537

complete: 'bar',

538

end: 'baz'

539

}

540

};

541

542

543

* GlobalEventHandler is an example object that encapsulates

544

* event handlers for "io:start", "io:complete", and "io:end".

545

546

* start( ) // Event handler for "io:start"

547

* success( ) // Event handler for "io:complete".

548

* end( ) // Event handler for "io:end".

549

550

var GlobalEventHandler = {

551

start: function(id, args) {

552

var args = args.start // 'foo'

553

554

success: function(id, o, args) {

555

var args = args.complete; // 'bar'

556

var data = o.responseText;

557

var xml = o.responseXML;

558

559

end: function(id, args) {

560

var args = args.end // args = 'baz'

561

}

562

};

563

564

function callIo() {

565

//example URI.

566

var uri = "http://pipes.yahooapis.com/",

567

// Start the transaction

568

request = Y.io(uri, cfg);

569

}

570

571

// Subscribe GlobalEventHandler.start to event "io:start".

572

Y.on('io:start', GlobalEventHandler.start, Y);

573

// Subscribe GlobalEventHandler.complete to event "io:complete".

574

Y.on('io:success', GlobalEventHandler.complete, Y);

575

// Subscribe GlobalEventHandler to event "io:end".

576

Y.on('io:end', GlobalEventHandler.end, Y);

577

578

// Once the Flash transport is initialized and ready for use,

579

// it will fire the "io:xdrReady" event. Subscribe to it,

580

// to automatically call function "callIo" when the transport

581

// is ready..

582

Y.on('io:xdrReady', callIo, Y);

583

584

});</pre>

585

586

<p>

587

Note: Cross-domain transactions do not fire the global <code>io:complete</code> event and the transaction-specific <code>complete</code> event, when using the IE XDomainRequest or the Flash transport. All other events in the transaction lifecycle are fired.

588

</p>

589

<p>

590

A subset of A-grade browsers are capable of making cross-domain requests, using XMLHttpRequest, requiring specific access control headers be served from the resource. To use this feature, the xdr configuration must be defined with: <code>{ use: 'native' }</code>. IO will try to resolve the request using the native transport, and it will fall back to the Flash transport if the initial attempt throws an exception due to the browser lacking native support.

591

</p>

592

<p>

593

<strong>NOTE:</strong> For native cross-domain requests to work, the resource <strong>must</strong> respond with the "Access-Control-Allow-Origin" header with a value permitting the client to make the request. In the absence of this HTTP response header, the transaction will always fail. Please see the following articles for more information on this topic.

594

</p>

595

<ul>

596

<li>Mozilla Developer Center: <a href="https://developer.mozilla.org/En/HTTP_Access_Control">HTTP Access Control article</a>.</li>

597

<li>MSDN: <a href="http://msdn.microsoft.com/en-us/library/cc709423(VS.85).aspx">Cross-Domain Security article</a>.</li>

598

<li>W3C: <a href="http://dev.w3.org/2006/waf/access-control/">Access Control Working Draft</a>,</li>

599

</ul>

600

601

<h3 id="serializing-html-form-as-data">Serializing HTML Form as Data</h3>

602

<p>

603

IO can serialize HTML form fields into a string of UTF-8 encoded, name-value pairs. If the transaction is HTTP GET, the data are appended to the URI as a querystring. If the transaction if HTTP POST, the data will be the POST message.

604

</p>

605

606

<pre class="code prettyprint">// Create a YUI instance using the io-form sub-module.

607

YUI().use("io-form", function(Y) {

608

// Create a configuration object for the file upload transaction.

609

// The form configuration should include two defined properties:

610

// id: This can be the ID or an object reference to the HTML form.

611

// useDisabled: Set this property to "true" to include disabled

612

// HTML form fields, as part of the data. By

613

// default, disabled fields are excluded from the

614

// serialization.

615

// The HTML form data are sent as a UTF-8 encoded key-value string.

616

var cfg = {

617

method: 'POST',

618

form: {

619

id: formObject,

620

useDisabled: true

621

}

622

};

623

624

// Define a function to handle the response data.

625

function complete(id, o, args) {

626

var id = id; // Transaction ID.

627

var data = o.responseText; // Response data.

628

var args = args[1]; // 'ipsum'.

629

};

630

631

// Subscribe to event "io:complete", and pass an array

632

// as an argument to the event handler "complete".

633

Y.on('io:complete', complete, Y, { 'foo':'bar' });

634

635

// Start the transaction.

636

var request = Y.io(uri, cfg);

637

});</pre>

638

639

640

641

642

<h3 id="uploading-files-in-an-html-form">Uploading Files in an HTML Form</h3>

643

<p>

644

The default XHR transport, used in IO, cannot upload HTML form data that include elements of type="file". In this situation, IO will use an alternate transport -- an iframe -- to facilitate the transaction. The response data must be one of the following content types: "text/html", "text/plain", "text/xml". The following example shows how to configure a transaction involving file upload:

645

</p>

646

647

<pre class="code prettyprint">/*

648

* This example demonstrates how to configure io to upload files

649

* from an HTML form. This example uses the global events:

650

* "io:start" and "io:complete" to handle the transaction and

651

* response. Transaction events can be defined and fired, as well,

652

* in the configuration object; but, they are not used in this

653

* example.

654

655

// Create a YUI instance using the io-upload-iframe sub-module.

656

YUI().use("io-upload-iframe", function(Y) {

657

// Create a configuration object for the file upload transaction.

658

// The form configuration should include two defined properties:

659

// id: This can be the ID or an object reference to the HTML form

660

// containing the input type="file" elements.

661

// upload: Set this property to "true" to indicate this is a file

662

// upload transaction.

663

var cfg = {

664

method: 'POST',

665

form: {

666

id: formObject,

667

upload: true

668

}

669

};

670

671

// Define a function to handle the start of a transaction

672

function start(id, args) {

673

var id = id; // Transaction ID.

674

var args = args.foo; // 'bar'

675

}

676

677

// Define a function to handle the response data.

678

function complete(id, o, args) {

679

var id = id; // Transaction ID.

680

var data = o.responseText; // Response data.

681

var args = args[1]; // 'ipsum'.

682

};

683

684

// Subscribe to event "io:start", and pass an object

685

// as an argument to the event handler "start".

686

Y.on('io:start', start, Y, { 'foo':'bar' });

687

688

// Subscribe to event "io:complete", and pass an array

689

// as an argument to the event handler "complete".

690

Y.on('io:complete', complete, Y, ['lorem', 'ipsum']);

691

692

// Start the transaction.

693

var request = Y.io(uri, cfg);

694

});</pre>

695

696

697

<p>

698

When performing a file upload, a subset of global and transaction events will be fired. Specifically, these are:

699

</p>

700

<ul>

701

<li>Start</li>

702

<li>Complete</li>

703

704

</ul>

705

<p>Success and Failure events are not processed and fired because the iframe transport does not provide access to the HTTP status and response headers, to reliably determine those conditions.</p>

706

707

<h3 id="setting-http-headers">Setting HTTP Headers</h3>

708

<p>

709

IO can be configure to send default, user-defined HTTP Headers for all transactions, in addition to any headers defined in the configuration object. Headers can be set or removed as needed. The following example shows how to set and how to delete default headers in IO:

710

</p>

711

712

<pre class="code prettyprint">YUI().use("io-base", function(Y) {

713

714

// Set a new default HTTP header.

715

Y.io.header('Content-Type', 'application/json');

716

717

// To remove an existing header, use the same method, but omit the value.

718

Y.io.header('Content-Type');

719

});</pre>

720

721

722

<p>Custom HTTP headers may or may not be sent in cross-domain requests. This is may be due to limitations of the transport, or specific "Access-Control" headers requirement.</p>

723

724

<h3 id="queue">Queue</h3>

725

<p>

726

IO's queue module provides FIFO transaction response while keeping each transaction asynchronous and non-blocking. Specifically, transactions are handled -- by global or transaction event handlers -- in the order they are sent, regardless of actual server response order. Transactions can be promoted to the front of the queue, or they can be purged from the queue, as well.

727

</p>

728

<table>

729

<thead>

730

<tr><th>Field</th><th>Description</th></tr>

731

</thead>

732

<tbody>

733

<tr>

734

<td><strong>queue(uri, configuration)</strong></td>

735

<td>Method signature is identical to io, but returns the id of the transaction.</td>

736

</tr>

737

<tr>

738

<td><strong>queue.start()</strong></td>

739

<td>Activates the queue, and begins processing transactions in the queue. This is the default state of the queue.</td>

740

</tr>

741

<tr>

742

743

<td><strong>queue.stop()</strong></td>

744

<td>Deactivates the queue. Transactions sent to queue() will be stored until the queue is re-started.</td>

745

</tr>

746

<td><strong>queue.promote(id)</strong></td>

747

<td>Moves the specified transaction stored in the queue to the head of the queue.</td>

748

</tr>

749

<tr>

750

<td><strong>queue.remove(id)</strong></td>

751

<td>Deletes the specified transaction stored in the queue.</td>

752

</tr>

753

</tbody>

754

</table>

755

756

<pre class="code prettyprint">// Create a YUI instance using the io queue sub-module.

757

YUI().use("io-queue", function(Y) {

758

759

// Stop the queue so transactions can be stored.

760

Y.io.queue.stop();

761

762

// Send four transactions into the queue. Each response will arrive

763

// in synchronous order.

764

var task0 = Y.io.queue(uri);

765

var task1 = Y.io.queue(uri);

766

var task2 = Y.io.queue(uri);

767

var task3 = Y.io.queue(uri);

768

769

// Promote task2 to the top of the queue.

770

Y.io.queue.promote(task2);

771

772

// Remove task3 from the queue.

773

Y.io.queue.remove(task3);

774

775

// Re-start the queue.

776

// Transactions are sent in the following order: task2, task0, task 1.

777

// Transaction callbacks, if provided, will be processed in the same

778

// sequence: task2, task0, task1, regardless of actual response order.

779

Y.io.queue.start();

780

});</pre>

781

782

783

<h3 id="instantiating-io">Instantiating IO</h3>

784

<p>

785

As of 3.4.0, IO is instantiatiable. An IO instance avails its public and private fields, allowing for customizations as needed.

786

</p>

787

788

<pre class="code prettyprint">// Create a new instance of IO.

789

var io = new IO();

790

791

// Send a request using the new IO instance.

792

// This is analogous to the static method

793

// Y.io()

794

io.send(uri, configuration);</pre>

795

796

797

<p>

798

In addition to being instantiable, IO is now an EventTarget, and IO's global events can be configured at instantiation time.

799

</p>

800

801

<pre class="code prettyprint">// This simple example creates a new instance of IO and passes

802

// Custom Event configurations that instructs IO to emit

803

// Event Facades for all its events, and allow the events to

804

// bubble to other registered event targets, if any.

805

var io = new IO({

806

emitFacade: true, // Event handlers will receive an Event Facade.

807

bubbles: true, // Events will bubble to registered event targets.

808

});</pre>

809

810

811

<p>

812

If IO is configured to emit Event Facades, each event handler will receive the Event Facade as the argument.</p>

813

</p>

814

815

<pre class="code prettyprint">// This is the event handler using Event Facades.

816

var configuration = {

817

on: {

818

complete: function(o) {

819

820

* o is the event facade, and contains the following fields:

821

* - o.id is the transaction id.

822

* - o.data is the XMLHttpRequest (or other transport) object.

823

* - o.arguments is the user-defined arguments, if any.

824

* - o.cfg is the configuration object used for this transaction.

825

826

* These fields are in addition to the Event Facade's fields.

827

828

}

829

}

830

};

831

832

// For comparison, this is the regular event handler, when

833

// not emitting Event Facades as described in the previous

834

// sections on "The Response Object" and "Events."

835

var configuration = {

836

on: {

837

complete: function(id, xhr, arguments) {

838

// id is the transaction id.

839

// xhr is the XMLHttpRequest object.

840

// arguments is the user-defined arguments, if any.

841

}

842

}

843

};</pre>

844

845

846

<h3 id="using-io-in-nodejs">Using IO in Node.js</h3>

847

848

<p>

849

YUI uses Mikeal Roger's <a href="https://github.com/mikeal/request">Request</a> library under the hood

850

to provide our IO transport layer in Node.js.

851

</p>

852

853

<p>

854

The <code>io-base</code> module works out of the box and mimic's it's browser counterpart as much as it can.

855

</p>

856

857

<p><strong>Note:</strong> You can not use the <code>io</code> module on the server, the <code>io</code> module

858

contains the <code>io-form</code> and the <code>io-upload-frame</code> modules which both rely on a working DOM

859

to be available. The <code>io-base</code> module, however, has no requirement on a DOM.

860

</p>

861

862

<h4 id="simple-example">Simple Example</h4>

863

<pre class="code prettyprint">var Y = require('yui/io-base');

864

865

Y.io('https://github.com/api/v2/json/user/show/yui', {

866

on: {

867

complete: function(id, e) {

868

var json = JSON.parse(e.responseText);

869

console.log(json);

870

}

871

}

872

});</pre>

873

874

875

<p>Since the <code>request</code> module is bundled with YUI, we expose that inside YUI so you can also use it.</p>

876

877

<p>We alias request on the <code>IO</code> object as <code>Y.IO.request</code>, so now you can use it like this:</p>

878

879

<pre class="code prettyprint">fs.createReadStream('file.json').pipe(Y.IO.request.put('http://mysite.com/obj.json'));

880

881

Y.IO.request.get('http://google.com/img.png').pipe(Y.IO.request.put('http://mysite.com/img.png'));</pre>

882

883

884

<p>In future versions of YUI, we will support file uploads via our File API that will use this under the hood as well.</p>

885

886

<p>See the <a href="../yui/nodejs-io.html">YUI on Node.js example for IO</a> for more information about

887

using <code>IO</code> on Node.js.</p>

888

889

<h2 id="security-bulletin">Security Bulletin</h2>

890

<p>A security vulnerability exists in the XDR transport <code>io.swf</code> when using the <code>io-xdr</code> sub-module to make cross-domain requests. This vulnerability allows third-party sites to load <code>io.swf</code> from a remote domain and issue HTTP requests with the SWF's domain credentials. Please examine the following use cases, and, if applicable to you, please follow the recommended actions to close this exploit.

891

</p>

892

<ul>

893

<li> You currently host <code>io.swf</code> from YUI 3.1.0, 3.1.1, or 3.2.0pr1, and your application uses the io-xdr sub-module to make cross-domain requests. Solution: replace the version of <code>io.swf</code> with <code>io.swf</code> from YUI 3.1.2.</li>

894

<li> Your application uses the <code>io-xdr</code> sub-module from version YUI 3.1.0, 3.1.1, and you explicitly load <code>io.swf</code> from <code>http://yui.yahooapis.com/version/build/io.swf</code> (where <code>version</code> matches the affected YUI versions). Solution: modify your application's <code>crossdomain.xml</code> so that <code>allow-access-from domain=</code> does <strong>not</strong> allow access from yui.yahooapis.com. Download YUI 3.1.2 and deploy <code>io.swf</code> on your application's domain instead of loading it from yui.yahooapis.com.

895

<li> Your application uses the <code>io-xdr</code> sub-module from version YUI 3.1.0, 3.1.1, and you explicitly load <code>io.swf</code> from a disparate domain, and you have a crossdomain policy file allowing access from the SWF's domain. Solution: modify your application's crossdomain.xml so that <code>allow-access-from domain=</code> does <strong>not</strong> allow access from the domain serving <code>io.swf</code>. Download YUI 3.1.2 and deploy <code>io.swf</code> on your application's domain instead of loading it from a remote domain.

896

<li> If you use <code>io.swf</code> from YUI 3.0.0 you are not affected by this vulnerability.</li>

897

</ul>

898

<p>Beginning with YUI 3.1.2, <code>io.swf</code> will no longer be accessible from yui.yahooapis.com. You will be required to host and serve <code>io.swf</code>, if you wish to employ it as an XDR transport.</p>

899

900

<h2 id="known-issues">Known Issues</h2>

901

<ul>

902

<li>Multiple HTML Submit buttons, in an HTML form, are not supported at this time.</li>

903

</ul>

904

</div>

905

</div>

906

</div>

907

908

909

910

911

912

913

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

914

</div>

915

916

917

918

<li>

919

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

920

</li>

921

<li>

922

<a href="#a-simple-transaction">A Simple Transaction</a>

923

</li>

924

<li>

925

<a href="#using-io">Using IO</a>

926

927

<li>

928

<a href="#the-io-modules">The IO modules</a>

929

</li>

930

<li>

931

<a href="#the-configuration-object">The Configuration Object</a>

932

</li>

933

<li>

934

<a href="#the-response-object">The Response Object</a>

935

</li>

936

<li>

937

<a href="#events">Events</a>

938

</li>

939

<li>

940

<a href="#synchronous-transactions">Synchronous Transactions</a>

941

</li>

942

<li>

943

<a href="#cross-domain-transactions">Cross-Domain Transactions</a>

944

</li>

945

<li>

946

<a href="#serializing-html-form-as-data">Serializing HTML Form as Data</a>

947

</li>

948

<li>

949

<a href="#uploading-files-in-an-html-form">Uploading Files in an HTML Form</a>

950

</li>

951

<li>

952

<a href="#setting-http-headers">Setting HTTP Headers</a>

953

</li>

954

<li>

955

<a href="#queue">Queue</a>

956

</li>

957

<li>

958

<a href="#instantiating-io">Instantiating IO</a>

959

</li>

960

<li>

961

<a href="#using-io-in-nodejs">Using IO in Node.js</a>

962

963

<li>

964

<a href="#simple-example">Simple Example</a>

965

</li>

966

</ul>

967

</li>

968

</ul>

969

</li>

970

<li>

971

<a href="#security-bulletin">Security Bulletin</a>

972

</li>

973

<li>

974

<a href="#known-issues">Known Issues</a>

975

</li>

976

</ul>

977

</div>

978

</div>

979

980

981

982

983

984

<h2 class="no-toc">Examples</h2>

985

</div>

986

987

988

989

990

991

992

<a href="get.html">HTTP GET to request data</a>

993

</li>

994

995

996

997

998

<a href="weather.html">Request XML data from Yahoo! Weather</a>

999

</li>

1000

1001

1002

1003

1004

<a href="xdr.html">Request JSON using Yahoo! Pipes</a>

1005

</li>

1006

1007

1008

1009

1010

</ul>

1011

</div>

1012

</div>

1013

1014

1015

1016

1017

1018

<h2 class="no-toc">Examples That Use This Component</h2>

1019

</div>

1020

1021

1022

1023

1024

1025

1026

1027

1028

1029

1030

1031

1032

<a href="../overlay/overlay-io-plugin.html">IO Plugin</a>

1033

</li>

1034

1035

1036

</ul>

1037

</div>

1038

</div>

1039

1040

</div>

1041

</div>

1042

</div>

1043

</div>

1044

1045

1046

1047

1048

</body>

1049

</html>

Older »