ember-routing Module
Parent: ember
Ember.Location returns an instance of the correct implementation of
the location
API.
Implementations
You can pass an implementation name (hash
, history
, none
) to force a
particular implementation to be used in your application.
HashLocation
Using HashLocation
results in URLs with a #
(hash sign) separating the
server side URL portion of the URL from the portion that is used by Ember.
This relies upon the hashchange
event existing in the browser.
Example:
1 2 3 4 5 6 7 8 9 |
App.Router.map(function() { this.route('posts', function() { this.route('new'); }); }); App.Router.reopen({ location: 'hash' }); |
This will result in a posts.new url of /#/posts/new
.
HistoryLocation
Using HistoryLocation
results in URLs that are indistinguishable from a
standard URL. This relies upon the browser's history
API.
Example:
1 2 3 4 5 6 7 8 9 |
App.Router.map(function() { this.route('posts', function() { this.route('new'); }); }); App.Router.reopen({ location: 'history' }); |
This will result in a posts.new url of /posts/new
.
Keep in mind that your server must serve the Ember app at all the routes you define.
AutoLocation
Using AutoLocation
, the router will use the best Location class supported by
the browser it is running in.
Browsers that support the history
API will use HistoryLocation
, those that
do not, but still support the hashchange
event will use HashLocation
, and
in the rare case neither is supported will use NoneLocation
.
Example:
1 2 3 4 5 6 7 8 9 |
App.Router.map(function() { this.route('posts', function() { this.route('new'); }); }); App.Router.reopen({ location: 'auto' }); |
This will result in a posts.new url of /posts/new
for modern browsers that
support the history
api or /#/posts/new
for older ones, like Internet
Explorer 9 and below.
When a user visits a link to your application, they will be automatically
upgraded or downgraded to the appropriate Location
class, with the URL
transformed accordingly, if needed.
Keep in mind that since some of your users will use HistoryLocation
, your
server must serve the Ember app at all the routes you define.
NoneLocation
Using NoneLocation
causes Ember to not store the applications URL state
in the actual URL. This is generally used for testing purposes, and is one
of the changes made when calling App.setupForTesting()
.
Location API
Each location implementation must provide the following methods:
- implementation: returns the string name used to reference the implementation.
- getURL: returns the current URL.
- setURL(path): sets the current URL.
- replaceURL(path): replace the current URL (optional).
- onUpdateURL(callback): triggers the callback when the URL changes.
- formatURL(url): formats
url
to be placed intohref
attribute. - detect() (optional): instructs the location to do any feature detection
necessary. If the location needs to redirect to a different URL, it
can cancel routing by setting the
cancelRouterSetup
property on itself tofalse
.
Calling setURL or replaceURL will not trigger onUpdateURL callbacks.