Model Class
Base class from which Models can be defined.
import Model, { attr } from '@ember-data/model';
export default class User extends Model {
@attr name;
}
Models are used both to define the static schema for a particular resource type as well as the class to instantiate to present that data from cache.
Item Index
Methods
- _createSnapshot
- _debugInfo
- belongsTo
- changedAttributes
- create static
- deleteRecord
- destroyRecord
- eachAttribute static
- eachRelatedType static
- eachRelationship
- eachRelationship static
- eachTransformedAttribute static
- hasMany
- inverseFor static
- reload
- rollbackAttributes
- save
- serialize
- toString static
- typeForRelationship static
- unloadRecord
Properties
- adapterError
- attributes static
- currentState
- dirtyType
- errors
- fields static
- hasDirtyAttributes
- id
- isDeleted
- isEmpty
- isError
- isLoaded
- isLoading
- isNew
- isReloading
- isSaving
- isValid
- modelName static
- relatedTypes static
- relationshipNames static
- relationships static
- relationshipsByName static
- store
- transformedAttributes static
Methods
_createSnapshot
()
private
_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.
belongsTo
-
name
Get the reference for the specified belongsTo relationship.
For instance, given the following model
import Model, { belongsTo } from '@ember-data/model';
export default class BlogPost extends Model {
@belongsTo('user', { async: true, inverse: null }) author;
}
Then the reference for the author relationship would be retrieved from a record instance like so:
blogPost.belongsTo('author');
A BelongsToReference
is a low-level API that allows access
and manipulation of a belongsTo relationship.
It is especially useful when you're dealing with async
relationships
as it allows synchronous access to the relationship data if loaded, as
well as APIs for loading, reloading the data or accessing available
information without triggering a load.
It may also be useful when using sync
relationships that need to be
loaded/reloaded with more precise timing than marking the
relationship as async
and relying on autofetch would have allowed.
However,keep in mind that marking a relationship as async: false
will introduce
bugs into your application if the data is not always guaranteed to be available
by the time the relationship is accessed. Ergo, it is recommended when using this
approach to utilize links
for unloaded relationship state instead of identifiers.
Reference APIs are entangled with the relationship's underlying state, thus any getters or cached properties that utilize these will properly invalidate if the relationship state changes.
References are "stable", meaning that multiple calls to retrieve the reference for a given relationship will always return the same HasManyReference.
Parameters:
-
name
Stringof the relationship
Returns:
reference for this relationship
changedAttributes
()
Object
public
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 Model, { attr } from '@ember-data/model';
export default class MascotModel extends Model {
@attr('string') name;
@attr('boolean', {
defaultValue: false
})
isAdmin;
}
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
Model
in a dirty state use store.createRecord
.
To create instances of Model
in a clean state, use store.push
deleteRecord
()
public
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 Component from '@glimmer/component';
export default class extends Component {
softDelete = () => {
this.args.model.deleteRecord();
}
confirm = () => {
this.args.model.save();
}
undo = () => {
this.args.model.rollbackAttributes();
}
}
destroyRecord
-
options
Same as deleteRecord
, but saves the record immediately.
Example
import Component from '@glimmer/component';
export default class extends Component {
delete = () => {
this.args.model.destroyRecord().then(function() {
this.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 class PostAdapter extends MyCustomAdapter {
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 Model, { attr } from '@ember-data/model';
class PersonModel extends Model {
@attr('string') firstName;
@attr('string') lastName;
@attr('date') birthday;
}
PersonModel.eachAttribute(function(name, meta) {
// do thing
});
// prints:
// firstName {type: "string", kind: 'attribute', options: Object, parentType: function, name: "firstName"}
// lastName {type: "string", kind: 'attribute', options: Object, parentType: function, name: "lastName"}
// birthday {type: "date", kind: 'attribute', 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.
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.
- name 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 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 JSONSerializer from '@ember-data/serializer/json';
export default class ApplicationSerializer extends JSONSerializer {
serialize(record, options) {
let json = {};
record.eachRelationship(function(name, descriptor) {
if (descriptor.kind === 'hasMany') {
let serializedHasManyName = name.toUpperCase() + '_IDS';
json[serializedHasManyName] = record.get(name).map(r => r.id);
}
});
return json;
}
}
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
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 Model, { attr } from '@ember-data/model';
let Person = Model.extend({
firstName: attr(),
lastName: attr('string'),
birthday: attr('date')
});
Person.eachTransformedAttribute(function(name, type) {
// do thing
});
// 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.
For instance, given the following model
import Model, { hasMany } from '@ember-data/model';
export default class BlogPost extends Model {
@hasMany('comment', { async: true, inverse: null }) comments;
}
Then the reference for the comments relationship would be retrieved from a record instance like so:
blogPost.hasMany('comments');
A HasManyReference
is a low-level API that allows access
and manipulation of a hasMany relationship.
It is especially useful when you are dealing with async
relationships
as it allows synchronous access to the relationship data if loaded, as
well as APIs for loading, reloading the data or accessing available
information without triggering a load.
It may also be useful when using sync
relationships with @ember-data/model
that need to be loaded/reloaded with more precise timing than marking the
relationship as async
and relying on autofetch would have allowed.
However,keep in mind that marking a relationship as async: false
will introduce
bugs into your application if the data is not always guaranteed to be available
by the time the relationship is accessed. Ergo, it is recommended when using this
approach to utilize links
for unloaded relationship state instead of identifiers.
Reference APIs are entangled with the relationship's underlying state, thus any getters or cached properties that utilize these will properly invalidate if the relationship state changes.
References are "stable", meaning that multiple calls to retrieve the reference for a given relationship will always return the same HasManyReference.
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 Model, { hasMany } from '@ember-data/model';
export default class PostModel extends Model {
@hasMany('message') comments;
}
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
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 Component from '@glimmer/component';
export default class extends Component {
async reload = () => {
await this.args.model.reload();
// 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
()
public
If the model hasDirtyAttributes
this function will discard any unsaved
changes. If the model isNew
it will be removed from the store.
Example
record.name; // 'Untitled Document'
record.set('name', 'Doc 1');
record.name; // 'Doc 1'
record.rollbackAttributes();
record.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 class PostAdapter extends MyCustomAdapter {
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.
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
toString
()
public
static
Returns the name of the model class.
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 Model, { hasMany } from '@ember-data/model';
export default class PostModel extends Model {
@hasMany('comment') comments;
}
Calling store.modelFor('post').typeForRelationship('comments', store)
will return Comment
.
Parameters:
-
name
Stringthe name of the relationship
-
store
Storean instance of Store
Returns:
the type of the relationship, or undefined
unloadRecord
()
public
Unloads the record from the store. This will not send a delete request to your server, it just unloads the record from memory.
Properties
adapterError
AdapterError
public
This property holds the AdapterError
object with which
last adapter operation was rejected.
attributes
Map
public
static
A map whose keys are the attributes of the model (properties described by attr) and whose values are the meta object for the property.
Example
import Model, { attr } from '@ember-data/model';
export default class PersonModel extends Model {
@attr('string') firstName;
@attr('string') lastName;
@attr('date') birthday;
}
import Person from 'app/models/person'
let attributes = Person.attributes
attributes.forEach(function(meta, name) {
// do thing
});
// prints:
// firstName {type: "string", kind: 'attribute', options: Object, parentType: function, name: "firstName"}
// lastName {type: "string", kind: 'attribute', options: Object, parentType: function, name: "lastName"}
// birthday {type: "date", kind: 'attribute', options: Object, parentType: function, name: "birthday"}
currentState
Object
private
dirtyType
String
public
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.dirtyType; // 'created'
errors
Errors
public
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.errors.length; // 0
record.set('foo', 'invalid value');
record.save().catch(function() {
record.errors.foo;
// [{message: 'foo should be a number.', attribute: 'foo'}]
});
The errors
property is useful for displaying error messages to
the user.
<label>Username: <Input @value={{@model.username}} /> </label>
{{#each @model.errors.username as |error|}}
<div class="error">
{{error.message}}
</div>
{{/each}}
<label>Email: <Input @value={{@model.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
public
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 Model, { attr, belongsTo, hasMany } from '@ember-data/model';
export default class BlogModel extends Model {
@hasMany('user') users;
@belongsTo('user') owner;
@hasMany('post') posts;
@attr('string') title;
}
import Blog from 'app/models/blog'
let fields = Blog.fields;
fields.forEach(function(kind, field) {
// do thing
});
// prints:
// users, hasMany
// owner, belongsTo
// posts, hasMany
// title, attribute
hasDirtyAttributes
Boolean
public
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.hasDirtyAttributes; // true
store.findRecord('model', 1).then(function(model) {
model.hasDirtyAttributes; // false
model.set('foo', 'some value');
model.hasDirtyAttributes; // true
});
id
String
public
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.id; // null
store.findRecord('model', 1).then(function(model) {
model.id; // '1'
});
isDeleted
Boolean
public
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.isDeleted; // false
record.deleteRecord();
// Locally deleted
record.isDeleted; // true
record.hasDirtyAttributes; // true
record.isSaving; // false
// Persisting the deletion
let promise = record.save();
record.isDeleted; // true
record.isSaving; // true
// Deletion Persisted
promise.then(function() {
record.isDeleted; // true
record.isSaving; // false
record.hasDirtyAttributes; // false
});
isEmpty
Boolean
public
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
public
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.isError; // false
record.set('foo', 'valid value');
record.save().then(null, function() {
record.isError; // true
});
isLoaded
Boolean
public
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.isLoaded; // true
store.findRecord('model', 1).then(function(model) {
model.isLoaded; // true
});
isLoading
Boolean
public
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
public
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.isNew; // true
record.save().then(function(model) {
model.isNew; // false
});
isReloading
Boolean
public
If true
the store is attempting to reload the record from the adapter.
Example
record.isReloading; // false
record.reload();
record.isReloading; // true
isSaving
Boolean
public
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.isSaving; // false
let promise = record.save();
record.isSaving; // true
promise.then(function() {
record.isSaving; // false
});
isValid
Boolean
public
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
public
static
Represents the model's class name as a string. This can be used to look up the model's class name through
Store
's modelFor method.
modelName
is generated for you by EmberData. 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 RESTSerializer from '@ember-data/serializer/rest';
import { underscore } from '<app-name>/utils/string-utils';
export default const PostSerializer = RESTSerializer.extend({
payloadKeyFromModelName(modelName) {
return underscore(modelName);
}
});
relationshipNames
Object
public
static
A hash containing lists of the model's relationships, grouped by the relationship kind. For example, given a model with this definition:
import Model, { belongsTo, hasMany } from '@ember-data/model';
export default class BlogModel extends Model {
@hasMany('user') users;
@belongsTo('user') owner;
@hasMany('post') posts;
}
This property would contain the following:
import Blog from 'app/models/blog';
let relationshipNames = Blog.relationshipNames;
relationshipNames.hasMany;
//=> ['users', 'posts']
relationshipNames.belongsTo;
//=> ['owner']
relationships
Map
public
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 Model, { belongsTo, hasMany } from '@ember-data/model';
export default class BlogModel extends Model {
@hasMany('user') users;
@belongsTo('user') owner;
@hasMany('post') posts;
}
This computed property would return a map describing these relationships, like this:
import Blog from 'app/models/blog';
import User from 'app/models/user';
import Post from 'app/models/post';
let relationships = Blog.relationships;
relationships.user;
//=> [ { name: 'users', kind: 'hasMany' },
// { name: 'owner', kind: 'belongsTo' } ]
relationships.post;
//=> [ { name: 'posts', kind: 'hasMany' } ]
relationshipsByName
Map
public
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 Model, { belongsTo, hasMany } from '@ember-data/model';
export default class BlogModel extends Model {
@hasMany('user') users;
@belongsTo('user') owner;
@hasMany('post') posts;
}
This property would contain the following:
import Blog from 'app/models/blog';
let relationshipsByName = Blog.relationshipsByName;
relationshipsByName.users;
//=> { name: 'users', kind: 'hasMany', type: 'user', options: Object }
relationshipsByName.owner;
//=> { name: 'owner', kind: 'belongsTo', type: 'user', options: Object }
store
Unknown
public
The store service instance which created this record instance
transformedAttributes
Map
public
static
A map whose keys are the attributes of the model (properties described by 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 Model, { attr } from '@ember-data/model';
export default class PersonModel extends Model {
@attr firstName;
@attr('string') lastName;
@attr('date') birthday;
}
import Person from 'app/models/person';
let transformedAttributes = Person.transformedAttributes
transformedAttributes.forEach(function(field, type) {
// do thing
});
// prints:
// lastName string
// birthday date