History

HTML5 history and PJAX helper to create dynamic experiences

Using the Wee History feature you can make partial DOM replacements while manipulating the URL to create smooth, efficient navigation.

Bind

Bind element events and form submit events to PJAX

VariableTypeDefaultDescriptionRequired

events

object

-

{event: selector} object to bind

a

object, selection

-

Context or same options available to go method

context

selection

document

Context selection

Basic

Wee.history.bind({
    click: 'a',
    submit: '.element'
});

Advanced

Wee.history.bind({
        click: 'a:not([data-static])'
    },
    'ref:element',
    {
        extensions: [
            'html',
            'php',
        ],
        partials: 'title, .js-sidebar, ref:inner',
        request: {
            root: '/pjax',
            success: function() {
                ga('send', 'pageview');
            }
        }
    }
});

Go

Navigate to a new path or within the browser history

VariableTypeDefaultDescriptionRequired

options

object

-

Object properties below

Options Object

VariableTypeDefaultDescriptionRequired

action

string

'replace'

Either 'replace' or 'append' content

extensions

array

-

Whitelist of path extensions to support

partials

selection

'title, main'

Elements to replace from response

path

string

-

Path to local resource

processErrors

boolean

false

Process replacements on error responses

push

boolean

true

Push the path to the browser URL

request

object

-

Pass-through object to Wee.data

run

boolean

true

Evaluate routing rules

scrollTop

number, selection

0

Vertical offset to scroll

title

string

-

Set or override the returned page title

Basic

Wee.history.go({
    path: '/page/path'
});

Advanced

Wee.history.go({
    path: '/page/path',
    partials: '.element',
    request: {
        complete: function() {
            // Complete logic
        }
    }
});

Init

Set the initial state and popstate event, and bind global actions

VariableTypeDefaultDescriptionRequired

options

object

-

Object properties below

Options Object

VariableTypeDefaultDescriptionRequired

bind

object, boolean

-

Bind object format

extensions

array

-

Whitelist of path extensions to support

partials

selection

'title, main'

Elements to replace from response

processErrors

boolean

false

Process replacements on error responses

push

boolean

true

Push the path to the browser URL

request

object

-

Pass-through object to Wee.data

run

boolean

true

Evaluate routing rules

begin

object

-

Before request is made

replace

object

-

Manipulations to returned html can be made here before replacement

Default

Wee.history.init();

Advanced

Wee.history.init({
    bind: {
        click: 'a:not([data-static])'
    },
    extensions: [
        'html',
        'php',
    ],
    partials: 'title, .js-sidebar, ref:inner',
    processErrors: true,
    request: {
        root: '/pjax',
        success: function() {
            ga('send', 'pageview');
        }
    }
});

Lifecycle

The following events are available in this order at different stages throughout the History lifecycle.

options.begin(config); // return false to abort process
options.replace(html); // before replacement is made
options.request.send(); // before actual request is made
options.request.success(data); // logic to execute on if request is successful
options.request.error(xhr); // logic for handling errors returned during request
options.request.complete(xhr); // logic to remove any css modifer classes
options.pushstate({
    dir: [-1, 1],
    path: 'string',
    prev: 'string'
});
options.popstate({
    dir: [-1, 1],
    path: 'string',
    prev: 'string'
});
options.complete({
    dir: [-1, 1],
    path: 'string',
    prev: 'string'
});

Lifecycle

The following events are available in this order at different stages throughout the History lifecycle.

All examples below could use Wee.history.go as well.

Begin

Triggers before any history state or data request occurs. Returning false will halt process entirely.

Wee.history.init({
    ...
    begin: function(config) {
        // config is the entire configuration object passed into init method
    }
});

Send

Triggers when data request is initially sent.

Wee.history.init({
    ...
    request: {
        send: function() {
            //...
        }
    }
});

Replace

Triggers once HTML from data request is received but before the received markup is placed onto the DOM. Returned HTML is passed as parameter to this method. The return value will be treated as the HTML to be appended to DOM. If return value is js false, HTML will be prevented from being appended.

Wee.history.init({
    ...
    replace: function(html, config) {
        //...optionally modify html

        return html;
    }
});

Success

Triggers when the data request is returned successfully and after markup has been replaced on DOM.

Wee.history.init({
    ...
    request: {
        success: function(html, xhr) {
            //...
        }
    }
});

Error

Triggers when the data request is not returned successfully.

Wee.history.init({
    ...
    request: {
        error: function(xhr) {
            //...
        }
    }
});

Complete

Triggers when the data request is returned successfully and after either the success or error callback fires.

Wee.history.init({
    ...
    request: {
        complete: function(xhr) {
            //...
        }
    }
});

Pushstate

Triggers when new history entry is added to browser history.

Wee.history.init({
    ...
    push: true, // Default is true
    pushstate: function(history) {
        history.dir // Browser navigation direction (1)
        history.path // New URL path
        history.prev // Old URL path
    }
});

Popstate

Triggers when a history entry is changed.

Wee.history.init({
    ...
    pop: true,
    popstate: function(history) {
        history.dir // Browser navigation direction (-1 or 1)
        history.path // New URL path
        history.prev // Old URL path
    }
});

End

Triggers at the very end of process.

Wee.history.init({
    ...
    end: function(history) {
        history.dir // Browser navigation direction (-1 or 1)
        history.path // New URL path
        history.prev // Old URL path
    }
});