attr

  • function
can.Observe.prototype.attr  

Get or set properties on an Observe.

observe.attr()

Gets a collection of all the properties in this can.Observe.

Returns

{Object<String,*>}

an object with all the properties in this can.Observe.

observe.attr(key)

Reads a property from this can.Observe.

Parameters

  1. key {String}

    the property to read

Returns

{*}

the value assigned to key.

observe.attr(key, value)

Assigns value to a property on this can.Observe called key.

Parameters

  1. key {String}

    the property to set

  2. value {*}

    the value to assign to key.

Returns

{can.Observe}

this Observe, for chaining

observe.attr(obj[, removeOthers])

Assigns each value in obj to a property on this can.Observe named after the corresponding key in obj, effectively merging obj into the Observe.

Parameters

  1. obj {Object<String,*>}

    a collection of key-value pairs to set. If any properties already exist on the can.Observe, they will be overwritten.

  2. removeOthers=false {bool}Optional

    whether to remove keys not present in obj. To remove keys without setting other keys, use removeAttr.

Returns

{can.Observe}

this Observe, for chaining

attr gets or sets properties on the can.Observe it's called on. Here's a tour through how all of its forms work:

var people = new can.Observe({});

// set a property:
people.attr('a', 'Alex');

// get a property:
people.attr('a'); // 'Alex'

// set and merge multiple properties:
people.attr({
    a: 'Alice',
    b: 'Bob'
});

// get all properties:
people.attr(); // {a: 'Alice', b: 'Bob'}

// set properties while removing others:
people.attr({
    b: 'Bill',
    e: 'Eve'
}, true);

people.attr(); // {b: 'Bill', e: 'Eve'}

Deep properties

attr can also set and read deep properties. All you have to do is specify the property name as you normally would if you weren't using attr.

var people = new can.Observe({names: {}});

// set a property:
people.attr('names.a', 'Alice');

// get a property:
people.attr('names.a'); // 'Alice'
people.names.attr('a'); // 'Alice'

// get all properties:
people.attr(); // {names: {a: 'Alice'}}

Objects that are added to Observes become Observes themselves behind the scenes, so changes to deep properties fire events at each level, and you can bind at any level. As this example shows, all the same events are fired no matter what level you call attr at:

var people = new can.Observe({names: {}});

people.bind('change', function(ev, attr, how, newVal, oldVal) {
  console.log('people change: ' + attr + ', ' + how + ', ' + newVal + ', ' + oldVal);
});

people.names.bind('change', function(ev, attr, how, newVal, oldVal) {
   console.log('people.names change' + attr + ', ' + how + ', ' + newVal + ', ' + oldVal);
});

people.bind('names', function(ev, newVal, oldVal) {
    console.log('people names: ' + newVal + ', ' + oldVal);
});

people.names.bind('a', function(ev, newVal, oldVal) {
    console.log('people.names a: ' + newVal + ', ' + oldVal);
});

people.bind('names.a', function(ev, newVal, oldVal) {
    console.log('people names.a: ' + newVal + ', ' + oldVal);
});

people.attr('names.a', 'Alice'); // people change: names.a, add, Alice, undefined
                                 // people.names change: a, add, Alice, undefined
                                 // people.names a: Alice, undefined
                                 // people names.a: Alice, undefined

people.names.attr('b', 'Bob');   // people change: names.b, add, Bob, undefined
                                 // people.names change: b, add, Bob, undefined
                                 // people.names b: Bob, undefined
                                 // people names.b: Bob, undefined

See also

For information on the events that are fired on property changes and how to listen for those events, see bind.