can-route

can-route

Note: This is the CanJS can-route module. The old can-route has been renamed to did-route. Many thanks to @michaelrhodes for letting us use the can-route module name.

• route(template [, defaults])
  • route.map(MapConstructor)
  • route.map(mapInstance)
  • route.param(data)
  • route.deparam(url)
  • route.ready()
  • route.url(data [, merge])
  • route.link(innerText, data, props [, merge])

API

route(template [, defaults])

Create a route matching rule. Optionally provide defaults that will be applied to the [can-map] when the route matches.

route(":page", { page: "home" });

Will apply cart when the url is #cart and home when the url is #.

1. template {String}: the fragment identifier to match. The fragment identifier should start with either a character (a-Z) or colon (:). Examples:

route(":foo")
route("foo/:bar")

1. defaults {Object}: An object of default values.

• returns {can.route}:

route.map(MapConstructor)

Binds can-route to an instance based on a constructor. A new instance will be created and bound to:

var ViewModel = Map.attr({
	define: {
		page: {
			set: function(page){
				if(page === "user") {
					this.verifyLoggedIn();
				}
				return page;
			}
		}
	}
});

route.map(ViewModel);

1. MapConstructor {can-map}: A can-map constructor function. A new can-map instance will be created and used as the can-map internal to can-route.

route.map(mapInstance)

Bind can-route to an instance of a map.

var map = new Map({
	page: "home"
});

route.map(map);

map.attr("page", "user");
// location.hash -> "#user"

1. mapInstance {can-map}: A can-map instance, used as the can-map internal to can-route.

route.param(data)

1. object {data}: The data to populate the route with.

• returns {String}: The route, with the data populated in it.

route.deparam(url)

Extract data from a url, creating an object representing its values.

route(":page");

var result = route.deparam("page=home");
console.log(result.page); // -> "home"

1. url {String}: A route fragment to extract data from.

• returns {Object}: An object containing the extracted data.

route.ready()

Sets up the two-way binding between the hash and the can-route observable map and sets the route map to its initial values.

route(":page", { page: "home" }));

route.ready();
route.attr("page"); // -> "home"

• returns {canRoute}: The can-route object.

route.url(data [, merge])

Make a URL fragment that when set to window.location.hash will update can-route's properties to match those in data.

route.url({ page: "home" });
// -> "#!page=home"

1. data {Object}: The data to populate the route with.
2. merge {Boolean}: Whether the given options should be merged into the current state of the route.

• returns {String}: The route URL and query string.

route.link(innerText, data, props [, merge])

Make an anchor tag (<A>) that when clicked on will updatecanRoute's properties to match those in data.

1. innerText {Object}: The text inside the link.
2. data {Object}: The data to populate the route with.
3. props {Object}: Properties for the anchor other than href.
4. merge {Boolean}: Whether the given options should be merged into the current state of the route.

• returns {String}: A string with an anchor tag that points to the populated route.

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

Tests can run in the browser by opening a webserver and visiting the test.html page. Automated tests that run the tests from the command line in Firefox can be run with

npm test