@rstacruz/repage

repage.js

Extensions to visionmedia/page.js, an Express-inspired client-side router.

Basic usage

Use repage as you typically would use page.js. (This new page object is a decorated version of the original page.js page.)

var page = require('repage');

page('/', index);
page('/user/:user', show);
page('/user/:user/edit', edit);
page('/user/:user/album', album);
page('/user/:user/album/sort', sort);
page('*', notfound);
page();

Quick reference

The new page object implements all the API of visionmedia/page.js, plus other convenient extensions described later. As such, refer to the page.js API first.

// routing:
page('/', index)           // calls `index()` when navigating to /
page('*', notfound)        // calls `notfound()` for all pages
page.base('/blog')         // sets the base path

// navigation:
page('/users')             // navigate to /users
page.replace('/users')     // replaces the current state with /users

These are features only available in repage.js:

page('/user/:id', { id: 20 })           // navigates to /user/20
page('/search', { q: 'hello' })         // navigates to /search?q=hello
page.replace('/search', { q: 'hello' }) // navigates by replacing

page.uri('/user/:id', { id: 20 })       // returns "/user/20" (string)
page.redirect('/users')                 // redirects to /users from a route

page.back()                             // goes back, or returns home if available

Installation

Via npm or bower

The npm version lists page.js as a dependency, while the bower version ships as a standalone .js file.

$ npm install --save @rstacruz/repage
$ bower install --save @rstacruz/repage

Standalone

Download or hotlink: repage.js. It will then be exported as window.page.

API

page()

page([options])

Starts the page.js engine by binding event listeners to dispatch routes. See page.js API for details.

var page = require('repage');
page('/', index);
page('/user/:user', show);
page('*', notfound);
page();

page(path)

page(path, [params])

Navigate to the given path.

$('.view').click(function (e) {
  e.preventDefault();
  page('/user/12');
});

You may also specify params for params to be replaced in the paths placeholders. (Only in repage.js)

page('/user/:id', { id: 12 });
// same as `page('/user/12')`

replace()

page.replace(path, [params])

Works like page(path), but replaces the current state instead of pushing it. Great for form submission pages.

You may also specify params for params to be replaced in the paths placeholders, like in page('path'). (Only in repage.js)

$('.submit').on('click', function () {
  $.post('/submit', function (article) {
    alert("data saved");
    page.replace('/article/:id', { id: article.id });
  });
});

len

page.len

Number of pages navigated to. (Only in repage.js)

page.len == 0;
page('/login');
page.len == 1;

uri()

page.uri(path, options)

Builds a URI path with dynamic parameters, mimicking Express's conventions. (Only in repage.js)

page.uri('/api/users/:id', { id: 24 });
=> "/api/users/24"

Also builds query strings.

page.uri('/api/trip/:id', { id: 24, token: 'abcdef' });
=> "/api/trip/24?token=abcdef"

Great for using with req.params or req.query.

querystring()

page.querystring(data)

Converts an object into a query string. (Only in repage.js)

page.querystring({ name: 'john smith', count: 3 })
=> "name=john%20smith&count=3"

back()

page.back([path])

Goes back. If path is given, it will navigate to that instead when there's no page to go back to. (Only in repage.js)

document.getElementById('back').onclick = function() {
  // either goes back, or returns to the homepage when there's
  // no page to go back to.
  page.back('/');
};

redirect()

page.redirect(path, params)

Navigates to path. Works like page(path) or page.replace(), but suitable to be used inside a route. (Only in repage.js)

page('/login', function (ctx) {
  page.redirect('/sessions/new');
});

page('/dashboard', function (ctx) {
  if (!authenticated)
    page.redirect('/login');
});

teardown()

page.teardown()

Removes all traces of repage.js. Mostly useful in tests.

Thanks

repage.js © 2014+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz