Sparou provides "just enough structure" to navigate a single page web application.
Sparou includes a simple router. It supports URL templates with named parts, and allows you to order routes by precedence. A route is associated with a page name, and is used to resolve which page is being requested.
The router is bi-directional. It can resolve page name and parameters from URLs, and it can generate URLs from a page name and parameters. The router also parses and exposes query string parameters, but cannot route based on them.
A page is an object with some hooks on it. When a page is requested, Sparou will perform the following steps:
canUnloadon the currently loaded page. If this function returns
false, nothing more happens. If there is no current page, the current page does not implement
canUnload, or the current page's
canUnloadreturns anything other than
false, Sparou continues with unloading the current page.
onUnloadon the current page, if there is one (and it defines the
onUnloadhook). This allows for performing state cleanup before loading a new URL.
onLoadon the page matching the new URL. The routing resolution is passed as an argument.
Create an application navigator. The prefix is optional, and can be set if your
application is not served from the host root (e.g. your app is at
Load the new URL.
loadURL, but also push the
url to the browser.
Use the bi-directional router to generate a URL from the page name and parameters.
Returns the URL corresponding to the current page and current query parameters.
You can modify the location
query and have it reflected in the URL returned
nav;nav; // ...?id=42
Add some URL query parameters. This will cause the app to refresh with the new query parameters included in the URL. The new URL will also be loaded in the browser.
Kick things off by loading
The user navigated to this page.
location is described with the router below.
false to stop the user from navigating away from this page. Useful if
there is unsaved changes etc. The user will probably appreciate it if you
provide a visual clue that the navigation was prevented.
Called before leaving this page to load another. Can be used to clean up page-specific state etc.
The router is not exposed directly, although it is completely possible to use it on its own if desired.
Creates a routing table.
routes is an array of routes, where each route is a
[pageName, urlTemplate]. The
prefix can be used to ignore static
URL prefixes, e.g. to target a URL like
/my/app/news/23 with the route
/news/:id and the prefix
Produces a URL string from a path and a query parameter object.
Generates the URL to the given page type with the given parameters.
Returns the matching page from the routing table for the giving URL. If no route
matches, it returns
null. The location description includes the following
The name of the matching page.
The URL matched against.
Only the path part of the URL matched against.
Parameters matched from the route. Any
:paramName placeholder from URL
templates are included. For instance, if the matching route was
params will contain the
The query string, parsed into an object.