DS.Model

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. If you are working on Ember Data internals, you most likely want to be dealing with InternalModel

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.

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;
});

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] }
});

Override the class' create() method to raise an error. This prevents end users from inadvertently calling create() instead of createRecord(). The store is still able to create instances by calling the _create() method. To create an instance of a DS.Model use store.createRecord.

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 Ember from 'ember';

export default Ember.Route.extend({
  actions: {
    softDelete: function() {
      this.controller.get('model').deleteRecord();
    },
    confirm: function() {
      this.controller.get('model').save();
    },
    undo: function() {
      this.controller.get('model').rollbackAttributes();
    }
  }
});

Same as deleteRecord, but saves the record immediately.

Example

import Ember from 'ember';

export default Ember.Route.extend({
  actions: {
    delete: function() {
      let controller = this.controller;
      controller.get('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: function(store, type, snapshot) {
    if (snapshot.adapterOptions.subscribe) {
      // ...
    }
    // ...
  }
});

This Ember.js hook allows an object to be notified when a property is defined.

In this case, we use it to be notified when an Ember Data user defines a belongs-to relationship. In that case, we need to set up observers for each one, allowing us to track relationship changes and automatically reflect changes in the inverse has-many array.

This hook passes the class being set up, as well as the key and value being defined. So, for example, when the user does this:

DS.Model.extend({
 parent: DS.belongsTo('user')
  });

This hook would be called with "parent" as the key and the computed property returned by DS.belongsTo as the value.

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 iteration
• meta 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"}

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.

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.

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 iteration
• type 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

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;
});

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')
 });

import DS from 'ember-data';

export default DS.Model.extend({
   owner: DS.belongsTo('post')
 });

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' }

Reload the record from the adapter.

This will only work if the record has already finished loading.

Example

import Ember from 'ember';

export default Ember.Route.extend({
  actions: {
    reload: function() {
      this.controller.get('model').reload().then(function(model) {
        // do something with the reloaded model
      });
    }
  }
});

Discards any unsaved changes to the given attribute. This feature is not enabled by default. You must enable ds-rollback-attribute and be running a canary build.

Example

record.get('name'); // 'Untitled Document'
record.set('name', 'Doc 1');
record.get('name'); // 'Doc 1'
record.rollbackAttribute('name');
record.get('name'); // 'Untitled Document'

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 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 on the adapterOptions property of the options argument it will be passed to you adapter via the snapshot

record.save({ adapterOptions: { subscribe: false } });

import MyCustomAdapter from './custom-adapter';

export default MyCustomAdapter.extend({
  updateRecord: function(store, type, snapshot) {
    if (snapshot.adapterOptions.subscribe) {
      // ...
    }
    // ...
  }
});

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.

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.

Override the default event firing from Ember.Evented to also call methods with the given name.

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.

Unloads the record from the store. This will cause the record to be destroyed and freed up for garbage collection.

Fired when the record enters the error state.

Fired when the record becomes invalid.

Fired when a new record is commited to the server.

Fired when the record is deleted.

Fired when the record is loaded from the server.

Fired when the record is updated.

Fired when the record is ready to be interacted with, that is either loaded from the server or created locally.

Fired when the record is rolled back.

This property holds the DS.AdapterError object with which last adapter operation was rejected.

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"}

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'

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 backend
• attribute 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}}

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

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
});

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'
});

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
});

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.

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
});

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
});

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.

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
});

If true the store is attempting to reload the record from the adapter.

Example

record.get('isReloading'); // false
record.reload();
record.get('isReloading'); // true

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
});

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.

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:

export default const PostSerializer = DS.RESTSerializer.extend({
  payloadKeyFromModelName: function(modelName) {
    return Ember.String.underscore(modelName);
  }
});

An array of types directly related to a model. Each type will be included once, regardless of the number of relationships it has with the model.

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 relatedTypes = Ember.get(Blog, 'relatedTypes');
//=> [ User, Post ]

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']

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' } ]

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 }

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