https://github.com/avoidwork/dom-router
URL hash to DOM router
https://github.com/avoidwork/dom-router
Last synced: 10 months ago
JSON representation
URL hash to DOM router
- Host: GitHub
- URL: https://github.com/avoidwork/dom-router
- Owner: avoidwork
- License: bsd-3-clause
- Created: 2014-12-26T15:34:13.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2022-09-23T21:00:34.000Z (over 3 years ago)
- Last Synced: 2025-04-01T16:50:47.130Z (10 months ago)
- Language: JavaScript
- Homepage: http://avoidwork.github.io/dom-router
- Size: 887 KB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# dom-router
Imagine you didn't have to write a bunch of JavaScript to get a slick, progressively enhanced interface! `dom-router`
is a URL hash to DOM router which automatically, & intelligently toggles visibility of `Elements` based on `popstate`
events.
This provides a clean separation of concerns, and progressive enhancement in a simple library. You can write clean HTML,
and `dom-router` will progressively enhance the interface with CSS classes (not supplied). DOM updates happen on an
animation frame to minimize impacting your application. An optional `callback` allows you to handle application
state changes the way you want.
## Example
This example is meant to demonstrate multi-tier routing in a single page application. When the HTML is "clean", it is
functional for screen readers & text based browsers like `lynx`, and with progressive enhancement, developers can add
new behaviour without impacting the experience of other consumers.
### Minimal coding required
```javascript
import {router} from "./dom-router.js";
window.appRouter = router({callback: arg => console.log(`${arg.element.id} is visible`)});
```
### Before routing is enabled
```html
...
...
...
...
...
```
### After routing is enabled
This would be the result if a user visited `#settings/billing`:
```html
...
...
...
...
...
```
## How can I load dom-router?
When loaded with a script tag, `window.domRouter.router()` will be created.
## Configuration
### active
`Boolean` which enables/disables routing
### callback
Function to execute after route has changed, takes `arg` which describes the event
### css
`Object` with `current`, & `hidden` keys which have corresponding CSS class values, defaults to "dr-current", & "dr-hidden"
### ctx
Context for DOM selector, defaults to `body` if not specified
### delimiter
Multi-tier routing delimiter, defaults to `/`, e.g. `#settings/billing`; each tier should map to a nested `id`
### logging
`Boolean` which logs routing to `router.history[]` if `true`, defaults to `false`; could be a memory leak if logging is enabled and target `Elements` are removed from DOM
### start
[Optional] The starting route to display if one is not specified, or an invalid route is specified
### stickyPos
`Boolean` which enables/disables remaining at `Y position` when the route changes, i.e. no scrolling, defaults to `true`.
### stickyRoute
`Boolean` which enables/disables sticky routing, defaults to `true`.
### stickySearchParams
`Boolean` which enables/disables sticky `searchParams` of `location`, defaults to `false`. When it disabled `history.replaceState()` is executed on `location` before `callback()`.
### storage
`String` Storage used for `stickyRoute`, defaults to `session`; valid options are `session` or `local`.
### storageKey
`String` Key for persistent storage for `stickyRoute`.
## API
### current()
Returns the current `Route`; if logging is enabled the trigger `Element` will be present
### popstate()
Event handler
### scan(default)
Scans `ctx` for routes & resets `default` which is an optional argument, otherwise it defaults to the first route
### select(query)
Context specific DOM selector
## Requirements
- `Element.classList` API, or shim
- `popstate` Event
## License
Copyright (c) 2022 Jason Mulligan
Licensed under the BSD-3 license