100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# 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:** 
|
|
- **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).
|