fill out initial readme
This commit is contained in:
父節點
978add311b
當前提交
b3d383184f
43
README.md
43
README.md
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue