https://github.com/jaydenseric/hurdler
Enables hash links to web page content hidden beneath layers of interaction.
https://github.com/jaydenseric/hurdler
Last synced: 8 months ago
JSON representation
Enables hash links to web page content hidden beneath layers of interaction.
- Host: GitHub
- URL: https://github.com/jaydenseric/hurdler
- Owner: jaydenseric
- Created: 2015-08-24T21:59:25.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2016-11-20T08:16:20.000Z (about 9 years ago)
- Last Synced: 2025-04-26T11:37:40.236Z (9 months ago)
- Language: JavaScript
- Homepage:
- Size: 51.8 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 
  
Hurdler makes nested UI interactions simple to manage via URL hash.
- ES6 source with efficient transpilation in mind.
- Less than 1 KB compressed.
- IE 11 and modern browser support.
- [MIT license](https://en.wikipedia.org/wiki/MIT_License).
## How it works
1. A sprint is triggered manually or automatically when the URL hash changes with a valid target.
2. Hurdler sprints up the DOM from the target finding ancestor elements that match hurdles.
3. Jump callbacks run in top-down DOM order. Often components such as overlays need to be activated before descendants.
Lingo | Meaning
:----- | :--------------------------------------------------------------------
Target | A DOM element targeted via ID in the URL hash; the sprint start line.
Sprint | A sprint up the DOM, looking for hurdles from the target.
Hurdle | A test and stuff to do when a DOM element passes.
Jump | A hurdle that was found in a sprint.
## Benefits
When components such as modals and slideshows are navigated via URL hash:
- Controls are simple hash links; semantic with no click events to manage.
- Native browser back and forward controls navigate the UI.
- Component controls such as slideshow next buttons can be right-clicked and opened in a new tab, etc.
- Intuitively copy the URL to bookmark or share any part of the page.
With Hurdler:
- Even deeply nested pieces of content can be accessed by a short, single segment URL hash (e.g. `#/pricing`). Aside from looking nicer and being easier to tweet than multi-segment approaches (e.g. `#/section/overview/slide/pricing`), changing structure, components or content is less likely to break existing links.
- Components define their own hurdles; no centralized routes to setup.
- Dynamically inserting or moving components around is no problem; every sprint is a fresh search for hurdles to jump.
## Setup
Install Hurdler in your project as an NPM dependency:
```sh
npm install hurdler --save
```
Import it at the beginning of your app:
```javascript
import Hurdler from 'hurdler'
```
Initialize Hurdler:
```javascript
const hurdler = new Hurdler()
```
Setup hurdles:
```javascript
hurdler.addHurdle({
test: element => {
return element.tagName === 'SECTION'
},
onJump: element => {
console.log('Jumped a section', element)
}
})
```
Run a first sprint, after DOM ready:
```javascript
hurdler.sprint()
```
## API
### Hurdler
Creates a new Hurdler session. There should only be one instance per window.
**Parameters**
- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{}`)
- `$0.hashPrefix` **[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** String between URL hash symbol and target element ID to denote Hurdler links. Prevents auto scroll. (optional, default `'/'`)
- `$0.onSprintBefore` **[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Runs before each sprint.
- `$0.onSprintAfter` **[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Runs after each sprint.
- `$0.hurdles` **[[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Hurdle](#hurdle)>]** List of hurdles. (optional, default `[]`)
**Examples**
```javascript
const hurdler = new Hurdler({
hashPrefix: '!/'
})
```
#### target
The current URL hash target element, or null if nonexistent.
**Examples**
```javascript
console.log(hurdler.target)
```
#### addHurdle
Adds a hurdle.
**Parameters**
- `options` **[Hurdle](#hurdle)** A hurdle.
**Examples**
```javascript
hurdler.addHurdle({
test: element => {
return element.tagName === 'SECTION'
},
onJump: element => {
console.log('Jumped a section', element)
}
})
```
#### validateHash
Checks a provided URL hash matches the configured format.
**Parameters**
- `hash` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A URL hash to validate.
**Examples**
```javascript
hurdler.validateHash(anExampleLinkElement.hash)
```
Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** URL hash validity.
#### setTarget
Sets the URL hash target element, triggering a sprint.
**Parameters**
- `element` **[HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)** Element with an ID to target.
**Examples**
```javascript
hurdler.setTarget(anExampleElement)
```
#### clearTarget
Clears the window URL hash if a given element is targeted, or if the URL hash matches the configured Hurdler format.
**Parameters**
- `element` **[[HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)]** Element with an ID that you do not want targeted.
**Examples**
```javascript
hurdler.clearTarget(anExampleElement)
```
#### sprint
Jumps hurdles and runs callbacks for the current URL hash. Use after all hurdles have been added and the document is ready. Triggered automatically by URL hash changes.
**Examples**
```javascript
hurdler.sprint()
```
### Hurdle
An object holding a test and callbacks for when a DOM element passes.
**Properties**
- `test` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Accepts an element and returns a boolean if it matches the hurdle.
- `onJump` **[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Runs when the hurdle is jumped.
**Examples**
```javascript
{
test: element => {
return element.tagName === 'SECTION'
},
onJump: element => {
console.log('Jumped a section', element)
}
}
```