Ember.Location Namespace packages/ember-routing/lib/location/api.js:10

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.resource('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.resource('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.resource('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 into href attribute.

Calling setURL or replaceURL will not trigger onUpdateURL callbacks.

Show:

_finishDisconnections

private

Gets an outlet that is pending disconnection and then nullifys the object on the _outlet object.

_hasEquivalentView

(outletName, view) Boolean private

Determines if the view has already been created by checking if the view has the same constructor, template, and context as the view in the _outlets object.

Parameters:

outletName String
The name of the outlet we are checking
view Object
An Ember.View

Returns:

Boolean

connectOutlet

(outletName, view)

Manually fill any of a view's {{outlet}} areas with the supplied view.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var MyView = Ember.View.extend({
  template: Ember.Handlebars.compile('Child view: {{outlet "main"}} ')
});
var myView = MyView.create();
myView.appendTo('body');
// The html for myView now looks like:
// <div id="ember228" class="ember-view">Child view: </div>

var FooView = Ember.View.extend({
  template: Ember.Handlebars.compile('<h1>Foo</h1> ')
});
var fooView = FooView.create();
myView.connectOutlet('main', fooView);
// The html for myView now looks like:
// <div id="ember228" class="ember-view">Child view:
//   <div id="ember234" class="ember-view"><h1>Foo</h1> </div>
// </div>

Parameters:

outletName String
A unique name for the outlet
view Object
An Ember.View

create

(options) Object deprecated

This is deprecated in favor of using the container to lookup the location implementation as desired.

For example:

1
2
3
4
5
// Given a location registered as follows:
container.register('location:history-test', HistoryTestLocation);

// You could create a new instance via:
container.lookup('location:history-test');

Parameters:

options Object

Returns:

Object
an instance of an implementation of the `location` API

disconnectOutlet

(outletName)

Removes an outlet from the view.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
var MyView = Ember.View.extend({
  template: Ember.Handlebars.compile('Child view: {{outlet "main"}} ')
});
var myView = MyView.create();
myView.appendTo('body');
// myView's html:
// <div id="ember228" class="ember-view">Child view: </div>

var FooView = Ember.View.extend({
  template: Ember.Handlebars.compile('<h1>Foo</h1> ')
});
var fooView = FooView.create();
myView.connectOutlet('main', fooView);
// myView's html:
// <div id="ember228" class="ember-view">Child view:
//   <div id="ember234" class="ember-view"><h1>Foo</h1> </div>
// </div>

myView.disconnectOutlet('main');
// myView's html:
// <div id="ember228" class="ember-view">Child view: </div>

Parameters:

outletName String
The name of the outlet to be removed

getHash

private
Defined in packages/ember-routing/lib/location/api.js:184
Available since 1.4.0

Returns the current location.hash by parsing location.href since browsers inconsistently URL-decode location.hash.

https://bugzilla.mozilla.org/show_bug.cgi?id=483304

init

Sets the private _outlets object on the view.

registerImplementation

(name, implementation) deprecated

This is deprecated in favor of using the container to register the location implementation as desired.

Example:

1
2
3
4
5
6
7
Application.initializer({
 name: "history-test-location",

 initialize: function(container, application) {
   application.register('location:history-test', HistoryTestLocation);
 }
});

Parameters:

name String
implementation Object
of the `location` API