Ember Data is a library for loading models from a persistence layer (such as a JSON API), updating those models, then saving the changes. 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.
This release is definitely alpha-quality. The basics work, but there are for sure edge cases that are not yet handled. Please report any bugs or feature requests, and pull requests are always welcome.
Yes.
No.
- Manipulate associations client-side
- Handle error states
- Better built-in attributes
Every application has one or more stores. The store will be the repository that holds loaded models, and is responsible for retrieving models that have not yet been loaded.
App.store = DS.Store.create();You can tell the store how to talk to your backend by specifying an adapter.
By default, the store will assume a RESTful JSON API. However, you can specify
alternate adapters by setting the adapter property:
App.store = DS.Store.create({
adapter: 'DS.localStorageAdapter'
});NOTE: The default RESTful adapter is in progress. For Rails applications, it
will work seamlessly with the active_model_serializers gem's conventions. In
the meantime, see the section on rolling your own adapter.
For every type of data you'd like to represent, create a new subclass of
DS.Model:
App.Person = DS.Model.extend();You can specify which attributes a model has by using DS.attr. An attribute
represents a value that will exist in the underlying JSON representation of
the object, and which you also want to expose through the Ember object.
You can use attributes just like any other property, including as part of a computed property. These attributes ensure that the values can be retrieved from the underlying JSON representation and persisted later as needed.
App.Person = DS.Model.extend({
firstName: DS.attr('string'),
lastName: DS.attr('string'),
fullName: function() {
return this.get('firstName') + ' ' + this.get('lastName');
}.property('firstName', 'lastName'),
birthday: DS.attr('date')
});Valid attribute types are string, integer, boolean, and date. You
can also register custom attribute types. For example, here's a boolString
attribute type that converts booleans into the string "Y" or "N":
DS.attr.transforms.boolString: {
from: function(serialized) {
if (serialized === 'Y') {
return true;
}
return false;
},
to: function(deserialized) {
if (deserialized) {
return "Y";
}
return "N";
}
}Built-in attribute types are currently very primitive. Please help us flesh them out with patches and unit tests!
By default, the store uses a model's id attribute as its primary key.
You can specify a different key by setting the primaryKey property:
DS.Model.extend({
primaryKey: 'guid'
});Models can be associated with other models. Use the DS.hasMany() method
to create a relationship from one model to others:
App.Tag = DS.Model.extend({
name: DS.attr('string')
});
App.Person = DS.Model.extend({
name: DS.attr('string'),
tags: DS.hasMany(App.Tag)
});In this case, associations should be stored as an array of IDs. The JSON for a Person object might look like this:
{
"id": 1,
"name": "Tom Dale",
"tags": [1, 2]
}and the JSON for the Tag objects would be represented like this:
[{
"id": 1,
"name": "good-looking"
},
{
"id": 2,
"name": "not-too-bright"
}]However, imagine the JSON returned from the server for a Person looked like this:
{
"id": 1,
"name": "Tom Dale",
"tags": [{
"id": 1,
"name": "good-looking"
},
{
"id": 2,
"name": "not-too-bright"
}]
}In this case, instead of the association being an array of ids, it is an
array of embedded objects. To have the store understand these correctly,
set the embedded option to true:
App.Person = DS.Model.extend({
tags: DS.hasMany(Tag, { embedded: true })
});It is also possible to change the data attribute that an association is mapped to. Suppose the JSON for a person looked like this:
{
"id": 2,
"name": "Carsten Nielsen",
"tag_ids": [1, 2]
}In this case, you would specify the key in the association like this:
App.Person = DS.Model.extend({
tags: DS.hasMany(Tag, { key: 'tag_ids' })
});You can retrieve a model by its unique ID by using the find method:
var model = App.store.find(App.Person, 1);If that specific model has already been loaded, it will be returned immediately. Otherwise, an empty object will be returned. You can setup bindings and observers on the properties you're interested in; as soon as the data returns from the persistence layer, all of the attributes you specified will be updated automatically.
Besides find(), all of the methods described below operate in a similar
fashion. By returning empty objects, you can use the models returned from
the store immediately in your views. They will be updated automatically
as soon as the data is loaded.
You can make a server query by passing an Object as the second parameter to
find. In this case, you will get back a ModelArray object.
App.people = App.store.find(App.Person, { page: 1 });At first, this people array will have no elements. Later, we will see how
your adapter will populate the people. Because the people array is an
Ember Array, you can immediately insert it into the DOM. When it becomes
populated later, Ember's bindings will automatically update the DOM.
<ul>
{{#each App.people}}
<li>{{fullName}}</li>
{{/each}}
</ul>This will allow you to ask the store for an Array of information, and keep your view code completely agnostic to how the Array becomes populated.
Note: If manually retrieving models from a model array, you must use
the objectAt(index) method. Since the object is not a JavaScript Array,
using the [] notation will not work.
To find all models of a certain type, use the store's findAll() method:
var models = App.store.findAll(App.Person);All currently loaded models of that type will be immediately returned
in a ModelArray. Your adapter will also have an opportunity to load
additional models of that type if necessary.
You can filter all models of a type by calling the store's filter()
method with a function that determines whether the model should
be included or not. To avoid materializing model objects needlessly, only
the raw data hash returned from the persistence layer is passed.
To include a model, return true. If a model should not be included,
return false or undefined.
var oldPeople = App.store.filter(App.Person, function(data) {
if (data.age > 80) { return true; }
});You can create new model with createRecord():
var wycats = App.store.createRecord(App.Person, { name: "Brohuda" });New models are not saved back to the persistence layer until the
store's commit() method is called.
To update models, simply change a property on them. Updated models
will not be saved until the store's commit() method is called, which
allows you to batch changes.
To delete a model, call its deleteRecord() method:
var person = App.store.find(App.Person, 1);
person.deleteRecord();The model will not be deleted in the persistence layer until the store's
commit() method is called. However, deleted models will immediately be
removed from model arrays and associations.
You can be notified when certain events occur in a model's lifecycle by implementing methods on them:
didCreate- called when the model has been successfully created in the persistence layerdidUpdate- called when changes have been successfully saved to the persistence layerdidLoad- called when data has finished loading from the persistence layer
For example:
App.Person = DS.Model.extend({
didLoad: function() {
alert(this.get('firstName') + " finished loading.");
}
});You can also determine the state of a model by checking its state properties.
isLoaded- true when the model has finished loading, always true for models created locally.isDirty- true for created, updated, or deleted models that have not yet been savedisSaving- true if the model is in the process of being savedisDeleted- true if the model has been deleted, either locally or on the serverisError- true if the model is in an error state
You can "pre-load" data into the store, so it's ready for your users as soon as they need it.
To load an individual model, use the load() method:
App.store.load(Person, {
id: 1,
firstName: "Peter",
lastName: "Wagenet"
});You can load multiple records using loadMany():
App.store.loadMany(Person, [{
id: 2,
firstName: "Erik",
lastName: "Brynjolsofosonsosnson"
},
{
id: 3,
firstName: "Yehuda",
lastName: "Katz"
}]);An adapter is an object that receives requests from a store and translates them into the appropriate action to take against your persistence layer. The persistence layer is usually an HTTP API, but may be anything, such as the browser's local storage.
First, create a new instance of DS.Adapter:
App.adapter = DS.Adapter.create();To tell your store which adapter to use, set its adapter property:
App.store = DS.Store.create({
adapter: App.adapter
});Next, implement the methods your adapter needs, as described below.
Implement find() to fetch and populate a model with a specific ID. Once the
model has been found, call the store's load() method:
App.Person = DS.Model.extend();
App.Person.reopenClass({
url: '/people/%@'
});
DS.Adapter.create({
find: function(store, type, id) {
var url = type.url;
url = url.fmt(id);
jQuery.getJSON(url, function(data) {
// data is a Hash of key/value pairs. If your server returns a
// root, simply do something like:
// store.load(type, id, data.person)
store.load(type, id, data);
}
}
});The store will call your adapter's find() method when you call
store.find(type, id).
Note that for the rest of this documentation, we will use the url property in
our adapter. This is not the only way to write an adapter. For instance, you
could simply put a case statement in each method and do something different per
type. Or you could expose different information on your types that you use in
the adapter. We are simply using url to illustrate how an adapter is written.
Implement findMany() to fetch and populate all of the models for a given list
of IDs. The default findMany() will repeatedly invoke find(), but this may
be extremely inefficient. If you can, your server should support a way to find
many items by a list of IDs.
Once you are ready to populate the store with the data for the requested IDs, use the loadMany method:
App.Person = DS.Model.extend();
App.Person.reopenClass({
url: '/people?ids=%@'
});
DS.Adapter.create({
findMany: function(store, type, ids) {
var url = type.url;
url = url.fmt(ids.join(','));
jQuery.getJSON(url, function(data) {
// data is an Array of Hashes in the same order as the original
// Array of IDs. If your server returns a root, simply do something
// like:
// store.loadMany(type, ids, data.people)
store.loadMany(type, ids, data);
}
}
});It is extremely easy to implement an endpoint that will find many items in
Ruby on Rails. Simply define the index action in a standard resourceful
controller to understand an :ids parameter.
class PostsController < ApplicationController
def index
if ids = params[:ids]
@posts = Post.where(:id => ids)
else
@posts = Post.scoped
end
respond_with @posts
end
endCalled when the store's find() method is called with a query. Your adapter's
findQuery() method will be passed a model array that you should populate with
the results returned by the server.
App.Person = DS.Model.extend();
App.Person.reopenClass({
collectionUrl: '/people'
});
DS.Adapter.create({
findQuery: function(store, type, query, modelArray) {
var url = type.collectionUrl;
jQuery.getJSON(url, query, function(data) {
// data is expected to be an Array of Hashes, in an order
// determined by the server. This order may be specified in
// the query, and will be reflected in the view.
//
// If your server returns a root, simply:
// modelArray.load(data.people)
modelArray.load(data);
});
})
});You can do whatever you want with the query in your adapter, but most commonly,
you will just send it along to the server as the data portion of an Ajax
request.
Your server will then be responsible for returning an Array of JSON data. When
you load the data into the modelArray, the elements of that Array will be
loaded into the store at the same time.
Invoked when findAll() is called on the store. If you do nothing, only
models that have already been loaded will be included in the results. Otherwise,
this is your opportunity to load any unloaded models of this type. The
implementation is similar to findMany(); see above for an example.
When commit() is called on the store and there are models that need to be
created on the server, the store will call the adapter's create() method.
Once the store calls the adapter's create method, it will be put into a
saving state, and further attempts to edit the model will result in an
error.
Implementing a create method is straight forward:
App.Person = DS.Model.extend();
App.Person.reopenClass({
url: '/people/%@'
});
DS.Adapter.create({
createRecord: function(store, type, model) {
var url = type.url;
jQuery.ajax({
url: url.fmt(model.get('id')),
data: model.get('data'),
dataType: 'json',
type: 'POST',
success: function(data) {
// data is a hash of key/value pairs representing the model.
// In general, this hash will contain a new id, which the
// store will now use to index the model. Future calls to
// store.find(type, id) will find this model.
store.didCreateRecord(model, data);
}
});
})
});For better efficiency, you can implement a createRecords method on your adapter,
which should send all of the new models to the server at once.
App.Person = DS.Model.extend();
App.Person.reopenClass({
collectionUrl: '/people'
});
DS.Adapter.create({
createRecords: function(store, type, array) {
jQuery.ajax({
url: type.collectionUrl,
data: array.mapProperty('data'),
dataType: 'json',
type: 'POST',
success: function(data) {
// data is an array of hashes in the same order as
// the original models that were sent.
store.didCreateRecords(type, array, data);
}
});
})
});Update is implemented the same as createRecord(), except after the model has been
saved, you should call the store's didUpdateRecord() method.
App.Person = DS.Model.extend();
App.Person.reopenClass({
url: '/people/%@'
});
DS.Adapter.create({
updateRecord: function(store, type, model) {
var url = type.url;
jQuery.ajax({
url: url.fmt(model.get('id')),
dataType: 'json',
type: 'PUT',
success: function(data) {
// data is a hash of key/value pairs representing the model
// in its current state on the server.
store.didUpdateRecord(model, data);
}
});
})
});Again, updateRecords() is very similar to createRecords().
App.Person = DS.Model.extend();
App.Person.reopenClass({
collectionUrl: '/people'
});
DS.Adapter.create({
updateRecords: function(store, type, array) {
jQuery.ajax({
url: type.collectionUrl,
data: array.mapProperty('data'),
dataType: 'json',
type: 'PUT',
success: function(data) {
// data is an array of hashes in the same order as
// the original models that were sent.
store.didUpdateRecords(array);
}
});
})
});To delete a model, implement the deleteRecord() method, and call the store's
didDeleteRecord() method when completed.
App.Person = DS.Model.extend();
App.Person.reopenClass({
url: '/people/%@'
});
DS.Adapter.create({
deleteRecord: function(store, type, model) {
var url = type.url;
jQuery.ajax({
url: url.fmt(model.get('id')),
dataType: 'json',
type: 'DELETE',
success: function() {
store.didDeleteRecord(model);
}
});
})
});Note: The method is called deleteRecord instead of delete because
Internet Explorer blows up if you have a method called delete. Sorry.
Are you getting it?
App.Person = DS.Model.extend();
App.Person.reopenClass({
collectionUrl: '/people'
});
DS.Adapter.create({
deleteRecords: function(store, type, array) {
jQuery.ajax({
url: type.collectionUrl,
data: array.mapProperty('data'),
dataType: 'json',
type: 'DELETE',
success: function(data) {
store.didDeleteRecords(array);
}
});
})
});For maximum turbo-efficiency, you can package all pending changes (creates,
updates, and deletes) into one megapackage of data awesomeness. To do so,
implement commit(), which will be called with everything that needs
to be sent to the persistence layer.
Here's what the default adapter's commit() method looks like:
commit: function(store, commitDetails) {
commitDetails.updated.eachType(function(type, array) {
this.updateRecords(store, type, array.slice());
}, this);
commitDetails.created.eachType(function(type, array) {
this.createRecords(store, type, array.slice());
}, this);
commitDetails.deleted.eachType(function(type, array) {
this.deleteRecords(store, type, array.slice());
}, this);
}Ember Data will always return models or model arrays immediately, even though the underlying JSON objects have not yet been returned from the server.
In general, this means that you can insert them into the DOM using Ember's Handlebars template engine, and they will automatically update when your adapter has populated them.
For example, if you request a ModelArray:
App.people = App.store.find(App.Person, { firstName: "Tom" });You will get back a ModelArray that is currently empty. Ember Data will then
ask your adapter to populate the model Array, which will usually make an Ajax
request. Howver, you can immediately refer to it in your templates:
<ul>
{{#each App.people}}
<li>{{fullName}}</li>
{{/each}}
</ul>Once the Adapter calls modelArray.load(array), the DOM will automatically
populate with the new information.
The same is true of models themselves. For instance, you can make a request for a single model:
App.person = App.store.find(Person, 1);You will immediately receive back a new unpopulated Person object. You can
refer to it in the view right away:
{{App.person.fullName}}Initially, this will be empty, but when your adapter calls store.load(hash),
it will update with the information provided.
If you'd like to show different content while the model is in the process of
being loaded, you can use the model's isLoaded property:
{{#with App.person}}
{{#if isLoaded}}
Hello, {{fullName}}!
{{else}}
Loading...
{{/if}}
{{/with}}Note that the same principle applies to model arrays, as well. Like models,
model arrays have an isLoaded property that you can use to display different
content.
You can also indicate to users when a model is saving, for example:
{{#with App.person}}
<h1 {{bindAttr class="isSaving"}}>{{fullName}}</h1>
{{/with}}In this case, you could make the is-saving class in your CSS grey out the
content or add a spinner alongside it, for instance.
To run unit tests, run rackup from the root directory and visit
http://localhost:9292/tests/index.html?package=ember-data.
Profit.