@ember/object - 3.26 - Ember API Documentation

action (callback) PropertyDecorator public

Module: @ember/object

Defined in packages/@ember/object/index.js:5

import { action } from '@ember/object';

callback: Function|undefined; The function to turn into an action, when used in classic classes
returns: PropertyDecorator; property decorator instance

Decorator that turns the target function into an Action which can be accessed directly by reference.

        
              import Component from '@ember/component';
import { action, set } from '@ember/object';

export default class Tooltip extends Component {
  @action
  toggleShowing() {
    set(this, 'isShowing', !this.isShowing);
  }
}

        
              <!-- template.hbs -->
<button {{action this.toggleShowing}}>Show tooltip</button>

{{#if isShowing}}
  <div class="tooltip">
    I'm a tooltip!
  </div>
{{/if}}

Decorated actions also interop with the string style template actions:

        
              <!-- template.hbs -->
<button {{action "toggleShowing"}}>Show tooltip</button>

{{#if isShowing}}
  <div class="tooltip">
    I'm a tooltip!
  </div>
{{/if}}

It also binds the function directly to the instance, so it can be used in any context and will correctly refer to the class it came from:

        
          
              
              <!-- template.hbs -->
<button
  {{did-insert this.toggleShowing}}
  {{on "click" this.toggleShowing}}
>
  Show tooltip
</button>

{{#if isShowing}}
  <div class="tooltip">
    I'm a tooltip!
  </div>
{{/if}}
            

        
      

This can also be used in JavaScript code directly:

        
              import Component from '@ember/component';
import { action, set } from '@ember/object';

export default class Tooltip extends Component {
  constructor() {
    super(...arguments);

    // this.toggleShowing is still bound correctly when added to
    // the event listener
    document.addEventListener('click', this.toggleShowing);
  }

  @action
  toggleShowing() {
    set(this, 'isShowing', !this.isShowing);
  }
}

This is considered best practice, since it means that methods will be bound correctly no matter where they are used. By contrast, the {{action}} helper and modifier can also be used to bind context, but it will be required for every usage of the method:

        
          
              
              <!-- template.hbs -->
<button
  {{did-insert (action this.toggleShowing)}}
  {{on "click" (action this.toggleShowing)}}
>
  Show tooltip
</button>

{{#if isShowing}}
  <div class="tooltip">
    I'm a tooltip!
  </div>
{{/if}}
            

        
      

They also do not have equivalents in JavaScript directly, so they cannot be used for other situations where binding would be useful.

computed (dependentKeys*, func) ComputedDecorator public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/computed.ts:880

import { computed } from '@ember/object';

dependentKeys*: String; Optional dependent keys that trigger this computed property.
func: Function; The computed property function.
returns: ComputedDecorator; property decorator instance

This helper returns a new property descriptor that wraps the passed computed property function. You can use this helper to define properties with native decorator syntax, mixins, or via defineProperty().

Example:

        
              import { computed, set } from '@ember/object';

class Person {
  constructor() {
    this.firstName = 'Betty';
    this.lastName = 'Jones';
  },

  @computed('firstName', 'lastName')
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
}

let client = new Person();

client.fullName; // 'Betty Jones'

set(client, 'lastName', 'Fuller');
client.fullName; // 'Betty Fuller'

Classic Class Example:

        
              import EmberObject, { computed } from '@ember/object';

let Person = EmberObject.extend({
  init() {
    this._super(...arguments);

    this.firstName = 'Betty';
    this.lastName = 'Jones';
  },

  fullName: computed('firstName', 'lastName', function() {
    return `${this.get('firstName')} ${this.get('lastName')}`;
  })
});

let client = Person.create();

client.get('fullName'); // 'Betty Jones'

client.set('lastName', 'Fuller');
client.get('fullName'); // 'Betty Fuller'

You can also provide a setter, either directly on the class using native class syntax, or by passing a hash with get and set functions.

Example:

        
              import { computed, set } from '@ember/object';

class Person {
  constructor() {
    this.firstName = 'Betty';
    this.lastName = 'Jones';
  },

  @computed('firstName', 'lastName')
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }

  set fullName(value) {
    let [firstName, lastName] = value.split(/\s+/);

    set(this, 'firstName', firstName);
    set(this, 'lastName', lastName);

    return value;
  }
}

let client = new Person();

client.fullName; // 'Betty Jones'

set(client, 'lastName', 'Fuller');
client.fullName; // 'Betty Fuller'

Classic Class Example:

        
          
              
              import EmberObject, { computed } from '@ember/object';

let Person = EmberObject.extend({
  init() {
    this._super(...arguments);

    this.firstName = 'Betty';
    this.lastName = 'Jones';
  },

  fullName: computed('firstName', 'lastName', {
    get(key) {
      return `${this.get('firstName')} ${this.get('lastName')}`;
    },
    set(key, value) {
      let [firstName, lastName] = value.split(/\s+/);
      this.setProperties({ firstName, lastName });
      return value;
    }
  })
});

let client = Person.create();
client.get('firstName'); // 'Betty'

client.set('fullName', 'Carroll Fuller');
client.get('firstName'); // 'Carroll'
            

        
      

When passed as an argument, the set function should accept two parameters, key and value. The value returned from set will be the new value of the property.

Note: This is the preferred way to define computed properties when writing third-party libraries that depend on or use Ember, since there is no guarantee that the user will have prototype Extensions enabled.

The alternative syntax, with prototype extensions, might look like:

        
              fullName: function() {
  return this.get('firstName') + ' ' + this.get('lastName');
}.property('firstName', 'lastName')

This form does not work with native decorators.

create (arguments) public

Module: @ember/object

Defined in packages/@ember/-internals/runtime/lib/system/core_object.js:801

arguments

Creates an instance of a class. Accepts either no arguments, or an object containing values to initialize the newly instantiated object with.

        
              import EmberObject from '@ember/object';

const Person = EmberObject.extend({
  helloWorld() {
    alert(`Hi, my name is ${this.get('name')}`);
  }
});

let tom = Person.create({
  name: 'Tom Dale'
});

tom.helloWorld(); // alerts "Hi, my name is Tom Dale".

create will call the init function if defined during AnyObject.extend

If no arguments are passed to create, it will not set values to the new instance during initialization:

        
              let noName = Person.create();
noName.helloWorld(); // alerts undefined

NOTE: For performance reasons, you cannot declare methods or computed properties during create. You should instead declare methods and computed properties when using extend.

defineProperty (obj, keyName, desc, data) public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/properties.ts:11

import { defineProperty } from '@ember/object';

obj: Object; the object to define this property on. This may be a prototype.
keyName: String; the name of the property
desc: Descriptor; an instance of `Descriptor` (typically a computed property) or an ES5 descriptor. You must provide this or `data` but not both.
data: *; something other than a descriptor, that will become the explicit value of this property.

NOTE: This is a low-level method used by other parts of the API. You almost never want to call this method directly. Instead you should use mixin() to define new properties.

Defines a property on an object. This method works much like the ES5 Object.defineProperty() method except that it can also accept computed properties and other special descriptors.

Normally this method takes only three parameters. However if you pass an instance of Descriptor as the third param then you can pass an optional value as the fourth parameter. This is often more efficient than creating new descriptor hashes for each property.

Examples

        
              import { defineProperty, computed } from '@ember/object';

// ES5 compatible mode
defineProperty(contact, 'firstName', {
  writable: true,
  configurable: false,
  enumerable: true,
  value: 'Charles'
});

// define a simple property
defineProperty(contact, 'lastName', undefined, 'Jolley');

// define a computed property
defineProperty(contact, 'fullName', computed('firstName', 'lastName', function() {
  return this.firstName+' '+this.lastName;
}));

extend (mixins, arguments) public

Module: @ember/object

Defined in packages/@ember/-internals/runtime/lib/system/core_object.js:701

mixins: Mixin; One or more Mixin classes
arguments: Object; Object containing values to use within the new class

Creates a new subclass.

        
              import EmberObject from '@ember/object';

const Person = EmberObject.extend({
  say(thing) {
    alert(thing);
   }
});

This defines a new subclass of EmberObject: Person. It contains one method: say().

You can also create a subclass from any existing class by calling its extend() method. For example, you might want to create a subclass of Ember's built-in Component class:

        
              import Component from '@ember/component';

const PersonComponent = Component.extend({
  tagName: 'li',
  classNameBindings: ['isAdministrator']
});

When defining a subclass, you can override methods but still access the implementation of your parent class by calling the special _super() method:

        
          
              
              import EmberObject from '@ember/object';

const Person = EmberObject.extend({
  say(thing) {
    let name = this.get('name');
    alert(`${name} says: ${thing}`);
  }
});

const Soldier = Person.extend({
  say(thing) {
    this._super(`${thing}, sir!`);
  },
  march(numberOfHours) {
    alert(`${this.get('name')} marches for ${numberOfHours} hours.`);
  }
});

let yehuda = Soldier.create({
  name: 'Yehuda Katz'
});

yehuda.say('Yes');  // alerts "Yehuda Katz says: Yes, sir!"
            

        
      

The create() on line #17 creates an instance of the Soldier class. The extend() on line #8 creates a subclass of Person. Any instance of the Person class will not have the march() method.

You can also pass Mixin classes to add additional properties to the subclass.

        
          
              
              import EmberObject from '@ember/object';
import Mixin from '@ember/object/mixin';

const Person = EmberObject.extend({
  say(thing) {
    alert(`${this.get('name')} says: ${thing}`);
  }
});

const SingingMixin = Mixin.create({
  sing(thing) {
    alert(`${this.get('name')} sings: la la la ${thing}`);
  }
});

const BroadwayStar = Person.extend(SingingMixin, {
  dance() {
    alert(`${this.get('name')} dances: tap tap tap tap `);
  }
});
            

        
      

The BroadwayStar class contains three methods: say(), sing(), and dance().

get (obj, keyName) Object public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/property_get.ts:47

import { get } from '@ember/object';

obj: Object; The object to retrieve from.
keyName: String; The property key to retrieve
returns: Object; the property value or `null`.

Gets the value of a property on an object. If the property is computed, the function will be invoked. If the property is not defined but the object implements the unknownProperty method then that will be invoked.

        
              import { get } from '@ember/object';
get(obj, "name");

If you plan to run on IE8 and older browsers then you should use this method anytime you want to retrieve a property on an object that you don't know for sure is private. (Properties beginning with an underscore '_' are considered private.)

On all newer browsers, you only need to use this method to retrieve properties if the property might not be defined on the object and you want to respect the unknownProperty handler. Otherwise you can ignore this method.

Note that if the object itself is undefined, this method will throw an error.

getProperties (obj, list) Object public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/get_properties.ts:6

import { getProperties } from '@ember/object';

obj: Object
list: String...|Array; of keys to get
returns: Object

To get multiple properties at once, call getProperties with an object followed by a list of strings or an array:

        
              import { getProperties } from '@ember/object';

getProperties(record, 'firstName', 'lastName', 'zipCode');
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

is equivalent to:

        
              import { getProperties } from '@ember/object';

getProperties(record, ['firstName', 'lastName', 'zipCode']);
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

notifyPropertyChange (obj, keyName, _meta, value) Void public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/property_events.ts:19

Available since v3.1.0

obj: Object; The object with the property that will change
keyName: String; The property key (or path) that will change.
_meta: Meta; The objects meta.
value: Unknown; The new value to set for the property
returns: Void

This function is called just after an object property has changed. It will notify any observers and clear caches among other things.

Normally you will not need to call this method directly but if for some reason you can't directly watch a property you can invoke this method manually.

observer (propertyNames, func) public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/mixin.ts:845

import { observer } from '@ember/object';

propertyNames: String
func: Function
returns: func

Specify a method that observes property changes.

        
              import EmberObject from '@ember/object';
import { observer } from '@ember/object';

export default EmberObject.extend({
  valueObserver: observer('value', function() {
    // Executes whenever the "value" property changes
  })
});

Also available as Function.prototype.observes if prototype extensions are enabled.

reopen public

Module: @ember/object

Defined in packages/@ember/-internals/runtime/lib/system/core_object.js:861

Augments a constructor's prototype with additional properties and functions:

        
              import EmberObject from '@ember/object';

const MyObject = EmberObject.extend({
  name: 'an object'
});

o = MyObject.create();
o.get('name'); // 'an object'

MyObject.reopen({
  say(msg) {
    console.log(msg);
  }
});

o2 = MyObject.create();
o2.say('hello'); // logs "hello"

o.say('goodbye'); // logs "goodbye"

To add functions and properties to the constructor itself, see reopenClass

reopenClass public

Module: @ember/object

Defined in packages/@ember/-internals/runtime/lib/system/core_object.js:915

Augments a constructor's own properties and functions:

        
              import EmberObject from '@ember/object';

const MyObject = EmberObject.extend({
  name: 'an object'
});

MyObject.reopenClass({
  canBuild: false
});

MyObject.canBuild; // false
o = MyObject.create();

In other words, this creates static properties and functions for the class. These are only available on the class and not on any instance of that class.

        
          
              
              import EmberObject from '@ember/object';

const Person = EmberObject.extend({
  name: '',
  sayHello() {
    alert(`Hello. My name is ${this.get('name')}`);
  }
});

Person.reopenClass({
  species: 'Homo sapiens',

  createPerson(name) {
    return Person.create({ name });
  }
});

let tom = Person.create({
  name: 'Tom Dale'
});
let yehuda = Person.createPerson('Yehuda Katz');

tom.sayHello(); // "Hello. My name is Tom Dale"
yehuda.sayHello(); // "Hello. My name is Yehuda Katz"
alert(Person.species); // "Homo sapiens"
            

        
      

Note that species and createPerson are not valid on the tom and yehuda variables. They are only valid on Person.

To add functions and properties to instances of a constructor by extending the constructor's prototype see reopen

set (obj, keyName, value) Object public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/property_set.ts:23

import { set } from '@ember/object';

obj: Object; The object to modify.
keyName: String; The property key to set
value: Object; The value to set
returns: Object; the passed value.

Sets the value of a property on an object, respecting computed properties and notifying observers and other listeners of the change. If the specified property is not defined on the object and the object implements the setUnknownProperty method, then instead of setting the value of the property on the object, its setUnknownProperty handler will be invoked with the two parameters keyName and value.

        
              import { set } from '@ember/object';
set(obj, "name", value);

setProperties (obj, properties) public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/set_properties.ts:6

import { setProperties } from '@ember/object';

obj
properties: Object
returns: properties

Set a list of properties on an object. These properties are set inside a single beginPropertyChanges and endPropertyChanges batch, so observers will be buffered.

        
              import EmberObject from '@ember/object';
let anObject = EmberObject.create();

anObject.setProperties({
  firstName: 'Stanley',
  lastName: 'Stuart',
  age: 21
});

trySet (root, path, value) public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/property_set.ts:129

import { trySet } from '@ember/object';

root: Object; The object to modify.
path: String; The property path to set
value: Object; The value to set

Error-tolerant form of set. Will not blow up if any part of the chain is undefined, null, or destroyed.

This is primarily used when syncing bindings, which may try to update after an object has been destroyed.

        
              import { trySet } from '@ember/object';

let obj = { name: "Zoey" };
trySet(obj, "contacts.twitter", "@emberjs");

Class @ember/object

action (callback) PropertyDecorator public

computed (dependentKeys*, func) ComputedDecorator public

create (arguments) public

defineProperty (obj, keyName, desc, data) public

Examples

extend (mixins, arguments) public

get (obj, keyName) Object public

getProperties (obj, list) Object public

notifyPropertyChange (obj, keyName, _meta, value) Void public

observer (propertyNames, func) public

reopen public

reopenClass public

set (obj, keyName, value) Object public

setProperties (obj, properties) public

trySet (root, path, value) public