Table of Contents for

JavaScript Web Applications

Before you begin defining and loading models in your Ember.js app, you must first define a store:

App.Store = DS.Store.extend();

The store is important for several reasons. First, it is responsible for instantiating the records that your application asks for. If you ever ask the store for the same record multiple times, it will always return the same record. This feature, called an identity map, means that different parts of your application don’t get out of sync when displaying the same data.

Second, the store is responsible for communicating the changes you make in your application, such as modifying attributes or creating new records, to the adapter.

The web is full of many different APIs. Some of them transmit JSON over HTTP; others send XML representations of the data. Additionally, newer web browsers support brand new modes of communication (like WebSockets), and can even natively handle binary data.

This means that we can no longer assume that sending JSON to RESTful HTTP endpoints is sufficient for all modern JavaScript web application.

Thankfully, Ember allows you to easily encapsulate how your application talks to your backend in an object called the adapter. The default adapter is called DS.RESTAdapter, and is designed to work with the conventions of RESTful HTTP APIs like those built using Ruby on Rails.

If you need something different, you can write a completely custom adapter that uses whatever combination of technologies you’d prefer. The best part is that because the adapter completely encapsulates the details of server communication, changing your server backend does not require any changes to the rest of your application!

To tell the store which adapter to use, just override its adapter property:

App.Store = DS.Store.extend({
  adapter: 'App.AwesomeWebSocketsAdapter'
});

Once you’ve defined your store, it’s time to set up your models. Each model should represent a specific kind of object, and is made up of attributes and relationships.

Start by creating a new subclass of DS.Model. To tell Ember which properties are attributes that should be fetched from the server, use the DS.attr helper:

App.User = DS.Model.extend({
  name: DS.attr('string')
});

The argument passed to DS.attr() tells Ember what type of attribute it is, so that it can be converted into the correct JavaScript type when the JSON response is received.

Sometimes, a model may have properties that can be derived from other properties. For example, imagine that you are writing a commenting system and want to give users a VIP badge once they’ve posted 100 comments.

There’s no need to save the fact that the user is a VIP to the server, since you’d just be duplicating information (the number of posts) that you already have. Instead, just define a computed property that uses the number of posts to compute whether or not the user is a VIP:

App.User = DS.Model.extend({
  name: DS.attr('string'),
  commentCount: DS.attr('number'),

  isVIP: function() {
    return this.get('commentCount') > 100;
  }.property('commentCount')
});

This defines a property called isVIP that is true when the user has more than 100 comments, or false if they have fewer than 100.

The arguments passed to the property() function tell Ember the computed property’s dependent keys. If one or more of a computed property’s dependent keys changes, Ember knows that it needs to recalculate the computed property (and update any templates on screen that may have been using it).

While computed properties really shine when used to build up higher-level properties from primitive attributes in your models, you should note that you can use computed properties everywhere, from your controllers to your views.

Once you’ve defined a model, you can create a new record and initialize its attributes:

var user = App.User.createRecord({
  name: "Tyrion Lannister",
  commentCount: 99
});

Make sure you access the properties of your models (as well as all Ember objects) using their get and set methods:

user.get('name');
assertEqual( user.get('name'), "Tyrion Lannister" );
assertEqual( user.get('isVIP'), false );

user.set('commentCount', 100);

// Now that commentCount has changed, the isVIP
// computed property updates automatically.
assertEqual( user.get('isVIP'), true );

Using these accessors ensures that templates have a chance to update themselves, computed properties can be recalculated if necessary, and any registered observers can be fired.

You can tell Ember that two models are related to one another by using the DS.hasMany and DS.belongsTo helpers. For example, you can describe a one-to-many relationship between Posts and Comments:

App.Post = DS.Model.extend({
  comments: DS.hasMany('App.Comment')
});

App.Comment = DS.Model.extend({
  post: DS.belongsTo('App.Post')
});

Once you’ve done that, you can treat the relationships like regular properties:

var post = App.Post.createRecord();
var comment = App.Post.createRecord();

// You can set the `belongsTo` side
comment.set('post', post);

// ...or add it to the parent `hasMany` array
post.get('comments').pushObject(comment);

Whichever side of the relationship you modify, Ember will automatically keep the inverse side up-to-date.

As you can see here, hasMany relationships behave like arrays. To make changes to them, use Ember’s array mutation methods to ensure that Ember is notified of the changes you make. For the full list, see the documentation for Ember.MutableArray and Ember.MutableEnumerable.

Above, you saw the {{#if}} helper in action. The {{#if}} helper renders its content only if the value provided to it evaluates to truthy (that is, it’s not 0, false, null, undefined, an empty array or an empty string).

You can also provide an {{else}} block in cases where the value is false:

{{#if isLoaded}}
  <h1>{{title}}</h1>
{{else}}
  Loading…
{{/if}}

There is an inverse of {{#if}}, {{#unless}}, that only renders its content if the value provided is falsy:

{{#unless isAdministrator}}
  Karma: {{karma}}
{{/unless}

By default, a template’s context is the controller with which it is paired. You can change the template context inside a block by using the {{#with}} helper:

<p>Name: {{firstName}} {{lastName}}</p>

{{#with profile}}
  <p>Bio: {{bio}}</p>
  <p>Address:  {{address}}</p>
{{/with}}

Inside the {{#with}} block, the bio and address properties will be looked up on the controller’s profile object, instead of the controller itself.

Finally, the {{#each}} helper allows you to enumerate an array of objects. Inside the {{#each}} block, the context is set to each item in the array in turn:

<h1>{{blogTitle}}</h1>
<ul class="posts">
{{#each posts}}
  <li>{{title}} by {{author}}</li>
{{/each}}

You can write application-specific helpers for formatting values to be displayed in your HTML. For example, we often want to properly pluralize words based on a number associated with them. Imagine we wanted a {{pluralize}} helper that could be used like this:

Remaining: {{pluralize remainingItems}}

If the value of remainingItems was 1, it would render:

Remaining: 1 item

Otherwise, it would render:

Remaining: 16 items

If we wanted to customize which word was pluralized, we could pass the the word option:

Remaining: {{pluralize remainingItems word="post"}}

This would render something like:

Remaining: 16 posts

As it turns out, making helpers like this is extremely easy. The above example can be implemented in only five lines of code:

Ember.Handlebars.registerBoundHelper('pluralize', function(value, options) {
  var word = options.hash.word || "item";
  if (value === 1) { return '1 ' + word; }
  return value + ' ' + word + 's';
});

This registers a pluralize helper that receives the value that you pass to it. Options passed to the helper (like word="post") can be accessed via the options.hash object.

Whatever value you return from this helper will be placed into the template at the appropriate location. If the value changes (in the examples above, remainingItems), the helper will be re-run and the DOM will be updated.

When you do need a controller, the first step is to determine what kind of model it will represent.

If it’s not representing a model at all (that is, it only responds to actions but does not augment or transform a model), define an Ember.Controller subclass:

App.AuthenticationController = Ember.Controller.extend({
  logout: function() {
    // ...put logout code here...
  }
});

You can send actions to a template’s controller using the {{action}} Handlebars helper:

<button {{action "logout"}}>Log Out</button>

By default, actions are sent when the user clicks on the element to which you have added the {{action}} helper. You can change how the action is triggered using the on attribute:

<button {{action "reload" on="doubleClick"}}>Double-click to reload</a>

You can also use this to trigger an action on a controller when the user submits a form:

<form {{action "submitForm" on="submit"}}>
  <label for="name">Name</label>
  {{view Ember.TextField valueBinding="name"}}
  <button type="submit">Submit</button>
</form>

This would trigger the submitForm action if the user clicked the Submit button, or if they hit the enter key while the form’s text field had focus.

Remember that one of the responsibilities of a controller is to present a model to one or more templates. It may augment or transform the properties of a model, in order to make them more appropriate for display to the user. Let’s look at an example to illustrate exactly what this means.

If your controller presents a single model to a template, you would define a subclass of Ember.ObjectController. In this example, the PostController represents a single App.Post model:

// Model
App.Post = DS.Model.extend({
  title: DS.attr('string'),
  comments: DS.hasMany('App.Comment')
});

// Controller
App.PostController = Ember.ObjectController.extend();

When the application starts, the router will tell the PostController to represent a Post record by setting its model property. (We’ll describe the router in detail later in this chapter. For now, just know that it is responsible for connecting controllers to models and templates to controllers.)

Now, let’s say the template connected to the PostController asks for its title property:

<h2>{{title}}</h2>

Here’s where things get really cool.

You probably noticed that we have not defined a title property on the PostController. But, because it’s a subclass of ObjectController, it will automatically look up the property on its underlying model. As far as the template is concerned, the controller and the model look exactly the same!

In other words, the ObjectController acts as a proxy to its model; any request for a given property returns the value of the property with the same name on the model.

Sometimes, though, you may store information in a way that is different than how it should be presented. For example, we might store the price of an item as an integer in the database. When we present it to the user, however, we’d like to format it as currency:

var attr = DS.attr;

App.Item = DS.Model.extend({
  name: attr('string'),
  price: attr('number')
});

App.ItemController = Ember.ObjectController.extend({
  price: function() {
    var price = this.get('model.price');
    return "$" + parseFloat(price).toFixed(2);
  }.property('model.price')
});

Then, in our template:

<table>
  <tr><th>Item</th><td>{{name}}</td>
  <tr><th>Price</th><td>{{price}}</td>
</table>

When we render the template for the user, they’ll see a nicely formatted price, like $10.50, instead of the integer 1050.

As far as the template is concerned, it’s getting information directly from the model. But we can selectively transform values to make them more appropriate for our templates, without having to put view logic in the model layer.

Besides the ObjectController, Ember has another model controller: Ember.ArrayController. This is used to present a collection of models to a template.

Like with ObjectController, ArrayController presents itself to templates as though it were the underlying model collection:

App.PostsController = Ember.ArrayController.extend();

<h1>Posts</h1>
{{#each post in controller}}
  <h2>{{post.title}}</h2>
{{/each}}

Perhaps the most important use of array controllers is to present aggregate information about the underlying models to the template.

For example, imagine our blog software tracks which posts have already been read by the user. We want to show a count of how many posts the user has left to read, before the supply of new posts is exhausted.

The one-two punch of array controllers and computed properties makes this extremely easy:

App.PostsController = Ember.ArrayController.extend({
  unreadCount: function() {
    return this.filterProperty('isUnread').get('length');
  }.property('@each.isUnread')
});

While not a lot of code, there is a lot going on here. Let’s break down exactly what this is doing:

We can use this synthesized property just like a normal property in our templates. For example, here’s what the posts template might look like:

<h1>My Cool Blog</h1>
{{#each post in controller}}
  <h2>{{post.title}}</h2>
{{/each}}

<p>Unread Posts: {{unreadCount}}</p>

As posts are added or removed, or the isUnread property of any of the Post models changes, the unreadCount value displayed to the user will be updated automatically. Not too shabby for three lines of code and a simple Handlebars template.

You can list the routes in your application by calling your router’s map method.

App.Router.map(function() {
  this.route("about");
  this.route("favorites");
});

This tells Ember to render the about template when the user visits /about, and to render the favorites template when they visit /favorites. There is also an implicit route from / to the index template.

(Note that you do not need to define App.Router; one is provided for you automatically when you created your Ember.Application.)

You can configure which URL a particular template gets mapped to by passing an optional path argument:

App.Router.map(function() {
  this.route("favorites", { path: '/favs' });
});

This would tell Ember to render the favorites template when the user visits /favs.

As you’ll recall, templates are always bound to a controller which represents a model. So far, we’ve learned how to display a template when a given URL is visited. But how do we tell it what model goes with it?

To do so, we need to first define a route handler. The route handler is an object that customizes how a particular route behaves. For example, to specify the model that is associated with a template, return it from model hook:

App.IndexRoute = Ember.Route.extend({
  model: function() {
    return App.Post.find();
  }
});

This tells Ember to render the index template with the results of App.Post.find() as its context.

We didn’t need to do any additional configuration to make the route handler start working. Just define the handler with the right name, and Ember will know what to do automatically.

The rules for figuring out the route handler name are easy: it’s the name of the route, capitalized, with “Route” at the end. For example:

App.Router.map(function() {
  this.route("favorites");
  this.route("mostPopular");
});

These routes would have the following route handlers associated:

Most of the routes in your application will usually be associated with a specific model. For example, you might have a /posts route, which displays a collection of posts, and a /comments route, which displays a collection of comments.

When a route corresponds to a particular model, use the resource() method instead of route():

App.Router.map(function() {
  this.resource('posts');
});

Resource routes can contain nested routes. This is useful for filtering a collection of models, for example.

Imagine that in our blog application we wanted to users to be able to filter posts by whether they were unread, or whether the user had favorited them:

App.Router.map(function() {
  this.resource('posts', function() {
    this.route('unread');
    this.route('favorites');
  });
});

The above route definition would create the following URLs, with associated controller, route handler, and template names:

Here is a good rule of thumb for figuring out which kind of route to create:

Often, parts of the URL will contain information (typically the ID) about the model that should be displayed. For example, if you are viewing the post with ID of 17, the URL might be /post/17. Obviously, you don’t want to have to enumerate a different route for each post in your database!

Instead, you can define a route with a dynamic segment. Dynamic segments allow you to match any URL that follows a pattern, and extract information about the model out of it:

App.Router.map(function() {
  this.resource('post', { path: '/post/:post_id' });
});

Note that the path for our post resource contains a dynamic segment: :post_id. Dynamic segments should start with a colon (:), contain the model name, and end with _id.

Instead of having to manually configure which model is associated with this route by defining a model hook on a route handler, Ember is smart enough to know that it should look for the App.Post model with the given ID.

Use the Handlebars {{linkTo}} helper to create a link that your user can click on to change what appears on screen. Imagine we’re creating a simple personal website that contains several different static pages that we want users to be able to switch between. Our routes look like this:

App.Router.map(function() {
  this.route('about');
  this.route('contact');
  this.route('resume');
});

In our about template, we can link to the contact and resume routes like so:

Welcome to my personal site!

Please {{#linkTo "resume"}}read my resume{{/linkTo}} or
{{#linkTo "contact"}}contact me!{{/linkTo}}

As the user clicks these links, the old template will be removed and the new one will be put in its place. This happens extremely quickly, because all of the templates have already been loaded and the browser does not need to talk to the server to display the new template.

Stitching together static pages like this is a great way to quickly prototype web applications, while writing practically no code.

What happens if we want to link to a route with a dynamic segment? How do we tell it which model that route should represent?

That turns out to be easy too: just pass the model as an argument to the {{linkTo}} helper.

For example, imagine we have the following route definitions:

App.Router.map(function() {
  this.resource('posts');
  this.resource('post', { path: '/posts/:post_id' });
});

The posts template displays a list of the blog posts the app knows about. Just include the current post as the second argument to {{linkTo}}, and Ember will take care of the rest:

<h1>My Cool Blog</h1>
<ul>
{{#each post in controller}}
  <li>{{#linkTo "post" post}}{{post.title}}{{/linkTo}}</li>
{{/each}}
</ul>