Browse Source

fill out initial readme

Conduitry 5 years ago
committed by GitHub
  1. 43


@ -1,2 +1,45 @@
# story
Minimal HTML5 history API wrapper
## About
The purpose of this library was to create a very thin wrapper around the HTML5 history API, but still one that handles the basic everyday tasks. It started as a bit of shared code that I found myself using on a couple of personal projects, so I decided to publish it here.
It handles programmatically switching to a URL or replacing a URL, informing your code when the URL changes, and intercepting clicks on hyperlinks to call the history API instead of performing page navigation.
## What it is not
It is not an actual router. You provide a function, this library calls your function when the URL changes. That's it.
## How to use
This is an ES2015 module. You will need some way to bundle and transpile this for your app.
## Methods available
### `setBase(base)`
Set a new value for the base path. Defaults to `"/"`. This should be the root path of your app.
### `watch(cb)`
Register a new callback to be informed whenever the path changes. Your callback will be called with one argument, the portion of the path after the currently specified base.
### `unwatch(cb)`
Unregisters a previously registered watcher.
### `to(url)`
Perform (virtual) navigation to the new URL. `url` will be appended to the current base.
Also calls any currently registered watchers.
### `replace(url)`
Replace the current URL with the new one you specify. `url` will be appended to the current base. Call this when you want to, for example, perform a redirect without creating a new entry in the navigation history.
Also calls any currently registered watchers.
## Hyperlink handling
Activating hyperlinks will be replaced with a call to `to()` provided that:
* the control/meta/shift keys were not pressed during the click, and the click was not done with the middle mouse button
* the hyperlink element has no `target` value
* the hyperlink's `href` begins with the currently selected base - defaults to `"/"` and can be changed with `setBase()`
If you have a hyperlink that would otherwise be caught by the click handler and you do not want it to be, you can specify `target="_self"` on the link element.
## License
This code was written by Conduitry and is released into the public domain.