Installation

``
npm install osh-pages
`

Usage

Consider the following files

`
server.js
routes.js
view-user.js
`

The contents of each are printed below; let's start with routes.js
as it should look the most familiar:

`js
module.exports = {
'view-user': {
path: '/users/',
params: {
username: /^[a-z]+$/
}
}

// other routes here...

};
`

Each entry in the route map is a config object for an
osh-route.

The module, view-user.js exports a page prototype, which defines
the lifecycle methods for a page.

`js
var request = require('superagent'); // isomorphic!..mostly

module.exports = {
/**
* Read data from various APIs. In this case, we
* pull some user data from a fictitious API.
*/
read: function(pages, done) {
var page = this;
request.get('https://api.mysite.com/users/' + this.props.username)
.end(function(res) {
page.setState({
fullname: (
res.ok ?
res.body.fullname :
'Unknown user'
),
title: (
res.ok ?
this.props.username :
'Not found'
)
});
done();
});
},

/**
* Not a lifecycle method; separated from renderToString and
* renderToDocument for code reuse.
*/
renderBody: function() {
return (
'

' + this.escape(this.state.fullname) + '

/**
* Lifecycle method. Enhance HTML with js in the browser.
*/
run: function() {
// Initialize onclick handlers and other goodies.
}
};
`

Finally, you serve the app using Express, and optionally use the built-in
bundler (based on dynapack) to
enable client-side AJAX rendering and navigation. The following is
server.js:

`js
var express = require('express');
var serveStatic = require('serve-static');
var Pages = require('osh-pages');

var app = express();

var pages = Pages({basedir: __dirname});

// Paths are relative to basedir
pages.routes('./routes');
pages.set('view-user', './view-user');
pages.bundle({
output: './bundles',
prefix: '/js/'
});

app.use(pages);
app.use('/js', serveStatic(__dirname + '/bundles'));

pages.on('bundled', function() {
app.listen(3333);
});
`

Documentation

$3

- options
- basedir: All configuration parameters that are specified as
relative paths are assumed relative to this directory.
- default: process.cwd()
- required: yes
- type: String
- routes: See documentation for routes().

Call this to create a new pages instance on the server; it returns
an express middleware function augmented with the following
setup methods.

#### pages.routes(path)

- path: Path to a module that exports a routes object; the sitemap.
Can be relative to basedir set in constructor.
- required: yes
- type: String

Example routes.js:

`js
module.exports = {
'user': {
path: '/users/',
params: {
username: /^[a-z]+$/
}
},
'article': {
path: '/articles/',
params: {
articleId: /^\w+$/
}
}
};
`

#### pages.set(name, page)

- name: The name of a route exported by the routes module given to
routes().
- type: String
- required: yes
- page: Path to a module that exports a Page prototype. Can
be relative to basedir set in constructor.
- type: String
- required: yes

Register page logic with a route. You need to register by way of a module
path so that Pages can bundle your javascript.

#### pages.fn(name, fn)

- name: The name of the server function.
- fn: The server function.
- Signature: fn(opts, done) where opts is POJO data and done is
a callback. Pass error and result as first and second arg, respectively,
to done.

Register a server function (or remote procedure) with the Pages instance. A
server function is callable within a Page's read/write methods and
runs on only the server (when called in the browser, an AJAX request handles
the function call for you, being careful to send and check a CSRF token
for security).

Use server functions when a task needs to be performed privately, like
authenticating with an OAuth2-capable API server.

Within the server function, this has the following properties:

- this.session: The current Session instance.

Example:

`js
pages.fn('refreshAccessToken', function(opts, done) {
// For persisting the refresh token.
var session = this.session;

request.post('https://api.api.api/oauth/token')
.auth('thewebs', 'sshh')
.send({
grant_type: 'refresh_token',
refresh_token: session.secrets.refreshToken
})
.end(function(err, res) {
if (err) done(err);
else {
session.setSecrets({refreshToken: res.body.refresh_token});
done(null, res.body.access_token);
}
});
});
`

#### pages.bundle(opts)

- options
- output: Output directory for bundles. Can be relative to basedir.
- type: String
- default: '/bundles'
- prefix: Prefix for script urls. If serving scripts from the same
express app that houses the pages instance, this value should match
the mount path (with a trailing slash).

Bundle up javascript using Dynapack.
Options are passed to Dynapack after resolving any relative paths.

When bundling has finished, the 'bundled' event is fired on the pages
instance.

Example:

`js
pages.bundle({
output: __dirname + '/bundles',
prefix: '/js/'
});

app.use(pages);
app.use('/js', serveStatic(__dirname + '/bundles'));

pages.on('bundled', function() {
app.listen(3333);
});
`

Page

A Page prototype registered with the pages.set() method
should implement the following API. Lifecycle methods are required to do
anything useful.

$3

These methods should be defined on a Page prototype. Just remember,
read/write/render/run/fun/profit/glory/gratitude/humility (that got out of
hand...).

#### read(pages, render)

Called on a GET request for the Page.

Using information in this.props and the given pages object, gather data
from APIs and make calls to this.setState(state) to prepare the page for
rendering. Call the render callback without arguments when ready to render
the page.

The pages object contains the following properties to help with optimization
and managing session state:

- pages.session: The current Session instance.
- pages.current: The currently rendered page. If you are not managing your
own caching, use this to migrate state from the old page to the
new page without requerying an API. The only properties available are:
- pages.current.name
- pages.current.props
- pages.current.state

It also houses every server function registered with
pages.fn().

The render callback doubles as a redirector; passing it either a URI or a
name/props pair will skip rendering of the current page and either send a 302
response (if running on the server) or begin an AJAX GET of the indicated page
(if running in the browser). For example, if there was an error fetching data
from an API, you can redirect to a not-found page via:

`js
module.exports = {
read: function(pages, render) {
var page = this;
var session = pages.session;
var current = pages.current;

if (current && current.props.username === 'beatrix') {
this.setState({
user: current.state.user
});
render();
}
else {
api.getUser('beatrix', function(err, user) {
if (err) {
render('404', {msg: err.message});
// Assuming the '404' route path is simply: '/not-found', the
// following would be equivalent:
//render('/not-found?msg=' + encodeURIComponent(err.message));
}
else {
page.setState({user: user});
render();
}
});
}
}

// ...
};
`

where '404' is the name of a route.

#### write(pages, redirect)

Called when the page is POSTed to. This method stands alone; render
methods are not called after write, because pages should not be returned from
POST requests, only redirects (see this wonderful treatise on the
topic). It is
possible to have a page prototype that consists only of a write method (do
this to create a route that serves only POST requests).

The pages object contains the following properties to help with
managing session state:

- pages.session: The current Session instance.

It also houses every server function registered with
pages.fn().

Inside the write method, this.payload is used to access the data that was
POSTed from the form. Standard urlencoded forms will result in a simple
this.payload object, where keys are form input names. For example, submission
of the form:

`html




`

`js
module.exports = {
// ...

renderToString: function() {
return (
'' +
'' +
this.escape(this.renderTitle()) +
'' +
'' +
this.renderBody() +
this.renderAjax() +
''
''
);
}
};
`

#### render(pages)

Update the document to show the current page. A very basic implementation
(that would defeat the purpose of AJAX navigation) might be:

`js
module.exports = {
// ...

renderBody: function(pages) {
return 'so much html...';
},

render: function(pages) {
document.body.innerHTML = this.renderBody(pages);
document.title = this.renderTitle();
}
};
`

A more performant version would find the smallest difference between the
currently rendered page and the page to render, and update only those elements
of the document that need it. ReactJS provides automatic DOM diffing and is a
good choice here (in fact, this library was built with React rendering in
mind); in principle, any DOM diffing/rendering tool would work here.

Event handlers should not be attached to the document in this step. Instead
they should be attached in the run() lifecycle method, which gets called both
on initial page load and after each AJAX render. In general, it is okay to push
rendering into the run method (at the risk of re-rendering your initial page),
but not okay to push progressive enhancement into the render method.

*Note: In the case of a view library like React, which provides rendering and
progressive enhancement, simply defer rendering to run() (although
setting some DOM, like document.title, might be more appropriate for
render()). Up to you.*

#### recoverState(pages)

If stashing was disabled in Page.read(), the state that
was not stashed should be recovered from the server-rendered HTML in this
method. This is called once per browser session, on initial page load.

For example, an API might return a large chunk of raw HTML. Rather than
use the automatic Pages stashing and recovery, it would be more efficient
to read the HTML from the document on initial page load.

Example:

`js
module.exports = {
read: function(pages, render) {
var page = this;

// Important... see this later in the docs. Turns off all
// stashing.
page.stash(false);

request.get('https://api.blog.com/posts/42')
.end(function(res) {
page.setState({
blogPost: res.body
});
render();
});
},

renderToString: function(pages) {
return: (
'

run: function(pages) {
// and we have it...
console.log(this.state.blogPost);
}
};
`

#### run(pages)

Attach event handlers to the DOM. Or use a view library (like ReactJS) that
handles progressive enhancement, DOM diffing/rendering, and event handling.

$3

These methods are used from within the lifecycle methods described above.

#### setState(state)

Call this in Page.read() to set downloaded state on
the page instance.

#### stash(boolean)

Toggle stashing of state set with setState(). By default,
stashing is turned on, so that all the state set in a Page's read lifecycle
method is available in the browser on initial page load (without the need for
requerying APIs).

#### renderAjax()

Call this in renderToString to enable AJAX/progressive enhancement. It
includes