can-route-pushstate.md

@module {RoutePushstate} can-route-pushstate @parent can-routing @collection can-core @package ./package.json @group can-route-pushstate.prototype prototype

@description An observable that can be used as [can-route]'s [can-route.urlData].

@type {RoutePushstate}

can-route-pushstate exports a RoutePushstate constructor function that configure [can-route] to use pushstate to change the window's pathname instead of the hash

@type {Object} The pushstate object comprises several properties that configure the behavior of [can-route] to work with history.pushstate.

@body

Use

can-route-pushstate exports an observable that can be used with [can-route]. To start using can-route-pushstate set the [can-route.urlData] property:

import { route, RoutePushstate } from "can";

route.urlData = new RoutePushstate();

Creating and changing routes

To create routes use [can-route.register] like:

route.urlData = new RoutePushstate();

route.register( "{page}", { page: "homepage" } );
route.register( "contacts/{username}" );
route.register( "books/{genre}/{author}" );

route.start(); // Initializes can-route

Do not forget to [can-route.start initialize] can-route after creating all routes, do it by calling route.start().

Listening changes on matched route

As can-route contains a map that represents window.location.pathname, you can bind on it.

To bind to specific attributes on [can-route] you can listen to your viewModel's property changes (viewModel.on() if using [can-define/map/map]).

Using different pathname root

can-route-pushstate has one additional property, [can-route-pushstate.prototype.root], which specifies the part of that pathname that should not change. For example, if we only want to have pathnames within http://example.com/contacts/, we can specify a root like:

route.urlData = new RoutePushstate();
route.urlData.root = "/contacts/";
route.register( "{page}" );
route.url( { page: "list" } ); //-> "/contacts/list"
route.url( { foo: "bar" } );   //-> "/contacts/?foo=bar"

Now, all routes will start with "/contacts/". The default route.urlData.root value is "/".

Updating the current route

can-route-pushstate also allows changes to the current route state without creating a new history entry. This behavior can be controlled using the replaceStateOn, replaceStateOff, and replaceStateOnce methods.

Enable the behavior by calling replaceStateOn with specified route property keys like:

const push = new RoutePushstate();
route.urlData = push;
push.replaceStateOn( "page", "action" );
route.set( "page", "dashboard" ); // Route changes, no new history record

To return back to normal, call replaceStateOff with the specified route property keys like:

push.replaceStateOff( "action" );
route.set( "action", "remove" ); // Route changes, new history record is created

The behavior can be configured to occur only once for a specific property using replaceStateOnce like:

push.replaceStateOnce( "page" );
route.set( "page", "dashboard" ); // No new history record
route.set( "page", "search" ); // New history record is created

Planning route structure

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...

/admin/users/list.js

... 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.