ember-data

Ember Data

Ember Data is a library for robustly managing model data in your Ember.js applications.

Ember Data is designed to be agnostic to the underlying persistence mechanism, so it works just as well with JSON APIs over HTTP as it does with streaming WebSockets or local IndexedDB storage.

It provides many of the facilities you'd find in server-side ORMs like ActiveRecord, but is designed specifically for the unique environment of JavaScript in the browser.

In particular, Ember Data uses Promises/A+-compatible promises from the ground up to manage loading and saving records, so integrating with other JavaScript APIs is easy.

Using Ember Data

Getting Ember Data

bower install ember-data --save

The latest passing build from the "master" branch is available on http://emberjs.com/builds/#/canary.

Similarly, the latest passing build from the "beta" branch can be found on http://emberjs.com/builds/#/beta

Or build ember-data.js yourself. Clone the repository and run npm run build:production after setup. You'll find ember-data.js in the dist directory.

Internet Explorer 8

Internet Explorer 8 support requires Ember 1.8.1 (which provides a polyfill for Object.create).

Instantiating the Store

In Ember Data, the store is responsible for managing the lifecycle of your models. Every time you need a model or a collection of models, you'll ask the store for it.

To create a store, you don't need to do anything. Just by loading the Ember Data library, all of the routes and controllers in your application will get a new store property. This property is an instance of DS.Store that will be shared across all of the routes and controllers in your app.

Defining Your Models

First thing's first: tell Ember Data about the models in your application. For example, imagine we're writing a blog reader app. Here's what your model definition would look like if you're using globals (that is, not something like or ember-cli):

var attr = DS.attr;
var hasMany = DS.hasMany;
var belongsTo = DS.belongsTo;

App.BlogPost = DS.Model.extend({
  title: attr(),
  createdAt: attr('date'),

  comments: hasMany('comment')
});

App.Comment = DS.Model.extend({
  body: attr(),
  username: attr(),

  post: belongsTo('blogPost')
});

If you're using ES6 modules (via ember-cli), your models would look like this:

// app/models/blog-post.js
var attr = DS.attr;
var hasMany = DS.hasMany;

export default DS.Model.extend({
  title: attr(),
  createdAt: attr('date'),

  comments: hasMany('comment')
});

// app/models/comment.js
var attr = DS.attr;
var belongsTo = DS.belongsTo;

export default DS.Model.extend({
  body: attr(),
  username: attr(),

  post: belongsTo('blogPost')
});

A Brief Note on Adapters

Without immediately diving in to the depths of the architecture, one thing you should know is that Ember Data uses an object called an adapter to know how to talk to your server.

An adapter is just an object that knows how to translate requests from Ember Data into requests on your server. For example, if I ask the Ember Data store for a record of type person with an ID of 123, the adapter translates that into an XHR request to (for example) api.example.com/v3/person/123.json.

By default, Ember Data will use the RESTAdapter, which adheres to a set of RESTful JSON conventions.

Ember Data also ships with the FixtureAdapter, useful for testing and prototyping before you have a server, and the ActiveModelAdapter, which is designed to work out-of-the-box with the ActiveModel::Serializers gem for Rails.

To learn more about adapters, including what conventions the RESTAdapter follows and how to build your own, see the Ember.js Guides: Connecting to an HTTP Server.

Fetching a Collection of Models

From your route or controller:

this.store.find('blogPost');

This returns a promise that resolves to the collection of records.

Fetching a Single Model

this.store.find('blogPost', 123);

This returns a promise that resolves to the requested record. If the record can't be found or there was an error during the request, the promise will be rejected.

Even More Documentation

For much more detail on how to use Ember Data, see the Ember.js Guides on models.

API Stability

Ember Data is still under active development and is currently beta quality. That being said, the API has largely stabilized and many companies are using it in production.

For details on anticipated changes before the 1.0 release, see the blog post The Road to Ember Data 1.0.

Building Ember Data

1. Ensure that Node.js is installed.
2. Run npm install to ensure the required dependencies are installed.
3. Run npm run build:production to build Ember Data. The builds will be placed in the dist/ directory.

Contribution

See CONTRIBUTING.md

How to Run Unit Tests

Setup

1. Install Node.js from http://nodejs.org or your favorite package manager.

2. Install Ember CLI and bower. npm install -g ember-cli bower

3. Run npm install inside the project root to install the JS dependencies.

In Your Browser

1. To start the development server, run npm start.

2. Visit http://localhost:4200

From the CLI

1. Install phantomjs from http://phantomjs.org

2. Run npm test

Changelog

Release 1.0.0-beta.17 (May 10, 2015)

• #2898 Pass requestType to buildURL @amiel
• #2790 Embedded records mixin should use the correct serialization key when deserialize configuration is set, Fixes #2556 @agrobbin
• #2933 Extracts InvalidError into a separate file and makes it a subclass of Ember.Error @twokul
• #2936 Introduce relationship.hasData @wecc
• #2940 [DOC] Fix for DS.Store#findMany @hibariya
• #2939 Snapshots unknown relationships @wecc
• #2958 adapter.serialize receives a snapshot @rague
• #2946 Handle null/empty type paths in build url mixin @vinilios
• #2961 Use new getter/setter for computed if available @wecc
• #2956 Clear meta data when unloading all records for a type. Fixes #2772 @runspired
• #2953 Do not assert reserved properties for static properties. @bmac
• #2959 Remove value from retrieveFromCurrentState CP @wecc
• #2999 Make unloadAll() unload all records, deprecate unloadAll(type) in favor ... @svox1
• #2992 Feature detect Ember.Registry rather than relying on version numbers @emberjs
• #2983 Do not prepend a / if namespace is absolute. @rwjblue
• #2966 Break buildURL into multiple requestType methods @thejameskyle
• #2980 [DOC] Use block params style {{#each}} @HeroicEric
• #2965 Make version check for ember-data strict @tricknotes
• #3035 Add method argument to key serialization docs @Dremora
• #3004 Fix serialization results in the documentation. @nathanhammond
• #3037 Reset Model#isReloading to false when request fails @pangratz
• #3022 Add missing urlForUpdateRecord to BuildURLMixin @wecc
• #3021 Remove unnecessary URL check in findHasMany @wecc
• #3036 Remove logic for camelCase-ing error keys in ActiveModelAdapter @pangratz
• #3030 ActiveModelAdapter camelizes keys for errors on 422 @bdvholmes
• #3026 [BUGFIX] AMS polymorphic type for namespaced models @artych
• #3032 use typeKey and typeClass instead of using type inconsistently @emberjs
• #3040 JSONSerializer#extractErrors respects custom key mappings @pangratz
• #3043 Fix bug where record rejected via find stayed in loading state @pangratz
• #3046 Documented the Model's rolledBack event @lolmaus
• #3054 Fix for deleting from ManyArray @wagenet
• #3055 Merge attrs from superclasses into their subclasses. @omghax
• #3056 Add more assertions for merged attributes from superclass @pangratz