can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - can-route-pushstate</title> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"> <link rel="stylesheet" type="text/css" href="./static/bundles/bit-docs-site/static.css"> <link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48 64x64" href="/docs/images/canjs_favicon.ico"> <link rel="apple-touch-icon" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon-precomposed" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon" sizes="72x72" href="../docs/images/canjs_favicon_72x72.png"> <link rel="apple-touch-icon" sizes="114x114" href="../docs/images/canjs_favicon_114x114.png"> <link rel="apple-touch-icon" sizes="120x120" href="../docs/images/canjs_favicon_128x128.png"> <link rel="apple-touch-icon" sizes="144x144" href="../docs/images/canjs_favicon_144x144.png"> <link rel="apple-touch-icon" sizes="152x152" href="../docs/images/canjs_favicon_152x152.png"> <meta content="yes" name="apple-mobile-web-app-capable"> <meta name="apple-mobile-web-app-status-bar-style" content="white-translucent"> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-2302003-11', 'auto'); ga('send', 'pageview'); </script> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger"/> <label for="nav-trigger">Menu</label> <div id="everything"> <div id="left" class="column"> <div class="top-left"> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> <div class="dropdown project-dropdown"> <a href="https://donejs.com/">DoneJS</a> <a href="http://stealjs.com/">StealJS</a> <a href="http://jquerypp.com/">jQuery ++</a> <a href="https://funcunit.com/">FuncUnit</a> <a href="http://documentjs.com/">DocumentJS</a> </div> </div> <div class="version"> <div class="version-number"> 3.0.0 </div> <div class="dropdown version-dropdown"> <a href="https://v2.canjs.com">2.3.27</a> </div> </div> </div> <div class="search-bar"> <p>   </p> </div> </div> <div class="bottom-left"> <div class="social-side-container"> <ul class="social-side"> <li> <a class="header-mobile github" href="https://github.com/canjs/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/github.png">Github</a> </li> <li> <a class="header-mobile twitter" href="https://twitter.com/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/twitter.png">Twitter</a> </li> </ul> <ul class="social-side"> <li> <a class="header-mobile" href="https://gitter.im/canjs/canjs" target="_blank">Chat</a> </li> <li> <a class="header-mobile" href="http://forums.donejs.com/c/canjs" target="_blank">Forum</a> </li> </ul> </div> <ul> <li class=" "> <a class="page" href="guides.html" title="Welcome to CanJS! These guides are here to help you develop and improve your relationship with CanJS. After all, picking a JavaScript framework is a commitment. We want CanJS to be the framework you marry. This page helps you know how advance through the different stages of this relationship:"> Guides </a> </li> <li class=" parent expanded"> <a class="page" href="can-core.html" title="The best, most hardened and generally useful libraries in CanJS."> Core </a> <ul> <li class=" "> <a class="module" href="can-component.html" title="Create a custom element that can be used to manage widgets or application logic."> can-component </a> </li> <li class=" "> <a class="module" href="can-compute.html" title="Create an observable value."> can-compute </a> </li> <li class=" "> <a class="module" href="can-connect.html" title="can-connect provides persisted data middleware. Use it to assemble powerful model layers for any JavaScript project."> can-connect </a> </li> <li class=" "> <a class="module" href="can-define.html" title="Exports the define method that defines observable properties and their behavior on a prototype object."> can-define </a> </li> <li class=" "> <a class="module" href="can-define/list/list.html" title="Create observable lists."> can-define/list/list </a> </li> <li class=" "> <a class="module" href="can-define/map/map.html" title="Create observable objects."> can-define/map/map </a> </li> <li class=" "> <a class="function" href="can-route.html" title="Manage browser history and client state by synchronizing the window.location.hash with a map."> can-route </a> </li> <li class="current parent expanded"> <a class="module" href="can-route-pushstate.html" title="Changes can-route to use pushstate to change the window's pathname instead of the hash. var route = require("can-route-pushstate"); route("{page}", { page: "home" }); route.ready(); route.attr("page", "user"); location.pathname; // -> "/user""> can-route-pushstate </a> </li> <li class=" "> <a class="module" href="can-set.html" title="can-set is a utility for comparing sets that are represented by the parameters commonly passed to service requests."> can-set </a> </li> <li class=" "> <a class="module" href="can-stache.html" title="Live binding Mustache and Handlebars-compatible templates."> can-stache </a> </li> <li class=" "> <a class="module" href="can-stache/helpers/route.html" title="Adds stache helpers that use can-route."> can-stache/helpers/route </a> </li> <li class=" "> <a class="module" href="can-stache-bindings.html" title="Provides template event, one-way, and two-way bindings."> can-stache-bindings </a> </li> </ul> </li> <li class=" "> <a class="page" href="can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection."> Ecosystem </a> </li> <li class=" "> <a class="page" href="can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> </li> <li class=" "> <a class="page" href="can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development."> Legacy </a> </li> </ul> </div> </div> <div id="right" class="column"> <div class="top-right"> <div class="top-right-top"> <ul class="top-right-bitovi"> <li class="dropdown"> <a href="http://bitovi.com" class="bitovi icon-bits">Bitovi</a> <ul class="dropdown-menu"> <li><a href="http://bitovi.com">Bitovi.com</a></li> <li><a href="http://bitovi.com/blog/">Blog</a></li> <li><a href="http://bitovi.com/consulting/">Consulting</a></li> <li><a href="http://bitovi.com/training/">Training</a></li> <li><a href="http://bitovi.com/open-source/">Open Source</a></li> </ul> </li> </ul> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> </div> </div> <ul class="top-right-links"> <li> <a href="https://gitter.im/canjs/canjs">Chat</a> </li> <li> <a href="http://forums.donejs.com/c/canjs">Forum</a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/canjs" data-count-href="/canjs/canjs/stargazers" data-count-api="/repos/canjs/canjs#stargazers_count">Star</a> </li> <li> <a href="https://twitter.com/canjs" class="twitter-follow-button nav-social" data-show-count="true" data-show-screen-name="false">Follow @canjs</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </li> </ul> </div> <div class="breadcrumb"> <li><a href="../index.html">CanJS</a></li> / <li><a href="can-core.html">Core</a></li> / <li><a href="can-route-pushstate.html">can-route-pushstate</a></li> <li class="breadcrumb-dropdown">/ <a> On this page</a> <ul class="on-this-page"></ul> </li> <div class="nav-toggle" title="Back to top"></div> </div> </div> <div class="bottom-right"> <article> <section class="title"> <div class="page-type"> <h1>can-route-pushstate</h1> <div>module</div> </div> <section class="description"> <p>Changes <a href="can-route.html" title="Manage browser history and client state by synchronizing the window.location.hash with a map.">can-route</a> to use <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history">pushstate</a> to change the window's <a href="https://developer.mozilla.org/en-US/docs/Web/API/URLUtils.pathname">pathname</a> instead of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URLUtils.hash">hash</a>.</p> <pre><code class="language-js">var route = require("can-route-pushstate"); route("{page}", { page: "home" }); route.ready(); route.attr("page", "user"); location.pathname; // -> "/user" </code></pre> </section> </section> <section class="on-this-page-table"> </section> <section class="title-footer"> <ul class="title-social"> <li> <a class="npm-button" href="https://www.npmjs.com/package/can-route-pushstate"> <img src="https://img.shields.io/badge/npm%20package-3.0.0-brightgreen.svg" alt="npm package badge" /> </a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/can-route-pushstate" data-count-href="/canjs/can-route-pushstate/stargazers" data-count-api="/repos/canjs/can-route-pushstate#stargazers_count">Star</a> </li> </ul> <ul class="title-links">  <li><a href="//github.com/canjs/can-route-pushstate/tree/v3.0.0/can-route-pushstate.md">source</a></li>   </ul> </section> <div class="signature"> <h2 class="signature-title"> <code>Object</code> </h2> <div class="options"> <h3 class="options-title">Options</h3> <ul> <li> <b>The</b> <code>{Object}</code>: <p>pushstate object comprises several properties that configure the behavior of <a href="can-route.html" title="Manage browser history and client state by synchronizing the window.location.hash with a map.">can-route</a> to work with <code>history.pushstate</code>.</p> </li> </ul> </div> </div> <section class="body"> <h2>Use</h2> <p>can-route-pushstate uses the same API as <a href="can-route.html" title="Manage browser history and client state by synchronizing the window.location.hash with a map.">can-route</a>. To start using can-route-pushstate all you need is to import <code>can-route-pushstate</code>, it will set itself as default binding on <a href="can-route.html" title="Manage browser history and client state by synchronizing the window.location.hash with a map.">can-route</a>.</p> <p>You can check current binding by inspecting <code>route.currentBinding</code>; the default value is <code>"hashchange"</code>.</p> <h3>Creating and changing routes</h3> <p>To create routes use <code>route(url, defaults)</code> like:</p> <pre><code class="language-js">route("{page}", {page: 'homepage'}); route("contacts/{username}"); route("books/{genre}/{author}"); route.ready(); // Initializes can-route </code></pre> <p>Do not forget to <a href="can-route.ready.html" title="Initializes can-route.">initialize</a> can-route after creating all routes, do it by calling <code>route.ready()</code>.</p> <p>List of defined routes is contained in <code>route.routes</code>, you can examine current route state by calling:</p> <pre><code class="language-js">route.attr(); //-> {page: "homepage", route: "{page}"} </code></pre> <p>After creating routes and initializing can-route you can update current route by calling <code>route.attr(attr, newVal)</code>:</p> <pre><code class="language-js">route.attr('page', 'about'); route.attr(); //-> {page: "about", route: "{page}"} // without cleaning current route state route.attr('username', 'veljko'); route.attr(); //-> {page: "about", route: "{page}", username: 'veljko'} // with cleaning current can-route state route.attr({username: 'veljko'}, true); route.attr(); //-> {username: "veljko", route: "contacts/{username}"} </code></pre> <p>To update multiple attributes at once pass hash of attributes to <code>route.attr(hashOfAttrs, true)</code>. Pass <code>true</code> as second argument to clean up current state.</p> <pre><code class="language-js">route.attr({genre: 'sf', author: 'adams'}, true); route.attr(); //-> {genre: "sf", author: "adams", route: "books/{genre}/{author}"} </code></pre> <p><code>window.location</code> acts as expected:</p> <pre><code class="language-js">window.location.pathname; //-> "/books/sf/adams" window.location.hash; //-> "", hash remains unchanged </code></pre> <p>To generate urls use <code>route.url({attrs})</code>:</p> <pre><code class="language-js">route.url({username: 'justinbmeyer'}); //-> '/contacts/justinbmeyer' </code></pre> <h3>Listening changes on matched route</h3> <p>As can-route contains a map that represents <code>window.location.pathname</code>, you can bind on it.</p> <p>To bind to specific attributes on can-route:</p> <pre><code class="language-js">route.bind('username', function(ev, newVal, oldVal) { //-> ev: {EventObject} //-> newVal: 'nikica' //-> oldVal: 'veljko' }); route.attr({username: nikica}, true); </code></pre> <h3>Using different pathname root</h3> <p>can-route-pushstate has one additional property, <code>route.bindings.pushstate.root</code>, which specifies the part of that pathname that should not change. For example, if we only want to have pathnames within <code>http://example.com/contacts/</code>, we can specify a root like:</p> <pre><code class="language-js">route.bindings.pushstate.root = "/contacts/" route("{page}"); route.url({page: "list"}) //-> "/contacts/list" route.url({foo: "bar"}) //-> "/contacts/?foo=bar" </code></pre> <p>Now, all routes will start with <code>"/contacts/"</code>, the default <code>route.bindings.pushstate.root</code> value is <code>"/"</code>.</p> <h2>Planning route structure</h2> <p>Complications can arise if your route structure mimics the folder structure inside your app's public directory. For example, if you have a folder structure like the one in this url for your admin app...</p> <p><code>/admin/users/list.js</code></p> <p>... using a route of /admin/users on the same page that uses the list.js file will require the use of a trailing slash on all routes and links. The browser already learned that '/admin/users' is folder. Because folders were originally denoted by a trailing slash in a url, the browser will correct the url to be '/admin/users/'. While it is possible to add the trailing slash in routes and listen for them, any link to the page that omits the trailing slash will not trigger the route handler.</p> </section> <script type="text/javascript"> var docObject = {"src":{"path":"node_modules/can-route-pushstate/can-route-pushstate.md"},"description":"Changes [can-route] to use [pushstate](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history)\nto change the window's [pathname](https://developer.mozilla.org/en-US/docs/Web/API/URLUtils.pathname) instead\nof the [hash](https://developer.mozilla.org/en-US/docs/Web/API/URLUtils.hash).\n\n```js\nvar route = require(\"can-route-pushstate\");\n\nroute(\"{page}\", { page: \"home\" });\nroute.ready();\n\nroute.attr(\"page\", \"user\");\n\nlocation.pathname; // -> \"/user\"\n```\n\n","type":"module","title":"","types":[{"type":"Object","options":[{"name":"The","description":"pushstate object comprises several properties that configure the behavior of [can-route] to work with `history.pushstate`.\n","types":[{"type":"Object","options":[]}]}]}],"name":"can-route-pushstate","parent":"can-core","package":{"_args":[[{"raw":"can-route-pushstate@3.0.0","scope":null,"escapedName":"can-route-pushstate","name":"can-route-pushstate","rawSpec":"3.0.0","spec":"3.0.0","type":"version"},"/Users/kevin/dev/canjs"]],"_from":"can-route-pushstate@3.0.0","_id":"can-route-pushstate@3.0.0","_inCache":true,"_location":"/can-route-pushstate","_nodeVersion":"6.7.0","_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/can-route-pushstate-3.0.0.tgz_1476729989640_0.9208423118107021"},"_npmUser":{"name":"daffl","email":"daff@neyeon.de"},"_npmVersion":"3.10.3","_phantomChildren":{},"_requested":{"raw":"can-route-pushstate@3.0.0","scope":null,"escapedName":"can-route-pushstate","name":"can-route-pushstate","rawSpec":"3.0.0","spec":"3.0.0","type":"version"},"_requiredBy":["/"],"_resolved":"https://registry.npmjs.org/can-route-pushstate/-/can-route-pushstate-3.0.0.tgz","_shasum":"bdbd26f2f413459da79ac5d1503fa43c3c08f36c","_shrinkwrap":null,"_spec":"can-route-pushstate@3.0.0","_where":"/Users/kevin/dev/canjs","author":{"name":"Bitovi","email":"contact@bitovi.com","url":"http://bitovi.com"},"bit-docs":{"dependencies":{"bit-docs-glob-finder":"^0.0.5","bit-docs-dev":"^0.0.3","bit-docs-js":"^0.0.3","bit-docs-generate-readme":"^0.0.8"},"glob":{"pattern":"**/*.{js,md}","ignore":"node_modules/**/*"},"readme":{"apis":["can-route-pushstate"]},"parent":"can-route-pushstate"},"browser":{"transform":["cssify"]},"browserify":{"transform":["cssify"]},"bugs":{"url":"https://github.com/canjs/can-route-pushstate/issues"},"dependencies":{"can-event":"^3.0.1","can-route":"^3.0.0","can-util":"^3.0.1"},"description":"Pushstate for can-route","devDependencies":{"bit-docs":"0.0.6","can-define":"^0.8.1","can-map":"^3.0.0-pre.3","cssify":"^1.0.2","done-serve":"^0.2.0","donejs-cli":"^0.9.5","generator-donejs":"^0.9.0","jshint":"^2.9.1","steal":"^0.16.38","steal-qunit":"^0.1.1","steal-tools":"^0.16.0","testee":"^0.2.4"},"directories":{},"dist":{"shasum":"bdbd26f2f413459da79ac5d1503fa43c3c08f36c","tarball":"https://registry.npmjs.org/can-route-pushstate/-/can-route-pushstate-3.0.0.tgz"},"gitHead":"d513a3457cf7729ceddca92b8708e75f2dec6efd","homepage":"https://canjs.com","keywords":["canjs","canjs-plugin","donejs"],"main":"can-route-pushstate","maintainers":[{"name":"daffl","email":"daff@neyeon.de"},{"name":"garrettreed","email":"garrett@garrettreed.co"},{"name":"justinbmeyer","email":"justin@bitovi.com"},{"name":"matthewp","email":"matthew@matthewphillips.info"},{"name":"phillipskevin","email":"kphillips86@gmail.com"}],"name":"can-route-pushstate","optionalDependencies":{},"readme":"ERROR: No README data found!","repository":{"type":"git","url":"git://github.com/canjs/can-route-pushstate.git"},"scripts":{"build":"node build.js","develop":"done-serve --static --develop --port 8080","document":"bit-docs","jshint":"jshint ./*.js --config","postversion":"git push --tags && git checkout master && git branch -D release && git push","preversion":"npm test && npm run build","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","release:pre":"npm version prerelease && npm publish","test":"npm run jshint && npm run testee","testee":"testee test/test.html --browsers firefox","version":"git commit -am \"Update dist for release\" && git checkout -b release && git add -f dist/"},"system":{"configDependencies":["live-reload"],"npmAlgorithm":"flat"},"version":"3.0.0"},"comment":" ","pathToRoot":".."}; </script> </article> <footer><p>CanJS is part of <a href="http://donejs.com" target="_blank">DoneJS</a>. Created and maintained by the core <a href="https://donejs.com/About.html#section=section_Team" target="_blank">DoneJS team</a> and <a href="http://bitovi.com" target="_blank">Bitovi</a>. <strong>Currently 3.0.0.</strong></p></footer> </div> </div> </div> <script> steal = { instantiated: { "bundles/bit-docs-site/static.css!$css" : null } }; </script> <script type='text/javascript' data-main="bit-docs-site/static" src="./static/node_modules/steal/steal.production.js"></script> <script async defer src="https://buttons.github.io/buttons.js"></script> </body> </html>