Enables hash links to web page content hidden beneath layers of interaction.
Hurdler makes nested UI interactions simple to manage via URL hash.
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. |
When components such as modals and slideshows are navigated via URL hash:
With Hurdler:
#/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.Install Hurdler in your project as an NPM dependency:
npm install hurdler --save
Import it at the beginning of your app:
import Hurdler from 'hurdler'
Initialize Hurdler:
const hurdler = new Hurdler()
Setup hurdles:
hurdler.addHurdle({
test: element => {
return element.tagName === 'SECTION'
},
onJump: element => {
console.log('Jumped a section', element)
}
})
Run a first sprint, after DOM ready:
hurdler.sprint()
Creates a new Hurdler session. There should only be one instance per window.
Parameters
$0
Object (optional, default {}
)
$0.hashPrefix
[String] String between URL hash symbol and target element ID to denote Hurdler links. Prevents auto scroll. (optional, default '/'
)$0.onSprintBefore
[function] Runs before each sprint.$0.onSprintAfter
[function] Runs after each sprint.$0.hurdles
[Array<Hurdle>] List of hurdles. (optional, default []
)Examples
const hurdler = new Hurdler({
hashPrefix: '!/'
})
The current URL hash target element, or null if nonexistent.
Examples
console.log(hurdler.target)
Adds a hurdle.
Parameters
options
Hurdle A hurdle.Examples
hurdler.addHurdle({
test: element => {
return element.tagName === 'SECTION'
},
onJump: element => {
console.log('Jumped a section', element)
}
})
Checks a provided URL hash matches the configured format.
Parameters
hash
string A URL hash to validate.Examples
hurdler.validateHash(anExampleLinkElement.hash)
Returns boolean URL hash validity.
Sets the URL hash target element, triggering a sprint.
Parameters
element
HTMLElement Element with an ID to target.Examples
hurdler.setTarget(anExampleElement)
Clears the window URL hash if a given element is targeted, or if the URL hash matches the configured Hurdler format.
Parameters
element
[HTMLElement] Element with an ID that you do not want targeted.Examples
hurdler.clearTarget(anExampleElement)
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
hurdler.sprint()
An object holding a test and callbacks for when a DOM element passes.
Properties
test
function Accepts an element and returns a boolean if it matches the hurdle.onJump
[function] Runs when the hurdle is jumped.Examples
{
test: element => {
return element.tagName === 'SECTION'
},
onJump: element => {
console.log('Jumped a section', element)
}
}