Skip to content

Document the pjax options #433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 10, 2014
Merged

Document the pjax options #433

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c7fc4fc
Fix curl download instructions
mislav Sep 9, 2014
ab71fed
Improve pjax function synopsis and :memo: the options
mislav Sep 9, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 35 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ Or add `jquery-pjax` to your apps `bower.json`.
pjax can be downloaded directly into your app's public directory - just be sure you've loaded jQuery first.

```
curl -O https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js
curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js
```

**WARNING** Do not hotlink the raw script url. GitHub is not a CDN.
Expand Down Expand Up @@ -136,16 +136,40 @@ Or try this selector that matches any `<a data-pjax href=>` links inside a `<div
$(document).pjax('[data-pjax] a, a[data-pjax]', '#pjax-container')
```

When invoking `$.fn.pjax` there are a few different argument styles you can use:
#### Arguments

1. `$(document).pjax(delegation selector, options object)`
2. `$(document).pjax(delegation selector, container selector, options object)`
The synopsis for the `$.fn.pjax` function is:

In other words:
``` javascript
$(document).pjax(selector, [container], options)
```

1. `selector` is a string to be used for click [event delegation][$.fn.on].
2. `container` is a string selector that uniquely identifies the pjax container.
3. `options` is an object with keys described below.

##### pjax options

key | default | description
----|---------|------------
`timeout` | 650 | ajax timeout in milliseconds after which a full refresh is forced
`push` | true | use [pushState][] to add a browser history entry upon navigation
`replace` | false | replace URL without adding browser history entry
`maxCacheLength` | 20 | maximum cache size for previous container contents
`version` | | a string or function returning the current pjax version
`scrollTo` | 0 | vertical position to scroll to after navigation
`type` | `"GET"` | see [$.ajax][]
`dataType` | `"html"` | see [$.ajax][]
`container` | | CSS selector for the element where content should be replaced
`url` | link.href | a string or function that returns the URL for the ajax request
`target` | link | eventually the `relatedTarget` value for [pjax events](#events)
`fragment` | `"body"` | CSS selector for the fragment to extract from ajax response

You can change the defaults globally by writing to the `$.pjax.defaults` object:

1. The first argument must always be a `String` selector used for delegation.
2. The second argument can either be a `String` container selector or an options object.
3. If there are three arguments the second must be the `String` container selector and the third must be the options object.
``` javascript
$.pjax.defaults.timeout = 1200
```

### `$.pjax.click`

Expand Down Expand Up @@ -406,3 +430,6 @@ $ open http://localhost:4567/

[compat]: http://caniuse.com/#search=pushstate
[gist]: https://gist.github.com/
[$.fn.on]: http://api.jquery.com/on/
[$.ajax]: http://api.jquery.com/jQuery.ajax/
[pushState]: https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history#Adding_and_modifying_history_entries