What does .property() do? in function(){}.property()

Question

Todos.TodoController = Ember.ObjectController.extend({   isCompleted: function(key, value){     var model = this.get('model');      if (value === undefined) {       // property being used as a getter       return model.get('isCompleted');     } else {       // property being used as a setter       model.set('isCompleted', value);       model.save();       return value;     }   }.property('model.isCompleted') }); 

I'm working through the ToDo guide for Ember.js and I can't seem to understand how this controller works. What does the .property() mean? And how come when I remove the 'return value;' line the functionality stays the same. If someone could explain exactly what's going on here that would be great.

Link to the guide: http://emberjs.com/guides/getting-started/marking-a-model-as-complete-incomplete/

Answer 1

In javascript the only way to do some processing when getting or setting one property is using Object.defineProperty:

Object.defineProperty(person, "b", {   get : function() {      return person.firstName + ' ' + person.surname;    },   set : function(newValue) {     var names = newValue.split(' ');      person.firsname = names[0];     person.surname = names[1];    },   enumerable : true,   configurable : true }); 

But this have some disadvantages:

• Isn't cross browser
• Doesn't have binding, in other words, if firstname or surname changes, the dependent property fullname isn't changed.
• Calling person.name when person is undefined, make an error to be throwed
• Isn't possible to trigger observers, no without additional code and aware of the depency hierachy: firstname depends from fullname, and it can be dependency of others properties arghhh!

Due to this Ember has the concept of "property", called computed property.

It can be declared in 2 ways:

foo: Ember.computed(function({   ... }).property(dependent keys); 

or when using (the default) Ember.ENV.EXTEND_PROTOTYPES = true:

foo: function() {   ... }.property(dependent keys); 

The property(dependent keys), is needed because it tell to ember what is the properies that when changed, will make the property be updated.

fullname: function(key, value) {   // setter   if (value !== undefined) {     var names = value.split(' ');     this.set('firstname', names[0]);     this.set('surname', names[1]);   }   // always return the complete result, so nexts calls to this.get('fullname') will return the cached value     return this.get('firstname') + ' ' + this.get('surname'); }.property('firstname', 'surname') 

Using this, you have the advantage of:

• when changing firstname or surname to a new value, fullname is changed.
• The beforeObserves are triggered before changing the value, and the observes are triggered after the value change.
• Any template referencing some property is updated
• More then one call to person.get('firstname'), will return a cached value, saving processing. You can disable this using .property(..).volatile()
• Avoid null or undefined errors, when accessing null objects like: controller.get('person.dog.name') returns undefined, if person or dog is undefined.

I hope it helps