A Model represents some object that your application manages. For example, one might define a Model for Users, Products, Cars, or any other real-world object that we want to model in the system. Models are registered via the model manager, and are used by stores, which are in turn used by many of the data-bound components in Ext.
Models are defined as a set of fields and any arbitrary methods and properties relevant to the model. For example:
Ext.regModel('User', {
fields: [
{name: 'name', type: 'string'},
{name: 'age', type: 'int'},
{name: 'phone', type: 'string'},
{name: 'alive', type: 'boolean', defaultValue: true}
],
changeName: function() {
var oldName = this.get('name'),
newName = oldName + " The Barbarian";
this.set('name', newName);
}
});The fields array is turned into a MixedCollection automatically by the ModelMgr, and all other functions and properties are copied to the new Model's prototype.
Now we can create instances of our User model and call any model logic we defined:
var user = Ext.ModelMgr.create({
name : 'Conan',
age : 24,
phone: '555-555-5555'
}, 'User');
user.changeName();
user.get('name'); //returns "Conan The Barbarian"Validations
Models have built-in support for validations, which are executed against the validator functions in Ext.data.validations (see all validation functions). Validations are easy to add to models:
Ext.regModel('User', {
fields: [
{name: 'name', type: 'string'},
{name: 'age', type: 'int'},
{name: 'phone', type: 'string'},
{name: 'gender', type: 'string'},
{name: 'username', type: 'string'},
{name: 'alive', type: 'boolean', defaultValue: true}
],
validations: [
{type: 'presence', field: 'age'},
{type: 'length', field: 'name', min: 2},
{type: 'inclusion', field: 'gender', list: ['Male', 'Female']},
{type: 'exclusion', field: 'username', list: ['Admin', 'Operator']},
{type: 'format', field: 'username', matcher: /([a-z]+)[0-9]{2,3}/}
]
});The validations can be run by simply calling the validate function, which returns a Ext.data.Errors object:
var instance = Ext.ModelMgr.create({
name: 'Ed',
gender: 'Male',
username: 'edspencer'
}, 'User');
var errors = instance.validate();Associations
Models can have associations with other Models via belongsTo and hasMany associations. For example, let's say we're writing a blog administration application which deals with Users, Posts and Comments. We can express the relationships between these models like this:
Ext.regModel('Post', {
fields: ['id', 'user_id'],
belongsTo: 'User',
hasMany : {model: 'Comment', name: 'comments'}
});
Ext.regModel('Comment', {
fields: ['id', 'user_id', 'post_id'],
belongsTo: 'Post'
});
Ext.regModel('User', {
fields: ['id'],
hasMany: [
'Post',
{model: 'Comment', name: 'comments'}
]
});See the docs for Ext.data.BelongsToAssociation and Ext.data.HasManyAssociation for details on the usage and configuration of associations. Note that associations can also be specified like this:
Ext.regModel('User', {
fields: ['id'],
associations: [
{type: 'hasMany', model: 'Post', name: 'posts'},
{type: 'hasMany', model: 'Comment', name: 'comments'}
]
});Using a Proxy
Models are great for representing types of data and relationships, but sooner or later we're going to want to load or save that data somewhere. All loading and saving of data is handled via a Proxy, which can be set directly on the Model:
Ext.regModel('User', {
fields: ['id', 'name', 'email'],
proxy: {
type: 'rest',
url : '/users'
}
});Here we've set up a Rest Proxy, which knows how to load and save data to and from a RESTful backend. Let's see how this works:
var user = Ext.ModelMgr.create({name: 'Ed Spencer', email: '[email protected]'}, 'User');
user.save(); //POST /usersCalling save on the new Model instance tells the configured RestProxy that we wish to persist this Model's data onto our server. RestProxy figures out that this Model hasn't been saved before because it doesn't have an id, and performs the appropriate action - in this case issuing a POST request to the url we configured (/users). We configure any Proxy on any Model and always follow this API - see Ext.data.Proxy for a full list.
Loading data via the Proxy is equally easy:
//get a reference to the User model class
var User = Ext.ModelMgr.getModel('User');
//Uses the configured RestProxy to make a GET request to /users/123
User.load(123, {
success: function(user) {
console.log(user.getId()); //logs 123
}
});Models can also be updated and destroyed easily:
//the user Model we loaded in the last snippet:
user.set('name', 'Edward Spencer');
//tells the Proxy to save the Model. In this case it will perform a PUT request to /users/123 as this Model already has an id
user.save({
success: function() {
console.log('The User was updated');
}
});
//tells the Proxy to destroy the Model. Performs a DELETE request to /users/123
user.destroy({
success: function() {
console.log('The User was destroyed!');
}
});Usage in Stores
It is very common to want to load a set of Model instances to be displayed and manipulated in the UI. We do this by creating a Store:
var store = new Ext.data.Store({
model: 'User'
});
//uses the Proxy we set up on Model to load the Store data
store.load();A Store is just a collection of Model instances - usually loaded from a server somewhere. Store can also maintain a set of added, updated and removed Model instances to be synchronized with the server via the Proxy. See the Store docs for more information on Stores.
A config object containing one or more event handlers to be added to this object during initialization. This should be a valid listeners config object as specified in the addListener example for attaching multiple handlers at once.
DOM events from ExtJs Components
While some ExtJs Component classes export selected DOM events (e.g. "click", "mouseover" etc), this
is usually only done when extra value can be added. For example the DataView's
click event passing the node clicked on. To access DOM
events directly from a child element of a Component, we need to specify the element option to
identify the Component property to add a DOM listener to:
new Ext.Panel({
width: 400,
height: 200,
dockedItems: [{
xtype: 'toolbar'
}],
listeners: {
click: {
element: 'el', //bind to the underlying el property on the panel
fn: function(){ console.log('click el'); }
},
dblclick: {
element: 'body', //bind to the underlying body property on the panel
fn: function(){ console.log('dblclick body'); }
}
}
});true
or the first event name string if multiple event names are being passed as separate parameters.this.addEvents('storeloaded', 'storecleared');this reference) in which the handler function is executed.
If omitted, defaults to the object which fired the event.this reference) in which the handler function is executed.
If omitted, defaults to the object which fired the event.This option is useful during Component construction to add DOM event listeners to elements of Components which will exist only after the Component is rendered. For example, to add a click listener to a Panel's body:
new Ext.Panel({
title: 'The title',
listeners: {
click: this.handlePanelClick,
element: 'body'
}
});When added in this way, the options available are the options applicable to Ext.core.Element.addListener
Combining Options
Using the options argument, it is possible to combine different types of listeners:
A delayed, one-time listener.
myPanel.on('hide', this.handleClick, this, {
single: true,
delay: 100
});
Attaching multiple handlers in 1 call
The method also allows for a single argument to be passed which is a config object containing properties
which specify multiple events. For example:
myGridPanel.on({
cellClick: this.onCellClick,
mouseover: this.onMouseOver,
mouseout: this.onMouseOut,
scope: this // Important. Ensure "this" is correct during handler execution
});Adds listeners to any Observable object (or Element) which are automatically removed when this Component is destroyed.
ename parameter was an event name, this
is the handler function.ename parameter was an event name, this
is the scope (this reference) in which the handler function is executed.ename parameter was an event name, this
is the addListener options.this reference) in which the function is executed. Defaults to the Observable firing the event.Developers should subscribe to the Ext.data.Store.update event to have their code notified of commit operations.
id.
To generate a phantom instance with a new id use:var rec = record.copy(); // clone the record
Ext.data.Model.id(rec); // automatically generate a unique sequential idthis reference) in which the handler function is executed.
If omitted, defaults to the object which fired the event.Enables events fired by this Observable to bubble up an owner hierarchy by calling
this.getBubbleTarget() if present. There is no implementation in the Observable base class.
This is commonly used by Ext.Components to bubble events to owner Containers. See Ext.Component.getBubbleTarget. The default implementation in Ext.Component returns the Component's immediate owner. But if a known target is required, this can be overridden to access the required target more quickly.
Example:
Ext.override(Ext.form.Field, {
// Add functionality to Field's initComponent to enable the change event to bubble
initComponent : Ext.Function.createSequence(Ext.form.Field.prototype.initComponent, function() {
this.enableBubble('change');
}),
// We know that we want Field's events to bubble directly to the FormPanel.
getBubbleTarget : function() {
if (!this.formPanel) {
this.formPanel = this.findParentByType('form');
}
return this.formPanel;
}
});
var myForm = new Ext.formPanel({
title: 'User Details',
items: [{
...
}],
listeners: {
change: function() {
// Title goes red if form has been modified.
myForm.header.setStyle('color', 'red');
}
}
});Fires the specified event with the passed parameters (minus the event name).
An event may be set to bubble up an Observable parent hierarchy (See Ext.Component.getBubbleTarget) by calling enableBubble.
Ext.data.Model.PREFIX (defaults to 'ext-record')
Ext.data.Model.AUTO_ID (defaults to 1 initially)
modified
since the load or last commit.MyApp.User = Ext.regModel('User', {
fields: [
{name: 'id', type: 'int'},
{name: 'name', type: 'string'}
]
});
MyApp.User.load(10, {
scope: this,
failure: function(record, operation) {
//do something if the load failed
},
success: function(record, operation) {
//do something if the load succeeded
},
callback: function(record, operation) {
//do something whether the load succeeded or failed
}
});
This makes any event fired on any instance of the passed class also fire a single event through the class allowing for central handling of events on many instances at once.
Usage:
Ext.util.Observable.observe(Ext.data.Connection);
Ext.data.Connection.on('beforerequest', function(con, options) {
console.log('Ajax request made to ' + options.url);
});Developers should subscribe to the Ext.data.Store.update event to have their code notified of reject operations.
this.ename parameter was an event name, this
is the handler function.ename parameter was an event name, this
is the scope (this reference) in which the handler function is executed.queueSuspended parameter, then all
events fired during event suspension will be sent to any listeners now.Marks this Record as dirty. This method
is used interally when adding phantom records to a
writer enabled store.
Marking a record dirty causes the phantom to
be returned by Ext.data.Store.getModifiedRecords where it will
have a create action composed for it during store save
operations.