plob

plob is a simple(ish) SPA (single-page application) state manager, which handles page loading & url changing for you.

Getting Started

Add the package via either NPM or a direct link in the head tag.

npm install plob

const plob = require('plob')

CDN (or similar for local hosting):

<script src="https://cdn.jsdelivr.net/npm/plob@latest/src/plob.min.js"></script>

Now, you can simply start plob with the following:

plob.start()

This can be run at any time, but will wait for the DOM content to load before actually starting if it hasn't loaded already.

Links

Any a tag with a path within the root path specifified in the options will automatically be overridden. Basically, you don't have to do anything.

If you're adding a link after plob has started, run plob._override() to override links again. Links that are already upgraded won't be double-upgraded.

Options

The plob.start(options) function takes an object of options as input to configure plob's behaviour.

option | default | description ------ | ------- | ----------- root | '/' | root URL of the SPA system containers | [document.body] | containers for page content to be rendered in logging | false | enables logging loadtimes | false | if logging is enabled, displays load times for pages unsupported_cb | - | function to be run if plob is unsupported trailing_slash | false | whether to go to /foo/bar/ instead of /foo/bar load_overlay | - | initial loading element to hide once first page is loaded

Adding Pages

Pages take the form of asynchronous functions which have a 'render element' passed into them. They should then use this 'render element' (which will be one of the containers specific in options) as their root element in which the page is generated.

Pages can be added like so:

function my_page(render_elm, plob_options) {
    const h2 = document.createElement('h2')
    h2.innerText = 'Hello, world!'

    const img = document.createElement('img')
    img.src = '/example/grumpy_cat.jpg'

    render_elm.appendChild(h2)
    render_elm.appendChild(img)
}

plob.pages.push({regex: '.*', loader: my_page})

The page object can also have a name and an id parameter, which serve no functional value within plob besides logging. A priority number (which defaults to 1) can also be included, which will be used to sort the importance of pages when multiple regexs match for the current page. This is useful for pages such as 404.

Page Object

key | type | example | description --- | ---- | ------- | ----------- id | *? | 'abcd123' | page ID. Not required for any plob functionality name | *? | 'abcd123' | page name. Not required for any plob functionality regex | RegExp | '/mypage.*' | regular expression to match the URLs this page applies to loader | Function | - | function to run in order to load the page into a given element priority | Number | 10 | relative priority compared to other pages container | Node or Selector | '#special_container' | a specific container to use for this page, will never be overridden by another page or cleared at all

Note: it is highly recommended to use an Asynchronous Function for the loader if the page relies on asynchrous code, otherwise it may appear before it has fully loaded.

404 Page

A 404 page can easily be added with a wildcard regex and a negative priority, like so:

plob.pages.push({regex: '.*', loader: el => el.innerText = 'page not found', priority: -1})

See example/index.html for a working example of this.