#action - #attach() - #beforeNavigation() - #component - #container - #detach() - #draw() - #errorHandler() - #flash - #namespace - #navigate() - #navigateTo() - #notify() - #mount() - #params - #query - #redirectTo - #resource - #routeFor() - #show() - #start() - #stop() - #vars

#action

This property holds the action name of the current route.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.many('articles');
});
router.navigateTo('articles/123/edit');
console.log(router.action); // => "edit"

#attach()

Usage

• attach(listener)

This method register the listener as the target of notification from this router.

A listener must have #refresh() method. Typically, a listener is an instance of Cape.Component, Cape.ResourceAgent or Cape.CollectionAgent.

See #notify() for details.

#beforeNavigation()

See Before-Navigation Callbacks.

#component

This property holds the component name of the current route in lower case.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.many('articles');
  m.namespace('admin', function(m) {
    m.many('articles');
  });
});
router.navigateTo('articles/123/edit');
console.log(router.component); // => "edit"
router.navigateTo('admin/articles/123/edit');
console.log(router.component); // => "edit"

#container

This property holds the container name of the current route in lower case.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.many('articles');
  m.namespace('admin', function(m) {
    m.many('articles');
  });
});
router.navigateTo('articles/123/edit');
console.log(router.container); // => "articles"
router.navigateTo('admin/articles/123/edit');
console.log(router.container); // => "admin.articles"

#detach()

Usage

• detach(component)

This method removes the component from the list of targets of notification from this router.

See #notify() for details.

#draw()

Usage

• draw(function)

This method specify a function that takes a RoutingMapper object and defines routes.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.root('dashboard');
  m.page('about', 'docs.about');
  m.many('articles');
})

In the above example, the argument m is a RoutingMapper object.

#errorHandler()

See Before-Navigation Callbacks.

#flash

Usage

• flash[key] = value
• flash.key = value

Set an arbitrary value (object, string, integer, etc.) to the flash object, which is emptied after each navigation.

Example

router.flash.alert = 'The specified article has been deleted.';
router.navigateTo('articles');

#container

This property holds the namespace of the current route in lower case.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.many('articles');
  m.namespace('admin', function(m) {
    m.many('articles');
  });
});
router.navigateTo('articles/123/edit');
console.log(router.namespace); // => null
router.navigateTo('admin/articles/123/edit');
console.log(router.namespace); // => "admin"

#navigate()

This method is deprecated as of v1.4.

Usage

• navigate(hash)

Sets the anchor part (begins with a # symbol) of the browser’s current URL to hash. See #navigateTo().

#navigateTo() 1.4

Usage

• navigateTo(hash)

This method sets the anchor part (begins with a # symbol) of the browser’s current URL to hash.

When before-navigation callbacks are registered, they are executed before changing the anchor part of URL. If the before-navigation callbacks select other string for hash, it will be set to the anchor part of the browser’s current URL.

After setting the anchor part of URL, this method choose a component according to the routing table.

When this component is different from the component which is mounted currently, it unmounts the latter, executes the #notify() method, and mounts the former. When this component is same with the component mounted currently, it just executes the #notify() method.

If you don’t want the #notify() method to be executed, use #show() instead.

Usage

• navigateTo(hash, params)

Sets the anchor part (begins with a # symbol) of the browser’s current URL to hash adding query string which is constructed from params.

Example

router.navigateTo('articles', { page: '2' });

Usage

• navigateTo(hash, params, options)

Same as the previous usage, except that the flash messages are set using options.

Example

router.navigateTo('articles', {}, { notice: 'A new article has been uploaded.' });
router.navigateTo('articles/new', {}, { alert: 'Failed to upload a new article.' });

#notify()

Usage

• notify()

This method triggars the notification process, which calls the #refresh() method of all listeners registerd as targets of notification of this data store.

Eventually, each listener executes its #refresh() method, which may have to be defined by developers.

The #notify() method is executed after each time the #navigateTo() method is called.

#mount()

Usage

• mount(id)

This method specifies the id of the HTML element which this router inserts the components into.

Example

<div>
  <a href="#">Top</a>
  <a href="#about">About</a>
  <a href="#help">Help</a>
</div>

<div id="main"></div>

<script>
var router = new Cape.Router();
router.draw(function(m) {
  m.root('top_page');
  m.page('about', 'about_page');
  m.page('help', 'help_page');
})
router.mount('main');
</script>

In the example above, components are mounted into the <div> element whose id is 'main'.

#params

This property holds a set of key-value pairs, which represents the parameters embedded in the main part (before the first ‘?’ symbol) of hash.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.page('help/:name', 'help.item');
  m.many('articles', function(m) {
    m.many('comments');
  });
})
router.navigateTo('help/password');
// router.params.name === 'password'
router.navigateTo('articles/123')
// router.params.id === '123'
router.navigateTo('articles/123/comments/7')
// router.params.article_id === '123'
// router.params.id === '7'

#query

This property holds a set of key-value pairs, which represents the parameters embedded in the query part (after the first ‘?’ symbol) of hash .

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.many('articles')
})
router.navigateTo('articles')
// router.query === {}
router.navigateTo('articles?page=2')
// router.query.page === '2'
router.navigateTo('articles?page=2&deleted')
// router.query.page === '2'
// router.query.deleted === ''

#redirectTo()

This method sets the anchor part (begins with a # symbol) of the browser’s current URL to hash.

Unlike #navigateTo() method, before-navigation callbacks are not executed before changing the anchor part of URL.

After setting the anchor part of URL, this method choose a component according to the routing table.

When this component is different from the component mounted currently, it unmounts the latter, executes #notify() method and mounts the former. When this component is same with the component which is mounted currently it just executes #notify() method.

Usage

• redirectTo(hash)

Sets the anchor part (begins with a # symbol) of the browser’s current URL to hash.

Example

router.redirectTo('docs/help');

Usage 1.5

• redirectTo(hash, params)

Sets the anchor part (begins with a # symbol) of the browser’s current URL to hash adding query string which is constructed from params.

Example

router.redirectTo('articles', { page: '2' });

Usage 1.5

• redirectTo(hash, params, options)

Same as the previous usage, except that the flash messages are set using options.

Example

router.redirectTo('articles', {}, { notice: 'A new article has been uploaded.' });
router.redirectTo('articles/new', {}, { alert: 'Failed to upload a new article.' });

Usage Deprecated

• redirectTo(hash, options)

This usage is deprecated as of version 1.5.

For backward compatibility, if the second argument has ‘notice’ or ‘alert’ as a key and the third argument is not given, the second argument should be treated as options.

Example

router.redirectTo('articles', { notice: 'A new article has been uploaded.' });
router.redirectTo('articles/new', { alert: 'Failed to upload a new article.' });

#resource

This property holds the resource name of the current route in lower case.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.one('account');
  m.many('articles', function(m) {
    m.many('comments');
  });
  m.namespace('admin', function(m) {
    m.many('articles');
  });
});
router.navigateTo('account/edit');
console.log(router.resource); // => "account"
router.navigateTo('articles/123/edit');
console.log(router.resource); // => "articles"
router.navigateTo('articles/123/comments');
console.log(router.resource); // => "articles/comments"
router.navigateTo('admin/articles/123/edit');
console.log(router.resource); // => "articles"

#routeFor()

Usage

• routeFor(hash)

This method returns the first route matching to the hash, if any.

Example

var router = new Cape.Router();
router.draw(function(m) {
  m.namespace('admin', function(m) {
    m.many('articles');
  });
});
var route = router.routeFor('admin/articles/123/edit');

#show()

Usage

• show(componentClass)

This method mounts an instance of componentClass class.

Unlike #navigateTo(), it does neither change the anchor part of current URL, nor call the #notify() method.

Example

router.show(LoginForm);

Usage 1.5

• show(componentClass, params)

Mounts an instance of componentClass class passing values to the query attribute of the router.

Example

router.show(LoginForm, { email: 'alice@example.com', checked: '1' });
console.log(router.query.email); // => 'alice@example.com'
console.log(router.query.checked); // => '1'

#start()

With this method call, routers begin to listen to hashchange events.

#stop()

With this method call, routers stop to listen to hashchange events.

#vars

Usage

• vars[key] = value
• vars.key = value

Set an arbitrary value (object, string, integer, etc.) to the vars object.

Example

router.vars.signedIn = Date.now();
router.vars.currentUser = { id: 99, name: 'john', privileged: true };