hashable
v1.5.5
Published
Stateful URLs in the browser hash, parsing and formatting, and more!
Downloads
14
Readme
hashable
Save and restore state in the browser's location.hash, parse and format URLs, and more! See the API reference for more info.
Hash manipulation
Hashable can manipulate the browser's location hash, allowing you to read and write state to the URL without reloading the page:
// create your hash manipulator and add a change listener
var hash = hashable.hash()
.change(function(e) {
console.log("hash data:", e.data);
})
.enable();
// you can set the hash programmatically:
hash.set({path: "path/to/foo", bar: "hi"});
// location.hash should now equal:
// "path/to/foo?bar=hi"
// you can disable and re-enable hashchange event listening:
hash.disable();
hash.enable();
// you can set the default URL data as either an object literal or a function:
hash.default({foo: "bar"});
hash.default(function() {
return {foo: someCondition ? "bar" : "baz"};
});
// and check() does the dirty work of reading location.hash if it's set,
// or writing location.hash with either the current or default value:
hash.check();Parsers and Formatters
hashable.hash() can use whatever parsing and formatting logic you throw at it, but it comes with some helpful primitives:
# hashable.format.path() is the default format, and it parses location.hash into an object like so:
var fmt = hashable.format.path();
fmt({path: "foo/bar"}); // "foo/bar"
fmt.parse("foo/bar"); // {path: "foo/bar"}
fmt({path: "foo/bar", baz: "qux"}); // "foo/bar?baz=qux"
fmt.parse("foo/bar?baz=qux"); // {path: "foo/bar", baz: "qux"}# hashable.format() allows you to more specifically define a path format as a Mustache-like string:
var fmt = hashable.format("type/{type}");
fmt({type: "foo"}); // "type/foo"
fmt.parse("type/bar"); // {type: "bar"}# hashable.format.map() is made for slippy maps like Leaflet. This allows you to save the center and zoom of the map (its location on the Earth) in the URL, allowing people to share specific views. This approach also allows you to link directly to map views with anchor tags, using an href in the format #{zoom}/{lat}/{lng}.
# You can use the handy L.hash Leaflet plugin (bundled as of v1.3.0) like so:
var map = L.map("map")
.setView([37.7691, -122.4399], 11),
hash = L.hash()
.addTo(map)
.check();Or you can adapt the standalone example to your favorite map engine.
Browser Usage
Just drop hashable.js (or the minified hashable.min.js) into the <head> of your
HTML document, and access it via the global hashable object.
<!DOCTYPE html>
<html>
<head>
<script src="hashable.js"></script>
</head>
<body>
<script>
var hash = hashable.hash();
</script>
</body>
</html>You can aslo install the JavaScript locally with Bower:
$ bower install hashableUsing with Node.js
Just install via npm:
$ npm install hashableand require away:
var hashable = require("hashable");