Wee

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

Variable Type Default Description Required
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

Variable Type Default Description Required
options object - Object properties below ✔

Options Object

Variable Type Default Description Required
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

Variable Type Default Description Required
options object - Object properties below -

Options

Variable Type Default Description Required
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 htmlreturn 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
    }
});

← Routes →