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 {@link Ext.ModelManager model manager}, + * and are used by {@link Ext.data.Store 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.define('User', {
+ extend: 'Ext.data.Model',
+ 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 {@link Ext.util.MixedCollection MixedCollection} automatically by the {@link Ext.ModelManager ModelManager}, 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.ModelManager.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 + * {@link Ext.data.validations} ({@link Ext.data.validations see all validation functions}). Validations are easy to add to models:
+ * +
+Ext.define('User', {
+ extend: 'Ext.data.Model',
+ 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 {@link #validate} function, which returns a {@link Ext.data.Errors} + * object:
+ * +
+var instance = Ext.ModelManager.create({
+ name: 'Ed',
+ gender: 'Male',
+ username: 'edspencer'
+}, 'User');
+
+var errors = instance.validate();
+Associations
+ * + *Models can have associations with other Models via {@link Ext.data.BelongsToAssociation belongsTo} and + * {@link Ext.data.HasManyAssociation 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.define('Post', {
+ extend: 'Ext.data.Model',
+ fields: ['id', 'user_id'],
+
+ belongsTo: 'User',
+ hasMany : {model: 'Comment', name: 'comments'}
+});
+
+Ext.define('Comment', {
+ extend: 'Ext.data.Model',
+ fields: ['id', 'user_id', 'post_id'],
+
+ belongsTo: 'Post'
+});
+
+Ext.define('User', {
+ extend: 'Ext.data.Model',
+ fields: ['id'],
+
+ hasMany: [
+ 'Post',
+ {model: 'Comment', name: 'comments'}
+ ]
+});
+See the docs for {@link Ext.data.BelongsToAssociation} and {@link Ext.data.HasManyAssociation} for details on the usage + * and configuration of associations. Note that associations can also be specified like this:
+ * +
+Ext.define('User', {
+ extend: 'Ext.data.Model',
+ 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 {@link Ext.data.proxy.Proxy Proxy}, + * which can be set directly on the Model:
+ * +
+Ext.define('User', {
+ extend: 'Ext.data.Model',
+ fields: ['id', 'name', 'email'],
+
+ proxy: {
+ type: 'rest',
+ url : '/users'
+ }
+});
+Here we've set up a {@link Ext.data.proxy.Rest 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.ModelManager.create({name: 'Ed Spencer', email: 'ed@sencha.com'}, 'User');
+
+user.save(); //POST /users
+Calling {@link #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 {@link Ext.data.proxy.Proxy} for a full + * list.
+ * + *Loading data via the Proxy is equally easy:
+ * +
+//get a reference to the User model class
+var User = Ext.ModelManager.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 {@link Ext.data.Store 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 + * {@link Ext.data.Store Store docs} for more information on Stores.
+ * + * @constructor + * @param {Object} data An object containing keys corresponding to this model's fields, and their associated values + * @param {Number} id Optional unique ID to assign to this model instance + */ +Ext.define('Ext.data.Model', { + alternateClassName: 'Ext.data.Record', + + mixins: { + observable: 'Ext.util.Observable' + }, + + requires: [ + 'Ext.ModelManager', + 'Ext.data.Field', + 'Ext.data.Errors', + 'Ext.data.Operation', + 'Ext.data.validations', + 'Ext.data.proxy.Ajax', + 'Ext.util.MixedCollection' + ], + + onClassExtended: function(cls, data) { + var onBeforeClassCreated = data.onBeforeClassCreated; + + data.onBeforeClassCreated = function(cls, data) { + var me = this, + name = Ext.getClassName(cls), + prototype = cls.prototype, + superCls = cls.prototype.superclass, + + validations = data.validations || [], + fields = data.fields || [], + associations = data.associations || [], + belongsTo = data.belongsTo, + hasMany = data.hasMany, + + fieldsMixedCollection = new Ext.util.MixedCollection(false, function(field) { + return field.name; + }), + + associationsMixedCollection = new Ext.util.MixedCollection(false, function(association) { + return association.name; + }), + + superValidations = superCls.validations, + superFields = superCls.fields, + superAssociations = superCls.associations, + + association, i, ln, + dependencies = []; + + // Save modelName on class and its prototype + cls.modelName = name; + prototype.modelName = name; + + // Merge the validations of the superclass and the new subclass + if (superValidations) { + validations = superValidations.concat(validations); + } + + data.validations = validations; + + // Merge the fields of the superclass and the new subclass + if (superFields) { + fields = superFields.items.concat(fields); + } + + for (i = 0, ln = fields.length; i < ln; ++i) { + fieldsMixedCollection.add(new Ext.data.Field(fields[i])); + } + + data.fields = fieldsMixedCollection; + + //associations can be specified in the more convenient format (e.g. not inside an 'associations' array). + //we support that here + if (belongsTo) { + belongsTo = Ext.Array.from(belongsTo); + + for (i = 0, ln = belongsTo.length; i < ln; ++i) { + association = belongsTo[i]; + + if (!Ext.isObject(association)) { + association = {model: association}; + } + + association.type = 'belongsTo'; + associations.push(association); + } + + delete data.belongsTo; + } + + if (hasMany) { + hasMany = Ext.Array.from(hasMany); + for (i = 0, ln = hasMany.length; i < ln; ++i) { + association = hasMany[i]; + + if (!Ext.isObject(association)) { + association = {model: association}; + } + + association.type = 'hasMany'; + associations.push(association); + } + + delete data.hasMany; + } + + if (superAssociations) { + associations = superAssociations.items.concat(associations); + } + + for (i = 0, ln = associations.length; i < ln; ++i) { + dependencies.push('association.' + associations[i].type.toLowerCase()); + } + + if (data.proxy) { + if (typeof data.proxy === 'string') { + dependencies.push('proxy.' + data.proxy); + } + else if (typeof data.proxy.type === 'string') { + dependencies.push('proxy.' + data.proxy.type); + } + } + + Ext.require(dependencies, function() { + Ext.ModelManager.registerType(name, cls); + + for (i = 0, ln = associations.length; i < ln; ++i) { + association = associations[i]; + + Ext.apply(association, { + ownerModel: name, + associatedModel: association.model + }); + + if (Ext.ModelManager.getModel(association.model) === undefined) { + Ext.ModelManager.registerDeferredAssociation(association); + } else { + associationsMixedCollection.add(Ext.data.Association.create(association)); + } + } + + data.associations = associationsMixedCollection; + + onBeforeClassCreated.call(me, cls, data); + + cls.setProxy(cls.prototype.proxy || cls.prototype.defaultProxyType); + + // Fire the onModelDefined template method on ModelManager + Ext.ModelManager.onModelDefined(cls); + }); + } + }, + + inheritableStatics: { + /** + * Sets the Proxy to use for this model. Accepts any options that can be accepted by {@link Ext#createByAlias Ext.createByAlias} + * @param {String/Object/Ext.data.proxy.Proxy} proxy The proxy + * @static + */ + setProxy: function(proxy) { + //make sure we have an Ext.data.proxy.Proxy object + if (!proxy.isProxy) { + if (typeof proxy == "string") { + proxy = { + type: proxy + }; + } + proxy = Ext.createByAlias("proxy." + proxy.type, proxy); + } + proxy.setModel(this); + this.proxy = this.prototype.proxy = proxy; + + return proxy; + }, + + /** + * Returns the configured Proxy for this Model + * @return {Ext.data.proxy.Proxy} The proxy + */ + getProxy: function() { + return this.proxy; + }, + + /** + * Static. Asynchronously loads a model instance by id. Sample usage: +
+ MyApp.User = Ext.define('User', {
+ extend: 'Ext.data.Model',
+ 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
+ }
+ });
+ Ext.data.Model.PREFIX + * (defaults to 'ext-record')
Ext.data.Model.AUTO_ID + * (defaults to 1 initially)
update event)
+ * are relayed to the containing store. When an edit has begun, it must be followed
+ * by either {@link #endEdit} or {@link #cancelEdit}.
+ */
+ beginEdit : function(){
+ var me = this;
+ if (!me.editing) {
+ me.editing = true;
+ me.dirtySave = me.dirty;
+ me.dataSave = Ext.apply({}, me[me.persistanceProperty]);
+ me.modifiedSave = Ext.apply({}, me.modified);
+ }
+ },
+
+ /**
+ * Cancels all changes made in the current edit operation.
+ */
+ cancelEdit : function(){
+ var me = this;
+ if (me.editing) {
+ me.editing = false;
+ // reset the modified state, nothing changed since the edit began
+ me.modified = me.modifiedSave;
+ me[me.persistanceProperty] = me.dataSave;
+ me.dirty = me.dirtySave;
+ delete me.modifiedSave;
+ delete me.dataSave;
+ delete me.dirtySave;
+ }
+ },
+
+ /**
+ * End an edit. If any data was modified, the containing store is notified
+ * (ie, the store's update event will fire).
+ * @param {Boolean} silent True to not notify the store of the change
+ */
+ endEdit : function(silent){
+ var me = this;
+ if (me.editing) {
+ me.editing = false;
+ delete me.modifiedSave;
+ delete me.dataSave;
+ delete me.dirtySave;
+ if (silent !== true && me.dirty) {
+ me.afterEdit();
+ }
+ }
+ },
+
+ /**
+ * Gets a hash of only the fields that have been modified since this Model was created or commited.
+ * @return Object
+ */
+ getChanges : function(){
+ var modified = this.modified,
+ changes = {},
+ field;
+
+ for (field in modified) {
+ if (modified.hasOwnProperty(field)){
+ changes[field] = this.get(field);
+ }
+ }
+
+ return changes;
+ },
+
+ /**
+ * Returns true if the passed field name has been {@link #modified}
+ * since the load or last commit.
+ * @param {String} fieldName {@link Ext.data.Field#name}
+ * @return {Boolean}
+ */
+ isModified : function(fieldName) {
+ return this.modified.hasOwnProperty(fieldName);
+ },
+
+ /**
+ * Marks this Record as {@link #dirty}. This method
+ * is used interally when adding {@link #phantom} records to a
+ * {@link Ext.data.Store#writer writer enabled store}.
Marking a record {@link #dirty} causes the phantom to
+ * be returned by {@link Ext.data.Store#getModifiedRecords} where it will
+ * have a create action composed for it during {@link Ext.data.Store#save store save}
+ * operations.
Developers should subscribe to the {@link Ext.data.Store#update} event + * to have their code notified of reject operations.
+ * @param {Boolean} silent (optional) True to skip notification of the owning + * store of the change (defaults to false) + */ + reject : function(silent) { + var me = this, + modified = me.modified, + field; + + for (field in modified) { + if (modified.hasOwnProperty(field)) { + if (typeof modified[field] != "function") { + me[me.persistanceProperty][field] = modified[field]; + } + } + } + + me.dirty = false; + me.editing = false; + me.modified = {}; + + if (silent !== true) { + me.afterReject(); + } + }, + + /** + * Usually called by the {@link Ext.data.Store} which owns the model instance. + * Commits all changes made to the instance since either creation or the last commit operation. + *Developers should subscribe to the {@link Ext.data.Store#update} event + * to have their code notified of commit operations.
+ * @param {Boolean} silent (optional) True to skip notification of the owning + * store of the change (defaults to false) + */ + commit : function(silent) { + var me = this; + + me.dirty = false; + me.editing = false; + + me.modified = {}; + + if (silent !== true) { + me.afterCommit(); + } + }, + + /** + * Creates a copy (clone) of this Model instance. + * @param {String} id (optional) A new id, defaults to the id + * of the instance being copied. See{@link #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 id
+ *