DS.Model Class
The model class that all Ember Data records descend from. This is the public API of Ember Data models. If you are using Ember Data in your application, this is the class you should use.
Item Index
Methods
- _debugInfo
- _notifyProperties
- belongsTo
- changedAttributes
- create static
- deleteRecord
- destroyRecord
- eachAttribute static
- eachRelatedType static
- eachRelationship static
- eachRelationship
- eachTransformedAttribute static
- hasMany
- inverseFor static
- reload
- rollbackAttributes
- save
- send
- serialize
- toJSON
- toString static
- transitionTo
- trigger
- typeForRelationship static
- unloadRecord
Properties
- _internalModel
- adapterError
- attributes static
- currentState
- data deprecated
- dirtyType
- errors
- fields static
- hasDirtyAttributes
- id
- isDeleted
- isEmpty
- isError
- isLoaded
- isLoading
- isNew
- isReloading
- isSaving
- isValid
- modelName static
- recordData
- relatedTypes static
- relationshipNames static
- relationships static
- relationshipsByName static
- store
- transformedAttributes static
Methods
_debugInfo
()
private
Provides info about the model for debugging purposes by grouping the properties into more semantic groups.
Meant to be used by debugging tools such as the Chrome Ember Extension.
- Groups all attributes in "Attributes" group.
- Groups all belongsTo relationships in "Belongs To" group.
- Groups all hasMany relationships in "Has Many" group.
- Groups all flags in "Flags" group.
- Flags relationship CPs as expensive properties.
_notifyProperties
()
private
belongsTo
-
name
Get the reference for the specified belongsTo relationship.
Example
export default DS.Model.extend({
user: DS.belongsTo({ async: true })
});
let blog = store.push({
data: {
type: 'blog',
id: 1,
relationships: {
user: {
data: { type: 'user', id: 1 }
}
}
}
});
let userRef = blog.belongsTo('user');
// check if the user relationship is loaded
let isLoaded = userRef.value() !== null;
// get the record of the reference (null if not yet available)
let user = userRef.value();
// get the identifier of the reference
if (userRef.remoteType() === "id") {
let id = userRef.id();
} else if (userRef.remoteType() === "link") {
let link = userRef.link();
}
// load user (via store.findRecord or store.findBelongsTo)
userRef.load().then(...)
// or trigger a reload
userRef.reload().then(...)
// provide data for reference
userRef.push({
type: 'user',
id: 1,
attributes: {
username: "@user"
}
}).then(function(user) {
userRef.value() === user;
});
Parameters:
-
name
Stringof the relationship
Returns:
reference for this relationship
changedAttributes
()
Object
Returns an object, whose keys are changed properties, and value is an [oldProp, newProp] array.
The array represents the diff of the canonical state with the local state of the model. Note: if the model is created locally, the canonical state is empty since the adapter hasn't acknowledged the attributes yet:
Example
import DS from 'ember-data';
export default DS.Model.extend({
name: DS.attr('string'),
isAdmin: DS.attr('boolean', {
defaultValue: false
})
});
let mascot = store.createRecord('mascot');
mascot.changedAttributes(); // {}
mascot.set('name', 'Tomster');
mascot.changedAttributes(); // { name: [undefined, 'Tomster'] }
mascot.set('isAdmin', true);
mascot.changedAttributes(); // { isAdmin: [undefined, true], name: [undefined, 'Tomster'] }
mascot.save().then(function() {
mascot.changedAttributes(); // {}
mascot.set('isAdmin', false);
mascot.changedAttributes(); // { isAdmin: [true, false] }
});
Returns:
an object, whose keys are changed properties, and value is an [oldProp, newProp] array.
create
()
private
static
Create should only ever be called by the store. To create an instance of a
DS.Model
in a dirty state use store.createRecord
.
To create instances of DS.Model
in a clean state, use store.push
deleteRecord
()
Marks the record as deleted but does not save it. You must call
save
afterwards if you want to persist it. You might use this
method if you want to allow the user to still rollbackAttributes()
after a delete was made.
Example
import Route from '@ember/routing/route';
export default Route.extend({
actions: {
softDelete() {
this.get('controller.model').deleteRecord();
},
confirm() {
this.get('controller.model').save();
},
undo() {
this.get('controller.model').rollbackAttributes();
}
}
});
destroyRecord
-
options
Same as deleteRecord
, but saves the record immediately.
Example
import Route from '@ember/routing/route';
export default Route.extend({
actions: {
delete() {
this.get('controller.model').destroyRecord().then(function() {
controller.transitionToRoute('model.index');
});
}
}
});
If you pass an object on the adapterOptions
property of the options
argument it will be passed to your adapter via the snapshot
record.destroyRecord({ adapterOptions: { subscribe: false } });
import MyCustomAdapter from './custom-adapter';
export default MyCustomAdapter.extend({
deleteRecord(store, type, snapshot) {
if (snapshot.adapterOptions.subscribe) {
// ...
}
// ...
}
});
Parameters:
-
options
Object
Returns:
a promise that will be resolved when the adapter returns successfully or rejected if the adapter returns with an error.
eachAttribute
-
callback
-
[binding]
Iterates through the attributes of the model, calling the passed function on each attribute.
The callback method you provide should have the following signature (all parameters are optional):
function(name, meta);
name
the name of the current property in the iterationmeta
the meta object for the attribute property in the iteration
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context.
Example
import DS from 'ember-data';
let Person = DS.Model.extend({
firstName: DS.attr('string'),
lastName: DS.attr('string'),
birthday: DS.attr('date')
});
Person.eachAttribute(function(name, meta) {
console.log(name, meta);
});
// prints:
// firstName {type: "string", isAttribute: true, options: Object, parentType: function, name: "firstName"}
// lastName {type: "string", isAttribute: true, options: Object, parentType: function, name: "lastName"}
// birthday {type: "date", isAttribute: true, options: Object, parentType: function, name: "birthday"}
Parameters:
-
callback
FunctionThe callback to execute
-
[binding]
Object optionalthe value to which the callback's
this
should be bound
eachRelatedType
-
callback
-
binding
Given a callback, iterates over each of the types related to a model, invoking the callback with the related type's class. Each type will be returned just once, regardless of how many different relationships it has with a model.
Parameters:
-
callback
Functionthe callback to invoke
-
binding
Anythe value to which the callback's
this
should be bound
eachRelationship
-
callback
-
binding
Given a callback, iterates over each of the relationships in the model, invoking the callback with the name of each relationship and its relationship descriptor.
Parameters:
-
callback
Functionthe callback to invoke
-
binding
Anythe value to which the callback's
this
should be bound
eachRelationship
-
callback
-
binding
Given a callback, iterates over each of the relationships in the model, invoking the callback with the name of each relationship and its relationship descriptor.
The callback method you provide should have the following signature (all parameters are optional):
function(name, descriptor);
name
the name of the current property in the iterationdescriptor
the meta object that describes this relationship
The relationship descriptor argument is an object with the following properties.
- key String the name of this relationship on the Model
- kind String "hasMany" or "belongsTo"
- options Object the original options hash passed when the relationship was declared
- parentType DS.Model the type of the Model that owns this relationship
- type String the type name of the related Model
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context.
Example
import DS from 'ember-data';
export default DS.JSONSerializer.extend({
serialize: function(record, options) {
let json = {};
record.eachRelationship(function(name, descriptor) {
if (descriptor.kind === 'hasMany') {
let serializedHasManyName = name.toUpperCase() + '_IDS';
json[serializedHasManyName] = record.get(name).mapBy('id');
}
});
return json;
}
});
Parameters:
-
callback
Functionthe callback to invoke
-
binding
Anythe value to which the callback's
this
should be bound
eachTransformedAttribute
-
callback
-
[binding]
Iterates through the transformedAttributes of the model, calling the passed function on each attribute. Note the callback will not be called for any attributes that do not have an transformation type.
The callback method you provide should have the following signature (all parameters are optional):
function(name, type);
name
the name of the current property in the iterationtype
a string containing the name of the type of transformed applied to the attribute
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context.
Example
import DS from 'ember-data';
let Person = DS.Model.extend({
firstName: DS.attr(),
lastName: DS.attr('string'),
birthday: DS.attr('date')
});
Person.eachTransformedAttribute(function(name, type) {
console.log(name, type);
});
// prints:
// lastName string
// birthday date
Parameters:
-
callback
FunctionThe callback to execute
-
[binding]
Object optionalthe value to which the callback's
this
should be bound
hasMany
-
name
Get the reference for the specified hasMany relationship.
Example
// models/blog.js
export default DS.Model.extend({
comments: DS.hasMany({ async: true })
});
let blog = store.push({
data: {
type: 'blog',
id: 1,
relationships: {
comments: {
data: [
{ type: 'comment', id: 1 },
{ type: 'comment', id: 2 }
]
}
}
}
});
let commentsRef = blog.hasMany('comments');
// check if the comments are loaded already
let isLoaded = commentsRef.value() !== null;
// get the records of the reference (null if not yet available)
let comments = commentsRef.value();
// get the identifier of the reference
if (commentsRef.remoteType() === "ids") {
let ids = commentsRef.ids();
} else if (commentsRef.remoteType() === "link") {
let link = commentsRef.link();
}
// load comments (via store.findMany or store.findHasMany)
commentsRef.load().then(...)
// or trigger a reload
commentsRef.reload().then(...)
// provide data for reference
commentsRef.push([{ type: 'comment', id: 1 }, { type: 'comment', id: 2 }]).then(function(comments) {
commentsRef.value() === comments;
});
Parameters:
-
name
Stringof the relationship
Returns:
reference for this relationship
inverseFor
-
name
-
store
Find the relationship which is the inverse of the one asked for.
For example, if you define models like this:
import DS from 'ember-data';
export default DS.Model.extend({
comments: DS.hasMany('message')
});
store.modelFor('post').inverseFor('comments', store) // { type: App.Message, name: 'owner', kind: 'belongsTo' }
store.modelFor('message').inverseFor('owner', store) // { type: App.Post, name: 'comments', kind: 'hasMany' }
Parameters:
-
name
Stringthe name of the relationship
-
store
DS.Store
Returns:
the inverse relationship, or null
reload
-
options
Reload the record from the adapter.
This will only work if the record has already finished loading.
Example
import Route from '@ember/routing/route';
export default Route.extend({
actions: {
reload() {
this.controller.get('model').reload().then(function(model) {
// do something with the reloaded model
});
}
}
});
Parameters:
-
options
Objectoptional, may include
adapterOptions
hash which will be passed to adapter request
Returns:
a promise that will be resolved with the record when the adapter returns successfully or rejected if the adapter returns with an error.
rollbackAttributes
()
If the model hasDirtyAttributes
this function will discard any unsaved
changes. If the model isNew
it will be removed from the store.
Example
record.get('name'); // 'Untitled Document'
record.set('name', 'Doc 1');
record.get('name'); // 'Doc 1'
record.rollbackAttributes();
record.get('name'); // 'Untitled Document'
save
-
options
Save the record and persist any changes to the record to an external source via the adapter.
Example
record.set('name', 'Tomster');
record.save().then(function() {
// Success callback
}, function() {
// Error callback
});
If you pass an object using the adapterOptions
property of the options
argument it will be passed to your adapter via the snapshot.
record.save({ adapterOptions: { subscribe: false } });
import MyCustomAdapter from './custom-adapter';
export default MyCustomAdapter.extend({
updateRecord(store, type, snapshot) {
if (snapshot.adapterOptions.subscribe) {
// ...
}
// ...
}
});
Parameters:
-
options
Object
Returns:
a promise that will be resolved when the adapter returns successfully or rejected if the adapter returns with an error.
send
-
name
-
context
Parameters:
-
name
String -
context
Object
serialize
-
options
Create a JSON representation of the record, using the serialization strategy of the store's adapter.
serialize
takes an optional hash as a parameter, currently
supported options are:
includeId
:true
if the record's ID should be included in the JSON representation.
Parameters:
-
options
Object
Returns:
an object whose values are primitive JSON values only
toJSON
-
options
Use DS.JSONSerializer to get the JSON representation of a record.
toJSON
takes an optional hash as a parameter, currently
supported options are:
includeId
:true
if the record's ID should be included in the JSON representation.
Parameters:
-
options
Object
Returns:
A JSON representation of the object.
toString
()
static
Returns the name of the model class.
transitionTo
-
name
Parameters:
-
name
String
trigger
-
name
Override the default event firing from Ember.Evented to also call methods with the given name.
Parameters:
-
name
String
typeForRelationship
-
name
-
store
For a given relationship name, returns the model type of the relationship.
For example, if you define a model like this:
import DS from 'ember-data';
export default DS.Model.extend({
comments: DS.hasMany('comment')
});
Calling store.modelFor('post').typeForRelationship('comments', store)
will return Comment
.
Parameters:
-
name
Stringthe name of the relationship
-
store
Storean instance of DS.Store
Returns:
the type of the relationship, or undefined
unloadRecord
()
Unloads the record from the store. This will cause the record to be destroyed and freed up for garbage collection.
Properties
_internalModel
Object
private
adapterError
DS.AdapterError
This property holds the DS.AdapterError
object with which
last adapter operation was rejected.
attributes
Map
static
A map whose keys are the attributes of the model (properties described by DS.attr) and whose values are the meta object for the property.
Example
import DS from 'ember-data';
export default DS.Model.extend({
firstName: DS.attr('string'),
lastName: DS.attr('string'),
birthday: DS.attr('date')
});
import Ember from 'ember';
import Person from 'app/models/person';
let attributes = Ember.get(Person, 'attributes')
attributes.forEach(function(meta, name) {
console.log(name, meta);
});
// prints:
// firstName {type: "string", isAttribute: true, options: Object, parentType: function, name: "firstName"}
// lastName {type: "string", isAttribute: true, options: Object, parentType: function, name: "lastName"}
// birthday {type: "date", isAttribute: true, options: Object, parentType: function, name: "birthday"}
currentState
Object
private
data
Object
deprecated
private
dirtyType
String
If the record is in the dirty state this property will report what kind of change has caused it to move into the dirty state. Possible values are:
created
The record has been created by the client and not yet saved to the adapter.updated
The record has been updated by the client and not yet saved to the adapter.deleted
The record has been deleted by the client and not yet saved to the adapter.
Example
let record = store.createRecord('model');
record.get('dirtyType'); // 'created'
errors
DS.Errors
When the record is in the invalid
state this object will contain
any errors returned by the adapter. When present the errors hash
contains keys corresponding to the invalid property names
and values which are arrays of Javascript objects with two keys:
message
A string containing the error message from the backendattribute
The name of the property associated with this error message
record.get('errors.length'); // 0
record.set('foo', 'invalid value');
record.save().catch(function() {
record.get('errors').get('foo');
// [{message: 'foo should be a number.', attribute: 'foo'}]
});
The errors
property us useful for displaying error messages to
the user.
<label>Username: {{input value=username}} </label>
{{#each model.errors.username as |error|}}
<div class="error">
{{error.message}}
</div>
{{/each}}
<label>Email: {{input value=email}} </label>
{{#each model.errors.email as |error|}}
<div class="error">
{{error.message}}
</div>
{{/each}}
You can also access the special messages
property on the error
object to get an array of all the error strings.
{{#each model.errors.messages as |message|}}
<div class="error">
{{message}}
</div>
{{/each}}
fields
Map
static
A map whose keys are the fields of the model and whose values are strings describing the kind of the field. A model's fields are the union of all of its attributes and relationships.
For example:
import DS from 'ember-data';
export default DS.Model.extend({
users: DS.hasMany('user'),
owner: DS.belongsTo('user'),
posts: DS.hasMany('post'),
title: DS.attr('string')
});
import Ember from 'ember';
import Blog from 'app/models/blog';
let fields = Ember.get(Blog, 'fields');
fields.forEach(function(kind, field) {
console.log(field, kind);
});
// prints:
// users, hasMany
// owner, belongsTo
// posts, hasMany
// title, attribute
hasDirtyAttributes
Boolean
If this property is true
the record is in the dirty
state. The
record has local changes that have not yet been saved by the
adapter. This includes records that have been created (but not yet
saved) or deleted.
Example
let record = store.createRecord('model');
record.get('hasDirtyAttributes'); // true
store.findRecord('model', 1).then(function(model) {
model.get('hasDirtyAttributes'); // false
model.set('foo', 'some value');
model.get('hasDirtyAttributes'); // true
});
id
String
All ember models have an id property. This is an identifier managed by an external source. These are always coerced to be strings before being used internally. Note when declaring the attributes for a model it is an error to declare an id attribute.
let record = store.createRecord('model');
record.get('id'); // null
store.findRecord('model', 1).then(function(model) {
model.get('id'); // '1'
});
isDeleted
Boolean
If this property is true
the record is in the deleted
state
and has been marked for deletion. When isDeleted
is true and
hasDirtyAttributes
is true, the record is deleted locally but the deletion
was not yet persisted. When isSaving
is true, the change is
in-flight. When both hasDirtyAttributes
and isSaving
are false, the
change has persisted.
Example
let record = store.createRecord('model');
record.get('isDeleted'); // false
record.deleteRecord();
// Locally deleted
record.get('isDeleted'); // true
record.get('hasDirtyAttributes'); // true
record.get('isSaving'); // false
// Persisting the deletion
let promise = record.save();
record.get('isDeleted'); // true
record.get('isSaving'); // true
// Deletion Persisted
promise.then(function() {
record.get('isDeleted'); // true
record.get('isSaving'); // false
record.get('hasDirtyAttributes'); // false
});
isEmpty
Boolean
If this property is true
the record is in the empty
state. Empty is the first state all records enter after they have
been created. Most records created by the store will quickly
transition to the loading
state if data needs to be fetched from
the server or the created
state if the record is created on the
client. A record can also enter the empty state if the adapter is
unable to locate the record.
isError
Boolean
If true
the adapter reported that it was unable to save local
changes to the backend for any reason other than a server-side
validation error.
Example
record.get('isError'); // false
record.set('foo', 'valid value');
record.save().then(null, function() {
record.get('isError'); // true
});
isLoaded
Boolean
If this property is true
the record is in the loaded
state. A
record enters this state when its data is populated. Most of a
record's lifecycle is spent inside substates of the loaded
state.
Example
let record = store.createRecord('model');
record.get('isLoaded'); // true
store.findRecord('model', 1).then(function(model) {
model.get('isLoaded'); // true
});
isLoading
Boolean
If this property is true
the record is in the loading
state. A
record enters this state when the store asks the adapter for its
data. It remains in this state until the adapter provides the
requested data.
isNew
Boolean
If this property is true
the record is in the new
state. A
record will be in the new
state when it has been created on the
client and the adapter has not yet report that it was successfully
saved.
Example
let record = store.createRecord('model');
record.get('isNew'); // true
record.save().then(function(model) {
model.get('isNew'); // false
});
isReloading
Boolean
If true
the store is attempting to reload the record from the adapter.
Example
record.get('isReloading'); // false
record.reload();
record.get('isReloading'); // true
isSaving
Boolean
If this property is true
the record is in the saving
state. A
record enters the saving state when save
is called, but the
adapter has not yet acknowledged that the changes have been
persisted to the backend.
Example
let record = store.createRecord('model');
record.get('isSaving'); // false
let promise = record.save();
record.get('isSaving'); // true
promise.then(function() {
record.get('isSaving'); // false
});
isValid
Boolean
If this property is true
the record is in the valid
state.
A record will be in the valid
state when the adapter did not report any
server-side validation failures.
modelName
String
static
Represents the model's class name as a string. This can be used to look up the model's class name through
DS.Store
's modelFor method.
modelName
is generated for you by Ember Data. It will be a lowercased, dasherized string.
For example:
store.modelFor('post').modelName; // 'post'
store.modelFor('blog-post').modelName; // 'blog-post'
The most common place you'll want to access modelName
is in your serializer's payloadKeyFromModelName
method. For example, to change payload
keys to underscore (instead of dasherized), you might use the following code:
import { underscore } from '@ember/string';
export default const PostSerializer = DS.RESTSerializer.extend({
payloadKeyFromModelName(modelName) {
return underscore(modelName);
}
});
recordData
Undefined (reserved)
private
relationshipNames
Object
static
A hash containing lists of the model's relationships, grouped by the relationship kind. For example, given a model with this definition:
import DS from 'ember-data';
export default DS.Model.extend({
users: DS.hasMany('user'),
owner: DS.belongsTo('user'),
posts: DS.hasMany('post')
});
This property would contain the following:
import Ember from 'ember';
import Blog from 'app/models/blog';
let relationshipNames = Ember.get(Blog, 'relationshipNames');
relationshipNames.hasMany;
//=> ['users', 'posts']
relationshipNames.belongsTo;
//=> ['owner']
relationships
Map
static
The model's relationships as a map, keyed on the type of the relationship. The value of each entry is an array containing a descriptor for each relationship with that type, describing the name of the relationship as well as the type.
For example, given the following model definition:
import DS from 'ember-data';
export default DS.Model.extend({
users: DS.hasMany('user'),
owner: DS.belongsTo('user'),
posts: DS.hasMany('post')
});
This computed property would return a map describing these relationships, like this:
import Ember from 'ember';
import Blog from 'app/models/blog';
import User from 'app/models/user';
import Post from 'app/models/post';
let relationships = Ember.get(Blog, 'relationships');
relationships.get(User);
//=> [ { name: 'users', kind: 'hasMany' },
// { name: 'owner', kind: 'belongsTo' } ]
relationships.get(Post);
//=> [ { name: 'posts', kind: 'hasMany' } ]
relationshipsByName
Map
static
A map whose keys are the relationships of a model and whose values are relationship descriptors.
For example, given a model with this definition:
import DS from 'ember-data';
export default DS.Model.extend({
users: DS.hasMany('user'),
owner: DS.belongsTo('user'),
posts: DS.hasMany('post')
});
This property would contain the following:
import Ember from 'ember';
import Blog from 'app/models/blog';
let relationshipsByName = Ember.get(Blog, 'relationshipsByName');
relationshipsByName.get('users');
//=> { key: 'users', kind: 'hasMany', type: 'user', options: Object, isRelationship: true }
relationshipsByName.get('owner');
//=> { key: 'owner', kind: 'belongsTo', type: 'user', options: Object, isRelationship: true }
store
Unknown
transformedAttributes
Map
static
A map whose keys are the attributes of the model (properties described by DS.attr) and whose values are type of transformation applied to each attribute. This map does not include any attributes that do not have an transformation type.
Example
import DS from 'ember-data';
export default DS.Model.extend({
firstName: DS.attr(),
lastName: DS.attr('string'),
birthday: DS.attr('date')
});
import Ember from 'ember';
import Person from 'app/models/person';
let transformedAttributes = Ember.get(Person, 'transformedAttributes')
transformedAttributes.forEach(function(field, type) {
console.log(field, type);
});
// prints:
// lastName string
// birthday date
Events
becameError
Fired when the record enters the error state.
becameInvalid
Fired when the record becomes invalid.
didCreate
Fired when a new record is commited to the server.
didDelete
Fired when the record is deleted.
didLoad
Fired when the record is loaded from the server.
didUpdate
Fired when the record is updated.
ready
Fired when the record is ready to be interacted with, that is either loaded from the server or created locally.
rolledBack
Fired when the record is rolled back.