Commits

David Chambers committed 574f2c8

Added README.

Comments (0)

Files changed (1)

+# Hash
+
+Hash is a lightweight utility which lets `window.location.hash` be used as a
+key–value store.
+
+Search parameters are typically stored in query strings, which makes sense
+for “traditional” sites. It's becoming increasingly common, though, for search
+results to be delivered via Ajax, producing result sets without associated
+Uniform Resource Locators.
+
+Hash provides a simple API for creating hash fragments from key–value data
+(and vice versa). Unlike `location.search`, `location.hash` can be modified
+without triggering a page reload.
+
+## API
+
+### `new Hash([defaults])`
+
+Creates a `Hash` instance. The value of `location.hash` is used to populate
+the instance's internal mapping object.
+
+If the `defaults` mapping object is provided, it is used to initialize the
+instance's internal mapping object. Some or all of the data in `defaults`
+may be overwritten by the key–value pairs contained in `location.hash`.
+
+### `hash.get(key [, defaultValue])`
+
+Returns the value associated with the provided key if it exists in `hash`.
+Otherwise, returns `defaultValue` (if provided) or `undefined`.
+
+### `hash.set(key, value)`
+
+Adds a new key–value pair or overwrites an existing pair.
+
+Returns `hash`.
+
+### `hash.set(obj)`
+
+Adds the key–value pairs in the provided mapping object to `hash`, overwriting
+each existing pair whose key is also in `obj`.
+
+Returns `hash`.
+
+### `hash.remove(key)`
+
+Deletes the pair with the provided key.
+
+Returns `hash`.
+
+### `hash.apply()`
+
+Updates `location.hash` with the key–value pairs stored in `hash`. Requiring
+an explicit method call to update the URL prevents the creation of unwanted
+history entries.
+
+Returns `hash`.
+
+### `hash.extend(obj)`
+
+Equivalent to `hash.set(obj)`.
+
+### `hash.keys()`
+
+Returns an alphabetized array of keys.
+
+### `hash.toString()`
+
+Returns the string representation of `hash`. Each key–value pair is in the
+form `"k=v"` where `k` is the URI-encoded key and `v` is the URI-encoded
+value. Pairs are alphabetized by key, and separated by ampersands.
+
+`"#" + new Hash === window.location.hash` evaluates to `true` for every
+correctly-formatted hash, making it possible to translate in either direction.
+
+### `Hash.noConflict()`
+
+Restores the overwritten value of `window.Hash` and returns `Hash`.
+
+### `Hash.version`
+
+String representing this utility's version number. Currently "0.1.0".