~bac/juju-gui/trunkcopy

<a href="http://pjax.heroku.com/">Pjax</a> is a technique that allows you to progressively enhance normal links on a page so that clicks result in the linked content being loaded via Ajax and the URL being updated using HTML5 <code>pushState</code>, avoiding a full page load. In browsers that don't support <code>pushState</code> or that have JavaScript disabled, link clicks will result in a normal full page load. The Pjax Utility makes it easy to add this functionality to existing pages.

</p>

</div>

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

<p>

To include the source files for Pjax 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('pjax', function (Y) {

// Pjax 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-pjax">Using Pjax</h2>

<h3 id="quick-start">Quick Start</h3>

<p>

It's easy to add pjax functionality to any page with just a few lines of code. You don't even need any special server-side logic. Here's a simple example:

</p>

<pre class="code prettyprint"><h1>Links</h1>

<ol>

<li><a href="page3.html" class="yui3-pjax">Page Three</a></li>

</ol>

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

new Y.Pjax({container: '#content'});

});

</script></pre>

<p>

This creates a new Pjax instance that, by default, listens for clicks on any

link on the page that has a <code>yui3-pjax</code> class. When a <code>yui3-pjax</code> link is clicked, its URL will be loaded via Ajax and the loaded content will be inserted into the <code>#content</code> div, replacing its existing contents. If the loaded page includes an HTML <code><title></code> element, the current page's title will also be replaced with the new title.

</p>

<p>

One important thing to note is that since Pjax uses <a href="https://developer.mozilla.org/en/XMLHttpRequest"><code>XMLHttpRequest</code></a> under the hood, it can only load URLs from the <a href="https://developer.mozilla.org/en/Same_origin_policy_for_JavaScript">same origin</a> as the current page. This means the link URL must share the same protocol, port, and host as the current page. Pjax will ignore URLs it can't load, resulting in a full page load for those URLs.

</p>

<h3 id="instantiating-pjax">Instantiating Pjax</h3>

100

<p>

101

There are two ways to instantiate the Pjax Utility: you can load the <code>pjax-plugin</code> module and use the <code>Y.Plugin.Pjax</code> Node plugin, or you can load the <code>pjax</code> module and create a standalone instance of the <code>Y.Pjax</code> class.

102

</p>

103

104

<p>

105

Both instantiation methods provide the same core functionality; they only differ in how they're instantiated. Feel free to use whichever one you prefer.

106

</p>

107

108

<h4 id="as-a-plugin">As a Plugin</h4>

109

110

<p>

111

To instantiate Pjax as a plugin, load the <code>pjax-plugin</code> module and then plug the <code>Y.Plugin.Pjax</code> class into a Node instance. The node will be used as the container element, and content loaded via Pjax will replace the contents of the node.

112

</p>

113

114

<pre class="code prettyprint">YUI().use('pjax-plugin', function (Y) {

115

Y.one('#content').plug(Y.Plugin.Pjax);

116

});</pre>

117

118

119

<p>

120

You may optionally pass configuration attributes as the second argument to <code>plug()</code>:

121

</p>

122

123

<pre class="code prettyprint">Y.one('#content').plug(Y.Plugin.Pjax, {

124

linkSelector: 'a.pjax',

125

timeout : 10000

126

});</pre>

127

128

129

<h4 id="as-a-class">As a Class</h4>

130

131

<p>

132

To instantiate Pjax as a class, load the <code>pjax</code> module and then create a new instance of <code>Y.Pjax</code>, specifying the node you want to use as a content container. You may optionally provide additional configuration attributes as well.

133

</p>

134

135

<pre class="code prettyprint">YUI().use('pjax', function (Y) {

136

new Y.Pjax({container: '#content'});

137

});</pre>

138

139

140

<h3 id="configuring-pjax">Configuring Pjax</h3>

141

142

<p>

143

All configuration attributes are optional, although you'll usually want to at least specify a <code>container</code> node if you aren't using the Pjax plugin.

144

</p>

145

146

<h4 id="config-attributes">Config Attributes</h4>

147

148

<table>

149

<thead>

150

<tr>

151

<th>Attribute</th>

152

153

<th>Default</th>

154

<th>Description</th>

155

</tr>

156

</thead>

157

158

<tbody>

159

<tr>

160

<td><code>addPjaxParam</code></td>

161

<td>Boolean</td>

162

163

<td>

164

<p>

165

If <code>true</code>, a "pjax=1" query parameter will be appended to all URLs requested via Pjax.

166

</p>

167

168

<p>

169

Browsers ignore HTTP request headers when caching content, so if the same URL is used to request a partial Pjax page and a full page, the browser will cache them under the same key and may later load the cached partial page when the user actually requests a full page (or vice versa).

170

</p>

171

172

<p>

173

To prevent this, we can add a bogus query parameter to the URL so that Pjax URLs will always be cached separately from non-Pjax URLs.

174

</p>

175

</td>

176

</tr>

177

178

<tr>

179

<td><code>container</code></td>

180

181

182

<td>

183

<p>

184

Node into which content should be inserted when a page is loaded via Pjax. This node's existing contents will be removed to make way for the new content.

185

</p>

186

187

<p>

188

If not set, loaded content will not be automatically inserted into the page.

189

</p>

190

</td>

191

</tr>

192

193

<tr>

194

<td><code>contentSelector</code></td>

195

<td>String</td>

196

197

<td>

198

<p>

199

CSS selector used to extract a specific portion of the content of a page loaded via Pjax.

200

</p>

201

202

<p>

203

For example, if you wanted to load the page <code>example.html</code> but only use the content within an element with the id "pjax-content", you'd set

204

<code>contentSelector</code> to "#pjax-content".

205

</p>

206

207

<p>

208

If not set, the entire page will be used.

209

</p>

210

</td>

211

</tr>

212

213

<tr>

214

<td><code>linkSelector</code></td>

215

<td>String</td>

216

217

<td>

218

<p>

219

CSS selector string used to filter link click events so that only the links which match it will have the enhanced navigation behavior of Pjax applied.

220

</p>

221

222

<p>

223

When a link is clicked and that link matches this selector, Pjax will attempt to load it via Ajax. If HTML5 history is not supported, or if the link was middle-clicked, right-clicked, or clicked while a modifier key was pressed, the link click will be handled by the browser just like any old link.

224

</p>

225

</td>

226

</tr>

227

228

<tr>

229

<td><code>navigateOnHash</code></td>

230

<td>Boolean</td>

231

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

232

<td>

233

<p>

234

Whether navigating to a hash-fragment identifier on the current page should be enhanced and cause the <code>navigate</code> event to fire.

235

</p>

236

237

<p>

238

By default Pjax allows the browser to perform its default action when a user is navigating within a page by clicking in-page links (e.g. <code><a href="#top">Top of page</a></code>) and does not attempt to interfere or enhance in-page navigation.

239

</p>

240

</td>

241

</tr>

242

243

<tr>

244

<td><code>scrollToTop</code></td>

245

<td>Boolean</td>

246

247

<td>

248

<p>

249

Whether the page should be scrolled to the top after navigating to a URL.

250

</p>

251

252

<p>

253

When the user clicks the browser's back button, the previous scroll position will be maintained.

254

</p>

255

</td>

256

</tr>

257

258

<tr>

259

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

260

<td>Number</td>

261

262

<td>

263

<p>

264

Time in milliseconds after which an Ajax request should time out. When a timeout occurs, the <code>error</code> event will be fired.

265

</p>

266

</td>

267

</tr>

268

269

<tr>

270

<td><code>titleSelector</code></td>

271

<td>String</td>

272

<td><code>"title"</code></td>

273

<td>

274

<p>

275

CSS selector used to extract a page title from the content of a page loaded via Pjax.

276

</p>

277

278

<p>

279

By default this is set to extract the title from the <code><title></code> element, but you could customize it to extract the title from an <code><h1></code>, or from any other element, if that's more appropriate for the content you're loading.

280

</p>

281

</td>

282

</tr>

283

</tbody>

284

</table>

285

286

<h4 id="custom-selectors">Custom Selectors</h4>

287

288

<p>

289

Pjax's <code>contentSelector</code> and <code>titleSelector</code> config attributes allow you to customize how content and page titles are extracted from loaded pages, while the <code>linkSelector</code> attribute lets you customize which links on the page are loaded via Pjax.

290

</p>

291

292

<h5 id="contentselector"><code>contentSelector</code></h5>

293

294

<p>

295

By default, <code>contentSelector</code> is <code>null</code>, meaning that the entire contents of any loaded page will be inserted into the container node. This could be bad if the page includes a header and footer that shouldn't be displayed again. Specify a custom <code>contentSelector</code> to display only a portion of the loaded page.

296

</p>

297

298

<p>

299

Let's say we have an HTML page that looks like this:

300

</p>

301

302

303

<title>The Surprising Adventures of Sir Digby Chicken Caesar - Episode 1</title>

304

<body>

305

306

307

<h1>The Surprising Adventures of Sir Digby Chicken Caesar</h1>

308

</div>

309

310

311

<h2>Episode One</h2>

312

313

<p>

314

On a lonely planet spinning its way toward damnation amid the fear and

315

despair of a broken human race, who is left to fight for all that is

316

good and pure and gets you smashed for under a fiver? Yes, it's the

317

surprising adventures of me, Sir Digby Chicken Caesar!

318

</p>

319

</div>

320

321

322

<p>

323

324

</p>

325

</div>

326

</body></pre>

327

328

329

<p>

330

Since the header and footer are persistent across the site, we only want to display the content portion when this page is loaded via Pjax. All we need to do is set the <code>contentSelector</code> attribute to the appropriate CSS selector:

331

</p>

332

333

<pre class="code prettyprint">// Extract the contents of the '.episode-content' div from loaded pages and

334

// discard the rest.

335

new Y.Pjax({

336

container: '#content',

337

contentSelector: '.episode-content'

338

});</pre>

339

340

341

<h5 id="linkselector"><code>linkSelector</code></h5>

342

343

<p>

344

The <code>linkSelector</code> attribute allows you to customize which links Pjax will handle. By default, <code>linkSelector</code> is set to "a.yui3-pjax", which means that any <code><a></code> element with the class name "yui3-pjax" will be handled by Pjax. You could customize this to change the class name, or to limit Pjax to links inside a certain container, or anything else you can do with a CSS selector.

345

</p>

346

347

<h5 id="titleselector"><code>titleSelector</code></h5>

348

349

<p>

350

The <code>titleSelector</code> attribute allows you to customize how Pjax extracts a page title from loaded pages. By default, it's set to the selector string "title", which means it will extract the contents of the first <code><title></code> element on the loaded page. If desired, you could customize this selector to extract the title from an <code><h1></code> element, or any other element, or set it to <code>null</code> to prevent a title from being extracted.

351

</p>

352

353

<h3 id="pjax-events">Pjax Events</h3>

354

355

<table>

356

<thead>

357

<tr>

358

<th>Event</th>

359

<th>Description</th>

360

<th>Payload</th>

361

</tr>

362

</thead>

363

364

<tbody>

365

<tr>

366

<td><code>error</code></td>

367

<td>

368

<p>

369

Fired when an error occurs while attempting to load a URL.

370

</p>

371

</td>

372

<td>

373

<dl>

374

<dt><code>content</code> <em>(Object)</em></dt>

375

<dd>

376

<p>

377

Content extracted from the response, if any. This is an object with the following properties:

378

</p>

379

380

<dl>

381

382

<dd>

383

A <code>Y.Node</code> instance for a document fragment containing the extracted HTML content.

384

</dd>

385

386

<dt><code>title</code> <em>(String)</em></dt>

387

<dd>

388

The title of the HTML page, if any, extracted using the <code>titleSelector</code> attribute. If <code>titleSelector</code> is not set or if a title could not be found, this property will be <code>undefined</code>.

389

</dd>

390

</dl>

391

</dd>

392

393

<dt><code>responseText</code> <em>(String)</em></dt>

394

<dd>

395

Raw Ajax response text.

396

</dd>

397

398

<dt><code>status</code> <em>(Number)</em></dt>

399

<dd>

400

HTTP status code for the Ajax response.

401

</dd>

402

403

<dt><code>url</code> <em>(String)</em></dt>

404

<dd>

405

The absolute URL that failed to load.

406

</dd>

407

</dl>

408

</td>

409

</tr>

410

411

<tr>

412

413

<td>

414

<p>

415

Fired when a URL is successfully loaded.

416

</p>

417

</td>

418

<td>

419

<dl>

420

<dt><code>content</code> <em>(Object)</em></dt>

421

<dd>

422

<p>

423

Content extracted from the response, if any. This is an object with the following properties:

424

</p>

425

426

<dl>

427

428

<dd>

429

A <code>Y.Node</code> instance for a document fragment containing the extracted HTML content.

430

</dd>

431

432

<dt><code>title</code> <em>(String)</em></dt>

433

<dd>

434

435

</dd>

436

</dl>

437

</dd>

438

439

<dt><code>responseText</code> <em>(String)</em></dt>

440

<dd>

441

Raw Ajax response text.

442

</dd>

443

444

<dt><code>status</code> <em>(Number)</em></dt>

445

<dd>

446

HTTP status code for the Ajax response.

447

</dd>

448

449

<dt><code>url</code> <em>(String)</em></dt>

450

<dd>

451

The absolute URL that was loaded.

452

</dd>

453

</dl>

454

</td>

455

</tr>

456

457

<tr>

458

<td><code>navigate</code></td>

459

<td>

460

<p>

461

Fired when navigating to a URL via Pjax. This is a useful event to listen to if you want to add a visual loading indicator while content is loading.

462

</p>

463

</td>

464

<td>

465

<dl>

466

<dt><code>force</code> <em>(Boolean)</em></dt>

467

<dd>

468

<code>true</code> if enhanced navigation should occur even in browsers that don't support HTML5 history.

469

</dd>

470

471

<dt><code>originEvent</code> <em>(Event)</em></dt>

472

<dd>

473

The event that triggered navigation. Usually this will be a DOM click event.

474

</dd>

475

476

<dt><code>replace</code> <em>(Boolean)</em></dt>

477

<dd>

478

<code>true</code> if the current history entry will be replaced instead of a new entry being created.

479

</dd>

480

481

<dt><code>url</code> <em>(String)</em></dt>

482

<dd>

483

The URL being navigated to.

484

</dd>

485

</dl>

486

</td>

487

</tr>

488

</tbody>

489

</table>

490

491

<h2 id="optimizing-server-responses-for-pjax">Optimizing Server Responses for Pjax</h2>

492

493

<p>

494

While the Pjax Utility is capable of extracting and displaying small portions of loaded pages, it's much more efficient to avoid sending unnecessary content in the first place. With a little extra work on the server side, you can have the server recognize Pjax requests and send back only the relevant portion of the requested page.

495

</p>

496

497

<h3 id="x-pjax-http-header"><code>X-PJAX</code> HTTP Header</h3>

498

499

<p>

500

When the Pjax Utility makes an Ajax request to the server, it adds a special <code>X-PJAX</code> HTTP header to the request. You can check for the presence of this header on the server when handling the request to determine whether you should respond with a full page or a partial page.

501

</p>

502

503

<p>

504

A complete HTTP request generated by the Pjax Utility looks something like this:

505

</p>

506

507

508

GET /example.html?pjax=1 HTTP/1.1

509

Host: example.com

510

X-Requested-With: XMLHttpRequest

511

X-PJAX: true

512

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7

513

Accept: */*

514

Referer: http://example.com/index.html

515

Accept-Encoding: gzip,deflate,sdch

516

Accept-Language: en-US,en;q=0.8

517

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3

518

</pre>

519

520

<h3 id="pjax-query-parameter"><code>pjax</code> Query Parameter</h3>

521

522

<p>

523

When the <code>addPjaxParam</code> config attribute is <code>true</code> (the default), the Pjax Utility will add a <code>pjax=1</code> query parameter to the end of all URLs it requests. This serves two purposes:

524

</p>

525

526

<ol>

527

<li>

528

It provides an alternative to the <code>X-PJAX</code> HTTP header for determining whether a request was generated by the Pjax Utility.

529

</li>

530

531

<li>

532

It ensures that the browser caches Pjax responses separately from full page responses.

533

</li>

534

</ol>

535

536

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

537

538

<ul>

539

<li>

540

<p>

541

Pjax's partial page loads only work in browsers that support HTML5 history (most modern browsers do). In older browsers such as IE6 through IE9, pjax-enabled links will result in full page loads. This is by design, since it allows you to take advantage of the functionality supported by modern browsers while providing a graceful fallback for older browsers.

542

</p>

543

</li>

544

</ul>

545

</div>

546

</div>

547

</div>

548

549

550

551

552

553

554

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

555

</div>

556

557

558

559

<li>

560

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

561

</li>

562

<li>

563

<a href="#using-pjax">Using Pjax</a>

564

565

<li>

566

<a href="#quick-start">Quick Start</a>

567

</li>

568

<li>

569

<a href="#instantiating-pjax">Instantiating Pjax</a>

570

571

<li>

572

<a href="#as-a-plugin">As a Plugin</a>

573

</li>

574

<li>

575

<a href="#as-a-class">As a Class</a>

576

</li>

577

</ul>

578

</li>

579

<li>

580

<a href="#configuring-pjax">Configuring Pjax</a>

581

582

<li>

583

<a href="#config-attributes">Config Attributes</a>

584

</li>

585

<li>

586

<a href="#custom-selectors">Custom Selectors</a>

587

588

<li>

589

<a href="#contentselector"><code>contentSelector</code></a>

590

</li>

591

<li>

592

<a href="#linkselector"><code>linkSelector</code></a>

593

</li>

594

<li>

595

<a href="#titleselector"><code>titleSelector</code></a>

596

</li>

597

</ul>

598

</li>

599

</ul>

600

</li>

601

<li>

602

<a href="#pjax-events">Pjax Events</a>

603

</li>

604

</ul>

605

</li>

606

<li>

607

<a href="#optimizing-server-responses-for-pjax">Optimizing Server Responses for Pjax</a>

608

609

<li>

610

<a href="#x-pjax-http-header"><code>X-PJAX</code> HTTP Header</a>

611

</li>

612

<li>

613

<a href="#pjax-query-parameter"><code>pjax</code> Query Parameter</a>

614

</li>

615

</ul>

616

</li>

617

<li>

618

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

619

</li>

620

</ul>

621

</div>

622

</div>

623

624

625

626

627

628

</div>

629

</div>

630

</div>

631

</div>

632

633

634

635

636

</body>

637

</html>

Older »