dojo/router

Contents

• dojo/router
  • Introduction
  • Usage
  • Examples
  • See Also

dojo/router is a package that provides the ability to map hash based structures to callbacks.

Introduction

dojo/router is designed to allow the mapping of the browser hash to a callback, so that when the hash is updated, it can be used to direct to a callback. It also allows for parameterization of the hash, so that parts of the hash string can be parsed out and used as variables within the callback.

Usage

Usage is requiring in the module, registering any callbacks and then starting the router:

require(["dojo/router"], function(router){
  router.register("/something/:id", function(evt){
    // Will fire when the hash matches
    // evt.params.id will contain what is passed in :id
  });

  // Startup must be called in order to "activate" the router
  router.startup();
});

require(["dojo/router"], function(router){ router.register("/something/:id", function(evt){ // Will fire when the hash matches // evt.params.id will contain what is passed in :id }); // Startup must be called in order to "activate" the router router.startup(); });

register()

Allows the registration of a hash pattern and its associated callback. register() takes two arguments:

Argument	Type	Description
route	String|RegExp	A string or regular expression that should be used for matching hash changes.
callback	Function	When the hash matches a pattern as described in the route, this callback will be executed.

When provided a RegExp for the route:

• Matching is performed, and the resulting capture groups are passed through to the callback as an array.

When provided a string for the route:

• The string is parsed as a URL-like structure, like /foo/bar
• If any portions of that URL are prefixed with a colon (:), they will be parsed out and provided to the callback as in the argument object in the params property.
• If the last piece of the URL-like structure is prefixed with a star (*) instead of a colon, it will be replaced in the resulting RegExp generated by the router with a greedy (.+) match and anything remaining on the hash will be provided as a property on the object passed into the callback. Think of it like a basic means of globbing the end of a route.

The callback function will be called with an event argument that has several properties:

• params: Either an array or object of properties pulled from the new hash
• oldPath: The hash in its state before the change
• newPath: The new hash being shifted to
• preventDefault: A method that will stop hash changes from being actually applied to the active hash. This only works if the hash change was initiated using dojo/router::go(), as changes initiated more directly to the location.hash property will already be in place.
• stopImmediatePropagation: When called, will stop any further bound callbacks on this particular route from being executed. If two distinct routes are bound that are different, but both happen to match the current hash in some way, this will not keep other routes from receiving notice of the change.

register() returns a handle object that can be used to unregister the callback or add additional callbacks to the same route:

require(["dojo/router"], function(router){
  var handle = router.register("/some/path", function(evt){
    // ...
  });

  handle.register(function(evt){
    // ...
  }, true);

  handle.remove();
});

require(["dojo/router"], function(router){ var handle = router.register("/some/path", function(evt){ // ... }); handle.register(function(evt){ // ... }, true); handle.remove(); });

The handle’s register() function takes an optional second argument of isBefore which if true will insert the callback before the current handle’s callback. It defaults to false.

registerBefore()

This function works just like register() but will insert the callback before any other callbacks registered for the same hash pattern.

startup()

Starts up the router and registers for notification of hash changes.

go()

A convenience function for changing the hash. It means you do not need to require dojo/hash directly. It also synchronously fires off any routes that match:

require(["dojo/router"], function(router){
  router.register("/foo/bar", function(evt){
    // ...
  });

  router.startup();

  router.go("/foo/bar");
});

require(["dojo/router"], function(router){ router.register("/foo/bar", function(evt){ // ... }); router.startup(); router.go("/foo/bar"); });

Examples

This example demonstrates the basic usage of dojo/router by fetching some content on a hash change.

require(["dojo/router", "dojo/dom", "dojo/on", "dojo/request", "dojo/json", "dojo/domReady!"],
function(router, dom, on, request, JSON){
  router.register("/foo/bar", function(evt){
    evt.preventDefault();
    request.get("request/helloworld.json", {
      handleAs: "json"
    }).then(function(response){
      dom.byId("output").innerHTML = JSON.stringify(response);
    });
  });

  router.startup();

  on(dom.byId("changeHash"), "click", function(){
    router.go("/foo/bar");
  });
});

require(["dojo/router", "dojo/dom", "dojo/on", "dojo/request", "dojo/json", "dojo/domReady!"], function(router, dom, on, request, JSON){ router.register("/foo/bar", function(evt){ evt.preventDefault(); request.get("request/helloworld.json", { handleAs: "json" }).then(function(response){ dom.byId("output").innerHTML = JSON.stringify(response); }); }); router.startup(); on(dom.byId("changeHash"), "click", function(){ router.go("/foo/bar"); }); });

<button type="button" id="changeHash">Change Hash</button>
<div id="output"></div>

<button type="button" id="changeHash">Change Hash</button> <div id="output"></div>

See Also

• dojo/hash - Module for managing the browsers hash.

Table of Contents

• dojo/router
  • Introduction
  • Usage
    • register()
    • registerBefore()
    • startup()
    • go()
  • Examples
  • See Also