Summary

This class manages arbitrary data and its relationship to data models. Instances of ViewModel are associated with some Component and then used by their child items for the purposes of Data Binding.

Binding

The most commonly used aspect of a ViewModel is the bind method. This method takes a "bind descriptor" (see below) and a callback to call when the data indicated by the bind descriptor either becomes available or changes.

The bind method, based on the bind descriptor given, will return different types of "binding" objects. These objects maintain the connection between the requested data and the callback. Bindings ultimately derive from Ext.app.bind.BaseBinding which provides several methods to help manage the binding.

Perhaps the most important method is destroy. When the binding is no longer needed it is important to remember to destroy it. Leaking bindings can cause performance problems or worse when callbacks are called at unexpected times.

The types of bindings produced by bind are:

• Ext.app.bind.Binding
• Ext.app.bind.Multi
• Ext.app.bind.TemplateBinding

Bind Descriptors

A "bind descriptor" is a value (a String, an Object or an array of these) that describe the desired data. Any piece of data in the ViewModel can be described by a bind descriptor.

Textual Bind Descriptors

The simplest and most common form of bind descriptors are strings that look like an Ext.Template containing text and tokens surrounded by "{}" with dot notation inside to traverse objects and their properties.

For example:

• 'Hello {user.name}!'
• 'You have selected "{selectedItem.text}".'
• '{!isDisabled}'
• '{a > b ? "Bigger" : "Smaller"}'
• '{user.groups}'

All except the last are Ext.app.bind.TemplateBinding which use the familiar Ext.Template syntax with some slight differences. For more on templates see Ext.app.bind.Template.

The last descriptor is called a "direct bind descriptor". This special form of bind maps one-to-one to some piece of data in the ViewModel and is managed by the Ext.app.bind.Binding class.

Two-Way Descriptors

A direct bind descriptor may be able to write back a value to the ViewModel as well as retrieve one. When this is the case, they are said to be "two-way". For example:

 var binding = viewModel.bind('{s}', function(s) { console.log('s=' + s); });

 binding.setValue('abc');

Direct use of ViewModel in this way is not commonly needed because Ext.Component automates this process. For example, a textfield component understands when it is given a "two-way" binding and automatically synchronizes its value bidirectionally using the above technique. For example:

 Ext.widget({
     items: [{
         xtype: 'textfield',
         bind: '{s}'  // a two-way / direct bind descriptor
     }]
 });

Object and Array Descriptors / Multi-Bind

With two exceptions (see below) an Object is interpreted as a "shape" to produce by treating each of its properties as individual bind descriptors. An object of the same shape is passed as the value of the bind except that each property is populated with the appropriate value. Of course, this definition is recursive, so these properties may also be objects.

For example:

 viewModel.bind({
         x: '{x}',
         foo: {
             bar: 'Hello {foo.bar}'
         }
     },
     function (obj) {
         //  obj = {
         //      x: 42,
         //      foo: {
         //          bar: 'Hello foobar'
         //      }
         //  }
     });

Arrays are handled in the same way. Each element of the array is considered a bind descriptor (recursively) and the value produced for the binding is an array with each element set to the bound property.

Bind Options

One exception to the "object is a multi-bind" rule is when that object contains a bindTo property. When an object contains a bindTo property the object is understood to contain bind options and the value of bindTo is considered the actual bind descriptor.

For example:

 viewModel.bind({
         bindTo: '{x}',
         single: true
     },
     function (x) {
         console.log('x: ' + x); // only called once
     });

The available bind options depend on the type of binding, but since all bindings derive from Ext.app.bind.BaseBinding its options are always applicable. For a list of the other types of bindings, see above.

Deep Binding

When a direct bind is made and the bound property is an object, by default the binding callback is only called when that reference changes. This is the most efficient way to understand a bind of this type, but sometimes you may need to be notified if any of the properties of that object change.

To do this, we create a "deep bind":

 viewModel.bind({
         bindTo: '{someObject}',
         deep: true
     },
     function (someObject) {
         // called when reference changes or *any* property changes
     });

Binding Timings

The ViewModel has a scheduler attached that is used to coordinate the firing of bindings. It serves 2 main purposes:

• To coordinate dependencies between bindings. This means bindings will be fired in an order such that the any dependencies for a binding are fired before the binding itself.
• To batch binding firings. The scheduler runs on a short timer, so the following code will only trigger a single binding (the last), the changes in between will never be triggered.

Example:

viewModel.bind('{val}', function(v) {
    console.log(v);
});
viewModel.set('val', 1);
viewModel.set('val', 2);
viewModel.set('val', 3);
viewModel.set('val', 4);

The ViewModel can be forced to process by calling notify, which will force the scheduler to run immediately in the current state.

viewModel.bind('{val}', function(v) {
    console.log(v);
});
viewModel.set('val', 1);
viewModel.notify();
viewModel.set('val', 2);
viewModel.notify();
viewModel.set('val', 3);
viewModel.notify();
viewModel.set('val', 4);
viewModel.notify();

Models, Stores and Associations

A Ext.data.Session manages model instances and their associations. The ViewModel may be used with or without a Session. When a Session is attached, the ViewModel will always consult the Session to ask about records and stores. The Session ensures that only a single instance of each model Type/Id combination is created. This is important when tracking changes in models so that we always have the same reference.

A ViewModel provides functionality to easily consume the built in data package types Ext.data.Model and Ext.data.Store, as well as their associations.

Model Links

A model can be described declaratively using links. In the example code below, We ask the ViewModel to construct a record of type User with id: 17. The model will be loaded from the server and the bindings will trigger once the load has completed. Similarly, we could also attach a model instance to the ViewModel data directly.

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: ['name']
});

var rec = new MyApp.model.User({
    id: 12,
    name: 'Foo'
});

var viewModel = new Ext.app.ViewModel({
    links: {
        theUser: {
            type: 'User',
            id: 17
        }
    },
    data: {
        otherUser: rec
    }
});
viewModel.bind('{theUser.name}', function(v) {
    console.log(v);
});
viewModel.bind('{otherUser.name}', function(v) {
    console.log(v);
});

Model Fields

Bindings have the functionality to inspect the parent values and resolve the underlying value dynamically. This behavior allows model fields to be interrogated as part of a binding.

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: ['name', 'age']
});

var viewModel = new Ext.app.ViewModel({
    links: {
        theUser: {
            type: 'User',
            id: 22
        }
    }
});

// Server responds with:
{
    "id": 22,
    "name": "Foo",
    "age": 100
}

viewModel.bind('Hello {name}, you are {age} years old', function(v) {
    console.log(v);
});

Record Properties

It is possible to bind to the certain state properties of a record. The available options are:

• dirty
• phantom
• valid

Example usage:

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: [{
        name: 'name',
        validators: 'presence'
    }, {
        name: 'age',
        validators: {
           type: 'range',
            min: 0
         }
    }]
});

var rec = new MyApp.model.User();

var viewModel = new Ext.app.ViewModel({
    data: {
        theUser: rec
    }
});

viewModel.bind({
    dirty: '{theUser.dirty}',
    phantom: '{theUser.phantom}',
    valid: '{theUser.valid}'
}, function(v) {
    console.log(v.dirty, v.valid);
});

rec.set('name', 'Foo');
viewModel.notify(); // dirty, not valid
rec.set('age', 20);
viewModel.notify(); // dirty, valid
rec.reject();
viewModel.notify(); // not dirty, not valid

Advanced Record Binding

For accessing other record information that is not exposed by the binding API, formulas can be used to achieve more advanced operations:

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: ['name', 'age']
});

var rec = new MyApp.model.User();

var viewModel = new Ext.app.ViewModel({
    formulas: {
        isNameModified: {
            bind: {
                bindTo: '{theUser}',
                deep: true
            },
            get: function(rec) {
                return rec.isModified('name');
            }
        }
    },
    data: {
        theUser: rec
    }
});

viewModel.bind('{isNameModified}', function(modified) {
    console.log(modified);
});
rec.set('name', 'Foo');

Associations

In the same way as fields, the bindings can also traverse associations in a bind statement. The ViewModel will handle the asynchronous loading of data and only present the value once the full path has been loaded. For more information on associations see Ext.data.schema.OneToOne and Ext.data.schema.ManyToOne associations.

Ext.define('User', {
    extend: 'Ext.data.Model',
    fields: ['name']
});

Ext.define('Order', {
    extend: 'Ext.data.Model',
    fields: ['date', {
        name: 'userId',
        reference: 'User'
    }]
});

Ext.define('OrderItem', {
    extend: 'Ext.data.Model',
    fields: ['price', 'qty', {
        name: 'orderId',
        reference: 'Order'
    }]
});

var viewModel = new Ext.app.ViewModel({
    links: {
        orderItem: {
            type: 'OrderItem',
            id: 13
        }
    }
});
// The viewmodel will handle both ways of loading the data:
// a) If the data is loaded inline in a nested fashion it will
//    not make requests for extra data
// b) Only loading a single model at a time. So the Order will be loaded once
//    the OrderItem returns. The User will be loaded once the Order loads.
viewModel.bind('{orderItem.order.user.name}', function(name) {
    console.log(name);
});

Stores

Stores can be created as part of the ViewModel definition. The definitions are processed like bindings which allows for very powerful dynamic functionality.

It is important to ensure that you name viewModel's data keys uniquely. If data is not named uniquely, binds and formulas may receive information from an unintended data source. This applies to keys in the viewModel's data block, stores, and links configs.

var viewModel = new Ext.app.ViewModel({
    stores: {
        users: {
            model: 'User',
            autoLoad: true,
            filters: [{
                property: 'createdDate',
                value: '{createdFilter}',
                operator: '>'
            }]
        }
    }
});
// Later on in our code, we set the date so that the store is created.
viewModel.set('createdFilter', Ext.Date.subtract(new Date(), Ext.Date.DAY, 7));

See stores for more detail.

Store Properties

It is possible to bind to the certain state properties of the store. The available options are:

• count
• Ext.data.Store#method-first
• Ext.data.Store#method-last
• loading
• totalCount

Example:

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: ['name']
});

var viewModel = new Ext.app.ViewModel({
    stores: {
        users: {
            model: 'MyApp.model.User',
            data: [{
                name: 'Foo'
            }, {
                name: 'Bar'
            }]
        }
    }
});

viewModel.bind('{users.first}', function(first) {
    console.log(first ? first.get('name') : 'Nobody');
});

var timer = Ext.interval(function() {
    var store = viewModel.getStore('users');
    if (store.getCount()) {
        store.removeAt(0);
    } else {
        Ext.uninterval(timer);
    }
}, 100);

Advanced Store Binding

For accessing other store information that is not exposed by the binding API, formulas can be used to achieve more advanced operations:

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',
    fields: ['name', 'score']
});

var viewModel = new Ext.app.ViewModel({
    stores: {
        users: {
            model: 'MyApp.model.User',
            data: [{
                name: 'Foo',
                score: 100
            }, {
                name: 'Bar',
                score: 350
            }]
        }
    },
    formulas: {
        totalScore: {
            bind: {
                bindTo: '{users}',
                deep: true
            },
            get: function(store) {
                return store.sum('score');
            }
        }
    }
});

viewModel.bind('{totalScore}', function(score) {
    console.log(score);
});

viewModel.notify();
viewModel.getStore('users').removeAll();

Formulas

Formulas allow for calculated ViewModel data values. The dependencies for these formulas are automatically determined so that the formula will not be processed until the required data is present.

var viewModel = new Ext.app.ViewModel({
    formulas: {
        fullName: function(get) {
            return get('firstName') + ' ' + get('lastName');
        }
    },
    data: {firstName: 'John', lastName: 'Smith'}
});

viewModel.bind('{fullName}', function(v) {
    console.log(v);
});

See formulas for more detail.

Inheriting Data With Nesting

ViewModels can have a parent which allows values to be consumed from a shared base. These values that are available from the parent are not copied, rather they are "inherited" in a similar fashion to a javascript closure scope chain. This is demonstrated in the example below:

var parent = new Ext.app.ViewModel({
    data: {
        foo: 3
    }
});
var child = new Ext.app.ViewModel({
    parent: parent
});

This is analogous to the following javascript closure:

var foo = 3;
Ext.Ajax.request({
    success: function() {
        // foo is available here
    }
});

Climbing/Inheriting

In line with the above, the default behaviour when setting the value of a child ViewModel (either) through set or Ext.app.bind.Binding#method-setValue is to climb to where the value is "owned" and set the value there:

var parent = new Ext.app.ViewModel({
    data: {
        foo: 3
    }
});
var child = new Ext.app.ViewModel({
    parent: parent
});

child.set('foo', 100); // Climbs to set the value on parent
console.log(parent.get('foo')); // 100
parent.set('foo', 200);
console.log(child.get('foo')); // 200, inherited from the parent

Any subsequent sets are also inherited in the same fashion. The inheriting/climbing behavior occurs for any arbitrary depth, climbing/inherting can owned by a parent at any level above.

function log() {
    console.log([a, b, c, d, e].map(function(vm) {
        return vm.get('foo');
    }));
}

var a = new Ext.app.ViewModel({data: {foo: 3}}),
    b = new Ext.app.ViewModel({parent: a}),
    c = new Ext.app.ViewModel({parent: b}),
    d = new Ext.app.ViewModel({parent: c}),
    e = new Ext.app.ViewModel({parent: d});

log(); // [3, 3, 3, 3, 3]

e.set('foo', 100);
log(); // [100, 100, 100, 100, 100]

This same climbing behavior applies when setting a value on a binding. The climbing begins from the ViewModel where the binding was attached:

function log() {
    console.log([a, b, c].map(function(vm) {
        return vm.get('foo');
    }));
}

var a = new Ext.app.ViewModel({data: {foo: 3}}),
    b = new Ext.app.ViewModel({parent: a}),
    c = new Ext.app.ViewModel({parent: b});

var bind = c.bind('{foo}', function() {});

bind.setValue(100);
log(); // [100, 100, 100]

The exception to this rule is when there is nothing above to climb to. If a value is set and there is no parent above to hold it, then the value is set where it was called:

function log() {
    console.log([a, b, c].map(function(vm) {
        return vm.get('foo');
    }));
}

var a = new Ext.app.ViewModel(),
    b = new Ext.app.ViewModel({parent: a}),
    c = new Ext.app.ViewModel({parent: b});

c.set('foo', 3);
log(); // [null, null, 3]

b.set('foo', 2);
log(); // [null, 2, 3]

a.set('foo', 1);
log(); // [1, 2, 3]

These values are called local values, which are discussed below.

Local Values

If the child ViewModel is declared with top level data that also exists in the parent, then that child is considered to own that local value, so no value is inherited from the parent, nor does the climbing behaviour occur.

var parent = new Ext.app.ViewModel({
    data: {
        foo: 3
    }
});
var child = new Ext.app.ViewModel({
    parent: parent,
    data: {
        foo: 5
    }
});

console.log(parent.get('foo'), child.get('foo')); // 3, 5
child.set('foo', 100);
console.log(parent.get('foo'), child.get('foo')); // 3, 100
parent.set('foo', 200);
console.log(parent.get('foo'), child.get('foo')); // 200, 100

The inheriting/climbing behavior is limited to local values:

function log() {
    console.log([a, b, c, d, e].map(function(vm) {
        return vm.get('foo');
    }));
}

var a = new Ext.app.ViewModel({data: {foo: 1}}),
    b = new Ext.app.ViewModel({parent: a}),
    c = new Ext.app.ViewModel({parent: b, data: {foo: 2}}),
    d = new Ext.app.ViewModel({parent: c}),
    e = new Ext.app.ViewModel({parent: d, data: {foo: 3}});

log(); // [1, 1, 2, 2, 3]

e.set('foo', 100);
log(); // [1, 1, 2, 2, 100]

d.set('foo', 200);
log(); // [1, 1, 200, 200, 100]

c.set('foo', 201);
log(); // [1, 1, 201, 201, 100]

b.set('foo', 300);
log(); // [300, 300, 201, 201, 100]

a.set('foo', 301);
log(); // [301, 301, 201, 201, 100]

Attaching/Clearing Local Values Dynamically

To bypass the climbing behaviour and push a value into a particular point in the hierarchy, the setData method should be used. Once a local value is set, it will be used as such in the future.

function log() {
    console.log([a, b, c, d, e].map(function(vm) {
        return vm.get('foo');
    }));
}

var a = new Ext.app.ViewModel({data: {foo: 3}}),
    b = new Ext.app.ViewModel({parent: a}),
    c = new Ext.app.ViewModel({parent: b}),
    d = new Ext.app.ViewModel({parent: c}),
    e = new Ext.app.ViewModel({parent: d});

log(); // [3, 3, 3, 3, 3]

c.setData({
    foo: 100
});

log(); // [3, 3, 100, 100, 100]

d.set('foo', 200); // Climbs to new local value
log(); // [3, 3, 200, 200, 200]

Similarly, data can be cleared from being a local value by setting the value to undefined:

function log() {
    console.log([a, b, c, d].map(function(vm) {
        return vm.get('foo');
    }));
}

var a = new Ext.app.ViewModel({data: {foo: 3}}),
    b = new Ext.app.ViewModel({parent: a}),
    c = new Ext.app.ViewModel({parent: b, data: {foo: 100}}),
    d = new Ext.app.ViewModel({parent: c});

log(); // [3, 3, 100, 100]

c.setData({
    foo: undefined
});
log([3, 3, 3, 3]);