powahroot/README.md

# ![](https://raw.githubusercontent.com/sbrl/powahroot/master/logo-large.png)powahroot

> Client and server-side routing micro frameworks

_Powahroot_ is a pair of micro routing frameworks, presented as an ES6 module:

 - The first is for client-side single-page web applications
 - The other is for handling server-side Node.js requests

It's based on [`rill`](https://www.npmjs.com/package/rill) (see the npm package bearing the name), but stripped down and simplified.

- **Current version:** ![current npm version - see the GitHub releases](https://img.shields.io/npm/v/powahroot)
- **Changelog:** https://github.com/sbrl/powahroot/blob/main/CHANGELOG.md

## Getting Started
Install powahroot as a dependency with npm:

```bash
npm install --save powahroot
```

If your build process supports [tree-shaking](https://webpack.js.org/guides/tree-shaking/), only the router(s?) you need will be included in the final output of your build - as _powahroot_ uses ES6 modules.


## Usage

### Paths
Powahroot supports multiple syntax bells and whistles when defining routes. These are documented below:

Syntax							| Meaning
--------------------------------|----------------------------------------
`/index.html`					| Regular route. Matches exactly what it says on the tin.
`*`								| Special key(word?) that matches _any_ route. Must be present on its own without any other characters.
`/add/vegetable/:name/:weight`	| Parameters. Match values an pull them into an object automatically. Does not like forward slashes in parameter values.
`/images/::path`				| Parameter values with forward slashes. If you want to use parameters, but need values to be able to contain forward slashes `/`, this is for you. Don't forget you can mix-and-match this with the previous example!

### Client
Initialise a new router like this:

```js
import ClientRouter from 'powahroot/Client.mjs';

// ....

const router = new ClientRouter({
	// Options object. Default settings:
	verbose: false, // Whether to be verbose in console.log() messages
	listen_pushstate: true, // Whether to react to browser pushstate events (excluding those generated by powahroot itself, because that would cause an infinite loop :P)
});

// Add a page
router.add_page("/add/vegetable/:name/:weight", (params) => {
    console.log(`We added a ${params.name} with a weight of ${params.weight}g.`);
});

// Explicitly navigate to a page:
router.navigate("/add/carrot/frederick/10001");
```

### Server
The server router works slightly differently, to account for the different environment it's designed for. Here's how to use it:

```js
import ServerRouter from 'powahroot/Server.mjs';

// ....

const router = new ServerRouter();
// Logging middle ware
router.on_all(async (context, next) => {
    console.debug(context.url);
    await next();
});
// Regular handlere
router.get("/files/::filepath", (context, _next) => context.send.plain(200, `You requested ${context.params.filepath}`));
// .....

// Later, when you've got a request / response pair to handle:
await router.handle(request, response);
```

The `context` argument there is of type `RouterContext`. Check out the API reference (link below) to learn about the other useful properties it has.

## Reference
API docs are generated automatically. View them here:

<https://starbeamrainbowlabs.com/code/powahroot/docs/>

It contains full documentation on how to use everything, along with code examples to help you get started.

## Contributing
Contributions are welcome! Simply fork this repository, make your changes, and submit a [Pull Request](https://help.github.com/en/articles/about-pull-requests) (issues are welcome too!).

All contributions must be declared to have the `Mozilla Public License 2.0` (the same license that this repository is under).

## Licence
Everything in this repository _except_ the logo is licenced under the _Mozilla Public License 2.0.

The logo itself is © Copyright Starbeamrainbowlabs 2019. All rights reserved - though you _may_ use it when linking to this project (or to advertise usage in a 'powered by' logo).