iLoveElysia/pjax
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

More README cleanup

Browse Source
This commit is contained in:
Robin North
2018-01-30 17:44:04 +00:00
parent 5ec0ce09e1
commit 9971c4c4f0
1 changed files with 50 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
README.md
View File

@@ -2,7 +2,7 @@
[![Build Status](http://img.shields.io/travis/MoOx/pjax.svg)](https://travis-ci.org/MoOx/pjax). [![Build Status](http://img.shields.io/travis/MoOx/pjax.svg)](https://travis-ci.org/MoOx/pjax).
> Easily enable fast AJAX navigation on any website (using pushState + XHR) > Easily enable fast AJAX navigation on any website (using pushState() + XHR)
Pjax is ~~a jQuery plugin~~ **a standalone JavaScript module** that uses Pjax is ~~a jQuery plugin~~ **a standalone JavaScript module** that uses
AJAX (XmlHttpRequest) and AJAX (XmlHttpRequest) and
@@ -10,7 +10,7 @@ AJAX (XmlHttpRequest) and
to deliver a fast browsing experience. to deliver a fast browsing experience.
_It allows you to completely transform the user experience of standard websites _It allows you to completely transform the user experience of standard websites
(server side generated or static ones) to make them feel like they are browsing an app, (server-side generated or static ones) to make them feel like they are browsing an app,
especially for users with low bandwidth connection._ especially for users with low bandwidth connection._
**No more full page reloads. No more multiple HTTP requests.** **No more full page reloads. No more multiple HTTP requests.**
@@ -21,7 +21,7 @@ especially for users with low bandwidth connection._
## Installation ## Installation
- You can install pjax from **npm**: - You can install Pjax from **npm**:
```shell ```shell
npm install pjax npm install pjax
``` ```
@@ -37,24 +37,26 @@ especially for users with low bandwidth connection._
## No dependencies ## No dependencies
_There is nothing you need. No jQuery or anything else._ _Pjax does not rely on other libraries, like jQuery or similar. It is written entirely in vanilla JS._
## How Pjax works ## How Pjax works
Pjax loads pages using AJAX & updates the browser's current url using pushState without reloading your page's layout or any resources (JS, CSS), giving a fast page load. Pjax loads pages using AJAX and updates the browser's current URL using `pushState()` without reloading your page's layout or any resources (JS, CSS), giving a fast page load.
_But under the hood, it's just ONE HTTP request with a pushState() call._
Obviously, for [browsers that don't support pushState()](http://caniuse.com/#search=pushstate) Pjax gracefully degrades and does not do anything at all.
It simply works with all permalinks & can update all parts of the page you _But under the hood, it's just ONE HTTP request with a `pushState()` call._
Obviously, for [browsers that don't support `history.pushState()`](http://caniuse.com/#search=pushstate) Pjax gracefully degrades and does not do anything at all.
It simply works with all permalinks and can update all parts of the page you
want (including HTML metas, title, and navigation state). want (including HTML metas, title, and navigation state).
- It's not limited to one container, like jQuery-Pjax is. - It's not limited to one container, like jQuery-Pjax is.
- It fully supports browser history (back & forward buttons). - It fully supports browser history (back and forward buttons).
- It supports keyboard browsing. - It supports keyboard browsing.
- Automatically falls back to classic navigation for external pages (thanks to Capitain Obvious's help). - Automatically falls back to standard navigation for external pages (thanks to Captain Obvious's help).
- Automatically falls back to classic navigation for internal pages that do not have an appropriate DOM tree. - Automatically falls back to standard navigation for internal pages that do not have an appropriate DOM tree.
- You can add pretty cool CSS transitions (animations) very easily. - You can add pretty cool CSS transitions (animations) very easily.
- It's around 4kb (minified & gzipped). - It's around 4kb (minified and gzipped).
### Under the hood ### Under the hood
@@ -62,9 +64,9 @@ want (including HTML metas, title, and navigation state).
- When an internal link is clicked, Pjax grabs HTML from your server via AJAX. - When an internal link is clicked, Pjax grabs HTML from your server via AJAX.
- Pjax renders the page's DOM tree (without loading any resources - images, CSS, JS...). - Pjax renders the page's DOM tree (without loading any resources - images, CSS, JS...).
- It checks that all defined parts can be replaced: - It checks that all defined parts can be replaced:
- if the page doesn't meet the requirements, classic navigation is used. - If the page doesn't meet the requirements, standard navigation is used.
- if page meets the requirements, Pjax does all defined DOM replacements. - If the page meets the requirements, Pjax does all defined DOM replacements.
- Then, it updates the browser's current URL using pushState. - Then it updates the browser's current URL using `pushState()`.
## Overview ## Overview
@@ -106,20 +108,20 @@ new Pjax({ selectors: ["title", ".my-Header", ".my-Content", ".my-Sidebar"] })
Now, when someone in a Pjax-compatible browser clicks "blah", the content of all selectors will be replaced with the one found in the "blah" content. Now, when someone in a Pjax-compatible browser clicks "blah", the content of all selectors will be replaced with the one found in the "blah" content.
_Magic! For real!_ **There is completely no need to do anything on server side!** _Magic! For real!_ **There is no need to do anything server-side!**
## Differences with [jQuery-pjax](https://github.com/defunkt/jquery-pjax) ## Differences with [jQuery-pjax](https://github.com/defunkt/jquery-pjax)
- No jQuery dependency - No jQuery dependency
- Not limited to a container - Not limited to a container
- No server side requirements - No server-side requirements
- Works for CommonJS environment (browserify), AMD (RequireJS) or even globally - Works for CommonJS environment (Webpack/Browserify), AMD (RequireJS) or even globally
- Allow page transition with CSS animations - Allow page transition with CSS animations
- Can be easily tweaked, since every method is public (and as a result, overridable) - Can be easily tweaked, since every method is public (and as a result, overridable)
## Compatibility ## Compatibility
Pjax only works with [browsers that support the `history.pushState` API](http://caniuse.com/#search=pushstate). Pjax only works with [browsers that support the `history.pushState()` API](http://caniuse.com/#search=pushstate).
When the API isn't supported, Pjax goes into fallback mode (and it just does nothing). When the API isn't supported, Pjax goes into fallback mode (and it just does nothing).
To see if Pjax is actually supported by your browser, use `Pjax.isSupported()`. To see if Pjax is actually supported by your browser, use `Pjax.isSupported()`.
@@ -140,10 +142,10 @@ new Pjax({
This will enable Pjax on all links, and designate the part to replace using CSS selectors `"title", ".my-Header", ".my-Content", ".my-Sidebar"`. This will enable Pjax on all links, and designate the part to replace using CSS selectors `"title", ".my-Header", ".my-Content", ".my-Sidebar"`.
For some reason, you might want to just target some elements to apply Pjax behavior. For some reason, you might want to just target some elements to apply Pjax behavior.
In that case, you can 2 differents things: In that case, you can do two different things:
- use a custom selector like "a.js-Pjax" or ".js-Pjax a" depending on what you want. - Use a custom selector like "a.js-Pjax" or ".js-Pjax a" depending on what you want.
- override `Pjax.prototype.getElements` that just basically `querSelectorAll` the `elements` option. In this function you just need to return a `NodeList`. - Override `Pjax.prototype.getElements` that just basically `querySelectorAll` the `elements` option. In this function you just need to return a `NodeList`.
```js ```js
// use case 1 // use case 1
@@ -189,11 +191,11 @@ Example of what you can do:
This example is correct and should work "as expected". This example is correct and should work "as expected".
_If the current page and new page do not have the same amount of DOM elements, _If the current page and new page do not have the same amount of DOM elements,
Pjax will fallback to normal page load._ Pjax will fall back to normal page load._
##### `switches` (Object, default: `{}`) ##### `switches` (Object, default: `{}`)
Objects containing callbacks that can be used to switch old element with new element. Objects containing callbacks that can be used to switch old elements with new elements.
Keys should be one of the defined selectors. Keys should be one of the defined selectors.
Examples: Examples:
@@ -219,17 +221,17 @@ Callbacks are bound to Pjax instance itself to allow you to reuse it (ex: `this.
###### Existing switches callback ###### Existing switches callback
- `Pjax.switches.outerHTML`: default behavior, replace elements using outerHTML - `Pjax.switches.outerHTML`: default behavior, replace elements using outerHTML
- `Pjax.switches.innerHTML`: replace elements using innerHTML & copy className too - `Pjax.switches.innerHTML`: replace elements using innerHTML and copy className too
- `Pjax.switches.sideBySide`: smart replacement that allows you to have both elements in the same parent when you want to use CSS animations. Old elements are removed when all children have been fully animated ([animationEnd](http://www.w3.org/TR/css3-animations/#animationend) event triggered) - `Pjax.switches.sideBySide`: smart replacement that allows you to have both elements in the same parent when you want to use CSS animations. Old elements are removed when all children have been fully animated ([animationEnd](http://www.w3.org/TR/css3-animations/#animationend) event triggered)
###### Create a switch callback ###### Create a switch callback
Your function can do whatever you want, but you need to: Your function can do whatever you want, but you need to:
- replace oldEl content by newEl content in some fashion - replace `oldEl`'s content with `newEl`'s content in some fashion
- call `this.onSwitch()` to trigger the attached callback. - call `this.onSwitch()` to trigger the attached callback.
Here is the default behavior as example Here is the default behavior as an example:
```js ```js
function(oldEl, newEl, pjaxRequestOptions, switchesClasses) { function(oldEl, newEl, pjaxRequestOptions, switchesClasses) {
@@ -240,7 +242,7 @@ function(oldEl, newEl, pjaxRequestOptions, switchesClasses) {
##### `switchesOptions` (Object, default: `{}`) ##### `switchesOptions` (Object, default: `{}`)
These are options that can be used during switch by switchers ( for now, only `Pjax.switches.sideBySide` uses it). These are options that can be used during switch by switchers (for now, only `Pjax.switches.sideBySide` uses it).
This is very convenient when you use something like [Animate.css](https://github.com/daneden/animate.css) This is very convenient when you use something like [Animate.css](https://github.com/daneden/animate.css)
with or without [WOW.js](https://github.com/matthieua/WOW). with or without [WOW.js](https://github.com/matthieua/WOW).
@@ -336,7 +338,7 @@ The following CSS will be required to make something nice:
} }
``` ```
To get understand this CSS, here is an HTML snippet: To give context to this CSS, here is an HTML snippet:
```html ```html
<!doctype html> <!doctype html>
@@ -366,16 +368,16 @@ To get understand this CSS, here is an HTML snippet:
##### `history` (Boolean, default: `true`) ##### `history` (Boolean, default: `true`)
Enable pushState. Disabling this will prevent Pjax from controlling the history. Enable the use of `pushState()`. Disabling this will prevent Pjax from updating browser history.
However, there is almost no use case where you would want to do that. However, there is almost no use case where you would want to do that.
Internally, this option is used when a `popstate` event triggers Pjax (to not pushState again). Internally, this option is used when a `popstate` event triggers Pjax (to not `pushState()` again).
##### `analytics` (Function|Boolean, default: a function that pushes `_gaq` `_trackPageview` or sends `ga` `pageview` ##### `analytics` (Function|Boolean, default: a function that pushes `_gaq` `_trackPageview` or sends `ga` `pageview`
Function that allows you to add behavior for analytics. By default it tries to track Function that allows you to add behavior for analytics. By default it tries to track
a pageview with Google Analytics (if it exists on the page). a pageview with Google Analytics (if it exists on the page).
It's called every time a page is switched, even for history buttons. It's called every time a page is switched, even for history navigation.
Set to `false` to disable this behavior. Set to `false` to disable this behavior.
@@ -410,8 +412,6 @@ Pjax fires a number of events regardless of how it's invoked.
All events are fired from the _document_, not the link that was clicked. All events are fired from the _document_, not the link that was clicked.
#### Ajax related events
* `pjax:send` - Fired after the Pjax request begins. * `pjax:send` - Fired after the Pjax request begins.
* `pjax:complete` - Fired after the Pjax request finishes. * `pjax:complete` - Fired after the Pjax request finishes.
* `pjax:success` - Fired after the Pjax request succeeds. * `pjax:success` - Fired after the Pjax request succeeds.
@@ -426,12 +426,13 @@ document.addEventListener('pjax:complete', topbar.hide)
#### Note about DOM ready state #### Note about DOM ready state
Most of the time, you have code attached & related to the current DOM, that you only execute when page/DOM is ready. Most of the time, you will have code related to the current DOM that you only execute when the DOM is ready.
Since Pjax doesn't magically re-execute your previous code each time you load a page, you need to add some simple code to re-execute the appropriate code:
Since Pjax doesn't magically re-execute your previous code each time you load a page, you need to add some simple code to achieve this:
```js ```js
function whenDOMReady() { function whenDOMReady() {
// do you stuff // do your stuff
} }
whenDOMReady() whenDOMReady()
@@ -441,17 +442,18 @@ new Pjax()
document.addEventListener("pjax:success", whenDOMReady) document.addEventListener("pjax:success", whenDOMReady)
``` ```
_Note: Don't create the Pjax in the `whenDOMReady` function._ _Note: Don't create the Pjax instance in the `whenDOMReady` function._
For my concern & usage, I `js-Pjax`ify all body children, including stuff like navigation & footer (to get navigation state easily updated). For my concern and usage, I `js-Pjax`-ify all body children, including stuff like navigation and footer (to get navigation state easily updated).
So attached behavior is re-executed each time a page is loaded, like in the snippet above.
The attached behavior is re-executed each time a page is loaded, like in the snippet above.
If you want to just update a specific part (it's totally a good idea), you can just If you want to just update a specific part (it's totally a good idea), you can just
add the DOM related code in a function & re-execute this function when "pjax:success" event is done. add the DOM-related code in a function and re-execute this function when "pjax:success" event is fired.
```js ```js
// do your global stuff // do your global stuff
//... dom ready blah blah //... DOM ready blah blah
function whenContainerReady() { function whenContainerReady() {
// do your container related stuff // do your container related stuff
@@ -470,12 +472,12 @@ document.addEventListener("pjax:success", whenContainerReady)
### Q: Disqus doesn't work anymore, how can I fix that ? ### Q: Disqus doesn't work anymore, how can I fix that ?
A: There is a few things you need to do: A: There is a few things you need to do:
- wrap your Disqus snippet into a dom element that you will add to the `selector` - wrap your Disqus snippet into a DOM element that you will add to the `selector`
property (or just wrap it with `class="js-Pjax"`) & be sure to have at least the empty property (or just wrap it with `class="js-Pjax"`) and be sure to have at least the empty
wrapper on each page (to avoid differences of DOM between pages) wrapper on each page (to avoid differences of DOM between pages)
- edit your Disqus snippet like the one below - edit your Disqus snippet like the one below
#### Disqus snippet before pjax integration #### Disqus snippet before Pjax integration
```html ```html
<script> <script>
@@ -493,8 +495,8 @@ wrapper on each page (to avoid differences of DOM between pages)
#### Disqus snippet after Pjax integration #### Disqus snippet after Pjax integration
```html ```html
<div class="js-Pjax"><!-- need to be here on every pjaxified page, even if empty --> <div class="js-Pjax"><!-- needs to be here on every Pjax-ified page, even if empty -->
<!-- if (blah blah) { // eventual server side test to know wheter or not you include this script --> <!-- if (blah blah) { // eventual server-side test to know whether or not you include this script -->
<script> <script>
var disqus_shortname = 'YOURSHORTNAME' var disqus_shortname = 'YOURSHORTNAME'
var disqus_identifier = 'PAGEID' var disqus_identifier = 'PAGEID'
@@ -524,7 +526,7 @@ wrapper on each page (to avoid differences of DOM between pages)
</div> </div>
``` ```
**Note: The thing you need to understand is that Pjax handles inline `<script>` only for container you are reloading.** **Note: Pjax only handles inline `<script>` blocks for the container you are switching.**
--- ---