Class: SC.routes

SC.routes manages the browser location. You can change the hash part of the current location. The following code

SC.routes.set('location', 'notes/edit/4');

will change the location to http://domain.tld/my_app#notes/edit/4. Adding routes will register a handler that will be called whenever the location changes and matches the route:

SC.routes.add(':controller/:action/:id', MyApp, MyApp.route);

You can pass additional parameters in the location hash that will be relayed to the route handler:

SC.routes.set('location', 'notes/show/4?format=xml&language=fr');

The syntax for the location hash is described in the location property documentation, and the syntax for adding handlers is described in the add method documentation.

Browsers keep track of the locations in their history, so when the user presses the 'back' or 'forward' button, the location is changed, SC.route catches it and calls your handler. Except for Internet Explorer versions 7 and earlier, which do not modify the history stack when the location hash changes.

SC.routes also supports HTML5 history, which uses a '/' instead of a '#' in the URLs, so that all your website's URLs are consistent.

Defined in: routes.js

Field Summary

Instance Methods

Field Detail

baseURI

The base URI used to resolve routes (which are relative URLs). Only used when usesHistory is equal to YES.

The build tools automatically configure this value if you have the html5_history option activated in the Buildfile:

config :my_app, :html5_history => true

Alternatively, it uses by default the value of the href attribute of the tag of the HTML document. For example:

<base href="http://domain.tld/my_app">

The value can also be customized before or during the execution of the main() method.

See:
http://www.w3.org/TR/html5/semantics.html#the-base-element
usesHistory

A read-only boolean indicating whether or not HTML5 history is used. Based on the value of wantsHistory and the browser's support for pushState.

See:
wantsHistory
wantsHistory

Set this property to YES if you want to use HTML5 history, if available on the browser, instead of the location hash.

HTML 5 history uses the history.pushState method and the window's popstate event.

By default it is NO, so your URLs will look like:

http://domain.tld/my_app#notes/edit/4

If set to YES and the browser supports pushState(), your URLs will look like:

http://domain.tld/my_app/notes/edit/4

You will also need to make sure that baseURI is properly configured, as well as your server so that your routes are properly pointing to your SproutCore application.

See:
http://dev.w3.org/html5/spec/history.html#the-history-interface

Instance Method Detail

add(route, target, method)

Adds a route handler. Routes have the following format:

  • 'users/show/5' is a static route and only matches this exact string,
  • ':action/:controller/:id' is a dynamic route and the handler will be called with the 'action', 'controller' and 'id' parameters passed in a hash,

  • '*url' is a wildcard route, it matches the whole route and the handler will be called with the 'url' parameter passed in a hash.

    Route types can be combined, the following are valid routes:

  • 'users/:action/:id'

  • ':controller/show/:id'
  • ':controller/*url'
Parameters:
route String
the route to be registered
target Object
the object on which the method will be called, or directly the function to be called to handle the route
method Function
the method to be called on target to handle the route, can be a function or a string
deparam(string, coerce)
Function to create an object out of a urlencoded param string.
Parameters:
string String
the parameter string
coerce Boolean
coerce the values? (Default NO)
hashChange(event)

Event handler for the hashchange event. Called automatically by the browser if it supports the hashchange event, or by our timer if not.

Parameters:
event
informLocation(key, value)
Parameters:
key
value
location(key, value)

The current location hash. It is the part in the browser's location after the '#' mark.

The following code

SC.routes.set('location', 'notes/edit/4');

will change the location to http://domain.tld/my_app#notes/edit/4 and call the correct route handler if it has been registered with the add method.

You can also pass additional parameters. They will be relayed to the route handler. For example, the following code

SC.routes.add(':controller/:action/:id', MyApp, MyApp.route);
SC.routes.set('location', 'notes/show/4?format=xml&language=fr');

will change the location to http://domain.tld/my_app#notes/show/4?format=xml&language=fr and call the MyApp.route method with the following argument:

{ route: 'notes/show/4',
  params: '?format=xml&language=fr',
  controller: 'notes',
  action: 'show',
  id: '4',
  format: 'xml',
  language: 'fr' }

The location can also be set with a hash, the following code

SC.routes.set('location',
  { route: 'notes/edit/4', format: 'xml', language: 'fr' });

will change the location to http://domain.tld/my_app#notes/show/4?format=xml&language=fr.

The 'notes/show/4&format=xml&language=fr' syntax for passing parameters, using a '&' instead of a '?', as used in SproutCore 1.0 is still supported.

Parameters:
key
value
locationDidChange()

Observer of the 'location' property that calls the correct route handler when the location changes.

ping()

You usually don't need to call this method. It is done automatically after the application has been initialized.

It registers for the hashchange event if available. If not, it creates a timer that looks for location changes every 150ms.

popState(event)
Parameters:
event
trigger()

Triggers a route even if already in that route (does change the location, if it is not already changed, as well).

If the location is not the same as the supplied location, this simply lets "location" handle it (which ends up coming back to here).

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)