mirror of
https://github.com/wahyd4/cdnjs.git
synced 2026-08-22 19:28:40 +10:00
33 lines
12 KiB
JSON
33 lines
12 KiB
JSON
{
|
|
"name": "hasher",
|
|
"filename": "hasher.min.js",
|
|
"version": "1.2.0",
|
|
"description": "Hasher is a set of JavaScript functions to control browser history for rich-media websites and applications",
|
|
"main": "dist/js/hasher.js",
|
|
"scripts": {
|
|
"test": "open dev/tests/unit/dev.html"
|
|
},
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "git://github.com/millermedeiros/Hasher.git"
|
|
},
|
|
"keywords": [
|
|
"history",
|
|
"hash",
|
|
"hasher",
|
|
"navigation",
|
|
"browser"
|
|
],
|
|
"author": {
|
|
"name": "Miller Medeiros",
|
|
"email": "contact@millermedeiros.com"
|
|
},
|
|
"license": "MIT",
|
|
"dependencies": {
|
|
"signals": ">0.7 <2.0"
|
|
},
|
|
"readme": "\n\nHasher is a set of JavaScript functions to control browser history for rich-media websites and applications.\nIt works as an abstraction of browsers native methods plus some extra helper methods, it also has the advantage of dispatching Events when the history state change across multiple browsers (since this feature isn't supported by all of them).\n\n\n\n## Why? ##\n\n - Browsers evolved since the other available solutions were created.\n - Some of the alternatives are way too complex, sometimes doing more things automatically than you actually want it to do.\n - Source code of most of the solutions are way too cryptic making it impossible to customize for your need or to debug it in case you find any issue.\n - Some of the solutions require extra markup and/or blank files to make it work.\n - The HTML5 History API is awesome but some for some kinds of applications using the\n `location.hash` may still be the recommended solution for saving application state.\n\n\n\n## Goals ##\n\n - Be simple.\n - Work on the main browsers (IE6+, newest versions of Firefox, Safari, Opera and Chrome).\n - Clean source code, making it easy to debug/customize/maintain.\n - Follow best practices/standards.\n - Fully unit tested. ([tests](http://millermedeiros.github.com/Hasher/test/unit.html))\n - Don't break application if for some reason `location.hash` can't be updated.\n (it should still dispatch `changed` signal at each `hasher.setHash()`)\n\n\n\n## Dependencies ##\n\n - **This library requires [JS-Signals](http://millermedeiros.github.com/js-signals/) to work.**\n\n\n\n## Basic Example ##\n\n\n### HTML ###\n\nInclude [JS-Signals](http://millermedeiros.github.com/js-signals/) and **hasher** to your HTML file:\n\n```html\n <script type=\"text/javascript\" src=\"signals.js\"></script>\n <script type=\"text/javascript\" src=\"hasher.js\"></script>\n```\n\n**IMPORTANT:** `signals.js` should be included before `hasher.js`.\n\n\n### JavaScript ###\n\n```js\n //handle hash changes\n function handleChanges(newHash, oldHash){\n console.log(newHash);\n }\n\n hasher.changed.add(handleChanges); //add hash change listener\n hasher.initialized.add(handleChanges); //add initialized listener (to grab initial value in case it is already set)\n hasher.init(); //initialize hasher (start listening for history changes)\n\n hasher.setHash('foo'); //change hash value (generates new history record)\n```\n\n\n## Advanced Usage ##\n\n\n### Hash Bang! ###\n\nGoogle have a proposal for [making Ajax content crawlable](http://code.google.com/web/ajaxcrawling/docs/getting-started.html) by specifying that a certain *hash value* also have an static snapshot. Those *hash values* should start with an exclamation mark `!`:\n\n```js\nhasher.prependHash = '!'; //default value is \"/\"\nhasher.setHash('foo'); //will update location.hash to \"#!foo\" -> htttp://example.com/#!foo\n```\n\nPS: Only use the hashbang if you are generating static snapshots for the hash.\n\n\n### Setting hash value without dispatching changed signal ##\n\nOne of the greatest benefits of Hasher over other solutions is that it uses JS-Signals for the event dispatch, which provides [many advanced features](https://github.com/millermedeiros/js-signals/wiki/Examples). This can be useful when you are setting the hash value and your `changed` handler doesn't need to be called (e.g. updating hash value during scroll). Use it with care.\n\n```js\nfunction setHashSilently(hash){\n hasher.changed.active = false; //disable changed signal\n hasher.setHash(hash); //set hash without dispatching changed signal\n hasher.changed.active = true; //re-enable signal\n}\n\nhasher.init(); //start listening for changes\nhasher.changed.add(console.log, console); //log all changes\nhasher.setHash('foo');\nsetHashSilently('lorem/ipsum'); //set hash value without dispatching changed event (will generate history record anyway)\nhasher.setHash('bar');\n```\n\n\n### Setting hash value without generating a new history record\n\nHasher also contains the method `replaceHash()`. It works very similarly to the\n`setHash()` method (will also dispatch a `changed` signal), the main difference\nit that it won't keep the **previous** hash on the history record (similar to\n`location.replace()`). It's useful for redirections and any other change that\nshouldn't be on the browser history.\n\n```js\nfunction onHasherInit(curHash){\n if (curHash == '') {\n // redirect to \"home\" hash without keeping the empty hash on the history\n hasher.replaceHash('home');\n }\n}\nhasher.initialized.add(onHasherInit);\nhasher.changed.add(console.log, console); // log all hashes\nhasher.init();\n```\n\n\n### Routes: Using Hasher together with Crossroads.js ###\n\nHasher is only focused on providing a reliable and clear API for setting hash values and\nlistening to hash state change event. If you need an advanced *routing* system\ncheck [crossroads.js](http://millermedeiros.github.com/crossroads.js/). Both\nwere designed to work together easily:\n\n```js\n//setup crossroads\ncrossroads.addRoute('home');\ncrossroads.addRoute('lorem');\ncrossroads.addRoute('lorem/ipsum');\ncrossroads.routed.add(console.log, console); //log all routes\n\n//setup hasher\nfunction parseHash(newHash, oldHash){\n crossroads.parse(newHash);\n}\nhasher.initialized.add(parseHash); // parse initial hash\nhasher.changed.add(parseHash); //parse hash changes\nhasher.init(); //start listening for history change\n```\n\n\n\n## How does it work? ##\n\nHasher will listen for the browser `onhashchange` event if it is supported (FF3.6+, IE8+, Chrome 5+, Safari 5+, Opera 10.6+)\nor it will fallback to pooling the `window.location` on an interval to check if\nhash value changed. On IE 6-7 it also uses an hidden iframe to trigger\nthe history state changes (since updating the hash value won't do the trick).\nThis is the same method used by most of the other available solutions like swfaddress,\njQuery Address, YUI History, jqBBQ, Really Simple History, etc...\n\nThe main difference from the other solutions are the API, code structure and\nthe fact that it doesn't require jQuery/YUI/dojo/moootools/etc to work. It also\nuses [JS-Signals](http://millermedeiros.github.com/js-signals/) for the events which\nprovides a sane way of handling events and some really useful advanced features.\n\n\n\n## Why should I use it? ##\n\nBesides the fact of making history state work across multiple browsers it also\nnormalizes and fixes many bugs, here are a few of the advantges:\n\n * Normalizes the hash value across browsers (firefox decode hash value and\n all the other browsers don't).\n * Fix IE8 bug if `location.hash` contains a \"?\" character and file is being\n accessed locally it would break the history stack. [iss #6]\n * Fix Safari 4-5 bug while setting `location.hash` to a value that contain\n non-printable ASCII chars (non-latin, accents, etc..). [iss #8]\n * Degrade gracefully if for some reason `location.hash` isn't available, will\n dispatch the `changed` signal at each `hasher.setHash()` and application\n can still work, it just won't generate a new history record.\n * Doesn't rely on callbacks so you can add as many listeners as you want and\n since it uses [JS-Signals](http://millermedeiros.github.com/js-signals/)\n for the event system it also provides many advanced featured that wouldn't\n be available through a simple callback system, like disabling the dispatch\n of an event (so you can change the hash value without affecting your app\n state), removing all the listeners at once, dispose objects, etc...\n * Option to start/stop pooling/listening for changes on the hash whenever you\n want giving more control over how you app is supposed to work.\n * Available as an AMD module which can be easily integrated into other\n projects without polluting the global scope or affecting you aplication\n structure.\n * Isn't a plugin for a large JS library/framework (so you can use it with\n *any* library).\n * Can be easily integrated into a Router like\n [crossroads.js](http://millermedeiros.github.com/crossroads.js/).\n * Sometimes regular URLs doesn't make any sense, specially when you *can't*\n provide a fallback to all of them or when you just want to save the state of\n the application and that change wouldn't make sense on a full page reload\n (scrolling through the same page, interactive slideshow, etc..), also some\n content may not need to be indexed by search engines (although you can use\n *hashbangs* to make [Ajax content crawlable](http://code.google.com/web/ajaxcrawling/docs/getting-started.html)...).\n **Each scenario requires a different approach, be pragmatic.**\n * Clean API.\n\n\n\n## Documentation ##\n\nDocumentation can be found inside the `dist/docs` folder or at [http://millermedeiros.github.com/Hasher/docs/](http://millermedeiros.github.com/Hasher/docs/).\n\n\n\n## Unit Tests ##\n\nHasher is *usually* tested on IE (6,7,8,9), FF (3.6, 4.0, 5.0+ - mac/pc),\nChrome (latest stable - mac/pc), Safari Mac (4.3, 5.0) and Opera (latest - mac/pc).\n\nYou can also run the test by yourself at [http://millermedeiros.github.com/Hasher/test/unit.html](http://millermedeiros.github.com/Hasher/test/unit.html)\n\n\n\n## Repository Structure ##\n\n### Folder Structure ###\n\n dev -> development files\n |- build -> files used on the build process\n |- lib -> 3rd-party libraries\n |- src -> source files\n |- tests -> unit tests\n dist -> distribution files\n |- docs -> documentation\n |- js -> javascript files\n\n### Branches ###\n\n master -> always contain code from the latest stable version\n release-** -> code canditate for the next stable version (alpha/beta)\n dev -> main development branch (nightly)\n gh-pages -> project page\n **other** -> features/hotfixes/experimental, probably non-stable code\n\n\n\n## Distribution Files ##\n\nFiles inside `dist/js` folder.\n\n * hasher.js : Uncompressed source code with comments. Works as a plain script\n or can be loaded by an AMD loader like [RequireJS](http://requirejs.org/)\n without generating any global variables.\n * hasher.min.js : Compressed code.\n\nDocumentation is inside the `dist/docs` folder.\n\n\n\n## Building your own ##\n\nThis project uses [Apache Ant](http://ant.apache.org/) for the build process. If for some reason you need to build a custom version install Ant and run:\n\n ant compile\n\nThis will delete all JS files inside the `dist` folder, merge/update/compress source files and copy the output to the `dist` folder.\n\n ant deploy\n\nThis will delete all files inside *dist* folder, is runs `ant compile` and generate documentation files.\n\n**IMPORTANT:** `dist` folder always contain the latest version, regular users should **not** need to run build task.\n\n\n\n## License ##\n\nReleased under the [MIT license](http://www.opensource.org/licenses/mit-license.php).\n\n\n\n## Important ##\n\n - Weird case scenarios like calling methods from inside (i)frame, wrong doctype,\n plugins, 3rd party code, etc, **MAY** prevent script from working properly.\n - Hasher was designed on a way that it will still dispatch the\n `changed` signal even if it can't update the browser `location.hash`, so\n application should keep working even if back/prev buttons doesn't work as\n expected.\n - Consider using the new [HTML5 history API](http://robertnyman.com/2011/08/03/html5-history-api-and-improving-end-user-experience/)\n if normal URLs would make sense on the kind of site/application you are building and\n you have static fallbacks for all of them (in some cases that may not be\n possible or even a good option). [History.js](https://github.com/balupton/history.js)\n is probably the most used *polyfill* for the History API, check it out.\n\n\n© [Miller Medeiros](http://www.millermedeiros.com)\n",
|
|
"_id": "hasher@1.2.0",
|
|
"_from": "hasher"
|
|
}
|