Templates.helpers.link-to()

The {{link-to}} component renders a link to the supplied routeName passing an optionally supplied model to the route as its model context of the route. The block for {{link-to}} becomes the innerHTML of the rendered element:

{{#link-to 'photoGallery'}}
  Great Hamster Photos
{{/link-to}}

You can also use an inline form of {{link-to}} component by passing the link text as the first argument to the component:

{{link-to 'Great Hamster Photos' 'photoGallery'}}

Both will result in:

<a href="/hamster-photos">
  Great Hamster Photos
</a>

Supplying a tagName

By default {{link-to}} renders an <a> element. This can be overridden for a single use of {{link-to}} by supplying a tagName option:

{{#link-to 'photoGallery' tagName="li"}}
  Great Hamster Photos
{{/link-to}}

<li>
  Great Hamster Photos
</li>

To override this option for your entire application, see "Overriding Application-wide Defaults".

Disabling the link-to component

By default {{link-to}} is enabled. any passed value to the disabled component property will disable the link-to component.

static use: the disabled option:

{{#link-to 'photoGallery' disabled=true}}
  Great Hamster Photos
{{/link-to}}

dynamic use: the disabledWhen option:

{{#link-to 'photoGallery' disabledWhen=controller.someProperty}}
  Great Hamster Photos
{{/link-to}}

any passed value to disabled will disable it except undefined. to ensure that only true disable the link-to component you can override the global behaviour of Ember.LinkComponent.

Ember.LinkComponent.reopen({
  disabled: Ember.computed(function(key, value) {
    if (value !== undefined) {
      this.set('_isDisabled', value === true);
    }
    return value === true ? get(this, 'disabledClass') : false;
  })
});

see "Overriding Application-wide Defaults" for more.

Handling href

{{link-to}} will use your application's Router to fill the element's href property with a url that matches the path to the supplied routeName for your router's configured Location scheme, which defaults to Ember.HashLocation.

Handling current route

{{link-to}} will apply a CSS class name of 'active' when the application's current route matches the supplied routeName. For example, if the application's current route is 'photoGallery.recent' the following use of {{link-to}}:

{{#link-to 'photoGallery.recent'}}
  Great Hamster Photos
{{/link-to}}

will result in

<a href="/hamster-photos/this-week" class="active">
  Great Hamster Photos
</a>

The CSS class name used for active classes can be customized for a single use of {{link-to}} by passing an activeClass option:

{{#link-to 'photoGallery.recent' activeClass="current-url"}}
  Great Hamster Photos
{{/link-to}}

<a href="/hamster-photos/this-week" class="current-url">
  Great Hamster Photos
</a>

To override this option for your entire application, see "Overriding Application-wide Defaults".

Keeping a link active for other routes

If you need a link to be 'active' even when it doesn't match the current route, you can use the current-when argument.

{{#link-to 'photoGallery' current-when='photos'}}
  Photo Gallery
{{/link-to}}

This may be helpful for keeping links active for:

• non-nested routes that are logically related
• some secondary menu approaches
• 'top navigation' with 'sub navigation' scenarios

A link will be active if current-when is true or the current route is the route this link would transition to.

To match multiple routes 'space-separate' the routes:

{{#link-to 'gallery' current-when='photos drawings paintings'}}
  Art Gallery
{{/link-to}}

Supplying a model

An optional model argument can be used for routes whose paths contain dynamic segments. This argument will become the model context of the linked route:

Router.map(function() {
  this.route("photoGallery", {path: "hamster-photos/:photo_id"});
});

{{#link-to 'photoGallery' aPhoto}}
  {{aPhoto.title}}
{{/link-to}}

<a href="/hamster-photos/42">
  Tomster
</a>

Supplying multiple models

For deep-linking to route paths that contain multiple dynamic segments, multiple model arguments can be used. As the router transitions through the route path, each supplied model argument will become the context for the route with the dynamic segments:

Router.map(function() {
  this.route("photoGallery", { path: "hamster-photos/:photo_id" }, function() {
    this.route("comment", {path: "comments/:comment_id"});
  });
});

This argument will become the model context of the linked route:

{{#link-to 'photoGallery.comment' aPhoto comment}}
  {{comment.body}}
{{/link-to}}

<a href="/hamster-photos/42/comments/718">
  A+++ would snuggle again.
</a>

Supplying an explicit dynamic segment value

If you don't have a model object available to pass to {{link-to}}, an optional string or integer argument can be passed for routes whose paths contain dynamic segments. This argument will become the value of the dynamic segment:

Router.map(function() {
  this.route("photoGallery", { path: "hamster-photos/:photo_id" });
});

{{#link-to 'photoGallery' aPhotoId}}
  {{aPhoto.title}}
{{/link-to}}

<a href="/hamster-photos/42">
  Tomster
</a>

When transitioning into the linked route, the model hook will be triggered with parameters including this passed identifier.

Allowing Default Action

By default the {{link-to}} component prevents the default browser action by calling preventDefault() as this sort of action bubbling is normally handled internally and we do not want to take the browser to a new URL (for example).

If you need to override this behavior specify preventDefault=false in your template:

{{#link-to 'photoGallery' aPhotoId preventDefault=false}}
  {{aPhotoId.title}}
{{/link-to}}

Overriding attributes

You can override any given property of the Ember.LinkComponent that is generated by the {{link-to}} component by passing key/value pairs, like so:

{{#link-to  aPhoto tagName='li' title='Following this link will change your life' classNames='pic sweet'}}
  Uh-mazing!
{{/link-to}}

See Ember.LinkComponent for a complete list of overrideable properties. Be sure to also check out inherited properties of LinkComponent.

Overriding Application-wide Defaults

{{link-to}} creates an instance of Ember.LinkComponent for rendering. To override options for your entire application, reopen Ember.LinkComponent and supply the desired values:

Ember.LinkComponent.reopen({
  activeClass: "is-active",
  tagName: 'li'
})

It is also possible to override the default event in this manner:

Ember.LinkComponent.reopen({
  eventName: 'customEventName'
});