Touch 1.1.1 Sencha Docs

Ext.data.Model

Hierarchy

Files

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: 'ed@sencha.com'}, 'User');

user.save(); //POST /users

Calling 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.

Available since: 1.1.0

Defined By

Config options

Ext.data.Model
view source
: String
The name of the field treated as this Model's unique id (defaults to 'id'). ...

The name of the field treated as this Model's unique id (defaults to 'id').

Defaults to: 'id'

Available since: 1.1.0

(optional) A config object containing one or more event handlers to be added to this object during initialization. ...

(optional)

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'); }
        }
    }
});

Available since: 1.1.0

The property on this Persistable object that its data is saved to. ...

The property on this Persistable object that its data is saved to. Defaults to 'data' (e.g. all persistable data resides in this.data.)

Defaults to: 'data'

Available since: 1.1.0

Defined By

Properties

Readonly flag - true if this Record has been modified. ...

Readonly flag - true if this Record has been modified.

Defaults to: false

Available since: 1.1.0

Internal flag used to track whether or not the model instance is currently being edited. ...

Internal flag used to track whether or not the model instance is currently being edited. Read-only

Defaults to: false

Available since: 1.1.0

...

Defaults to: /^(?:scope|delay|buffer|single|stopEvent|preventDefault|stopPropagation|normalized|args|delegate|element|vertical|horizontal)$/

Available since: 1.1.0

Ext.data.Model
view source
: Booleanprivate
...

Defaults to: false

Available since: 1.1.0

Ext.data.Model
view source
: Stringprivate

An internal unique ID for each Model instance, used to identify Models that don't have an ID yet

An internal unique ID for each Model instance, used to identify Models that don't have an ID yet

Available since: 1.1.0

Ext.data.Model
view source
: Booleanprivate
...

Defaults to: true

Available since: 1.1.0

...

Defaults to: true

Available since: 1.1.0

Key: value pairs of all fields whose values have changed ...

Key: value pairs of all fields whose values have changed

Defaults to: {}

Available since: 1.1.0

Ext.data.Model
view source
: Boolean
true when the record does not yet exist in a server-side database (see setDirty). ...

true when the record does not yet exist in a server-side database (see setDirty). Any record which has a real database pk set as its id property is NOT a phantom -- it's real.

Defaults to: false

Available since: 1.1.0

The Ext.data.Store to which this Record belongs.

The Ext.data.Store to which this Record belongs.

Available since: 1.1.0

Methods

Defined By

Instance methods

Ext.data.Model
view source
new( data, id ) : Ext.data.Model
...

Available since: 1.1.0

Parameters

  • data : Object

    An object containing keys corresponding to this model's fields, and their associated values

  • id : Number

    Optional unique ID to assign to this model instance

Returns

Overrides: Ext.util.Stateful.constructor

Adds the specified events to the list of events which this Observable may fire. ...

Adds the specified events to the list of events which this Observable may fire.

Available since: 1.1.0

Parameters

  • o : Object|String

    Either an object with event names as properties with a value of true or the first event name string if multiple event names are being passed as separate parameters.

  • Optional : string

    . Event name if multiple event names are being passed as separate parameters. Usage:

    this.addEvents('storeloaded', 'storecleared');
    
( eventName, handler, [scope], [options] )
Appends an event handler to this object. ...

Appends an event handler to this object.

Available since: 1.1.0

Parameters

  • eventName : String

    The name of the event to listen for. May also be an object who's property names are event names. See

  • handler : Function

    The method the event invokes.

  • scope : Object (optional)

    The scope (this reference) in which the handler function is executed. If omitted, defaults to the object which fired the event.

  • options : Object (optional)

    An object containing handler configuration. properties. This may contain any of the following properties:

    • scope : Object
      The scope (this reference) in which the handler function is executed. If omitted, defaults to the object which fired the event.
    • delay : Number
      The number of milliseconds to delay the invocation of the handler after the event fires.
    • single : Boolean
      True to add a handler to handle just the next firing of the event, and then remove itself.
    • buffer : Number
      Causes the handler to be scheduled to run in an Ext.util.DelayedTask delayed by the specified number of milliseconds. If the event fires again within that time, the original handler is not invoked, but the new handler is scheduled in its place.
    • target : Observable
      Only call the handler if the event was fired on the target Observable, not if the event was bubbled up from a child Observable.
    • element : String
      This option is only valid for listeners bound to Components. The name of a Component property which references an element to add a listener to.

    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.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
    });
    
    .

Fires

    Adds listeners to any Observable object (or Element) which are automatically removed when this Component is destroyed. ...

    Adds listeners to any Observable object (or Element) which are automatically removed when this Component is destroyed.

    Available since: 1.1.0

    Parameters

    • item : Observable|Element

      The item to which to add a listener/listeners.

    • ename : Object|String

      The event name, or an object containing event name properties.

    • fn : Function

      Optional. If the ename parameter was an event name, this is the handler function.

    • scope : Object

      Optional. If the ename parameter was an event name, this is the scope (this reference) in which the handler function is executed.

    • opt : Object

      Optional. If the ename parameter was an event name, this is the addListener options.

    Fires

      Ext.data.Model
      view source
      ( )private
      If this Model instance has been joined to a store, the store's afterCommit method is called ...

      If this Model instance has been joined to a store, the store's afterCommit method is called

      Available since: 1.1.0

      Fires

        Ext.data.Model
        view source
        ( )private
        If this Model instance has been joined to a store, the store's afterEdit method is called ...

        If this Model instance has been joined to a store, the store's afterEdit method is called

        Available since: 1.1.0

        Fires

          Ext.data.Model
          view source
          ( )private
          If this Model instance has been joined to a store, the store's afterReject method is called ...

          If this Model instance has been joined to a store, the store's afterReject method is called

          Available since: 1.1.0

          Fires

            Ext.data.Model
            view source
            ( fn )private
            Helper function used by afterEdit, afterReject and afterCommit. ...

            Helper function used by afterEdit, afterReject and afterCommit. Calls the given method on the store that this instance has joined, if any. The store function will always be called with the model instance as its single argument.

            Available since: 1.1.0

            Parameters

            • fn : String

              The function to call on the store

            Removes all listeners for this object including the managed listeners ...

            Removes all listeners for this object including the managed listeners

            Available since: 1.1.0

            Fires

              Removes all managed listeners for this object. ...

              Removes all managed listeners for this object.

              Available since: 1.1.0

              Usually called by the Ext.data.Store which owns the model instance. ...

              Usually called by the 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 Ext.data.Store.update event to have their code notified of commit operations.

              Available since: 1.1.0

              Parameters

              • silent : Boolean (optional)

                True to skip notification of the owning store of the change (defaults to false)

              Fires

                Creates a copy (clone) of this Model instance. ...

                Creates a copy (clone) of this Model instance.

                Available since: 1.1.0

                Parameters

                • id : String (optional)

                  A new id, defaults to the id of the instance being copied. See 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
                  

                Returns

                • Record
                Enables events fired by this Observable to bubble up an owner hierarchy by calling this.getBubbleTarget() if present. ...

                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.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');
                    }
                }
                });
                

                Available since: 1.1.0

                Parameters

                • events : String/Array

                  The event name to bubble, or an Array of event names.

                ( eventName, args ) : Boolean
                Fires the specified event with the passed parameters (minus the event name). ...

                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.

                Available since: 1.1.0

                Parameters

                • eventName : String

                  The name of the event to fire.

                • args : Object...

                  Variable number of parameters are passed to handlers.

                Returns

                • Boolean

                  returns false if any of the handlers return false otherwise it returns true.

                Fires

                  ( fieldName ) : Mixed
                  Returns the value of the given field ...

                  Returns the value of the given field

                  Available since: 1.1.0

                  Parameters

                  • fieldName : String

                    The field to fetch the value for

                  Returns

                  • Mixed

                    The value

                  Gets a hash of only the fields that have been modified since this Model was created or commited. ...

                  Gets a hash of only the fields that have been modified since this Model was created or commited.

                  Available since: 1.1.0

                  Returns

                  • Object

                    Object

                  Ext.data.Model
                  view source
                  ( ) : Number
                  Returns the unique ID allocated to this model instance as defined by idProperty ...

                  Returns the unique ID allocated to this model instance as defined by idProperty

                  Available since: 1.1.0

                  Returns

                  • Number

                    The id

                  Fires

                    Returns the configured Proxy for this Model ...

                    Returns the configured Proxy for this Model

                    Available since: 1.1.0

                    Returns

                    Checks to see if this object has any listeners for a specified event ...

                    Checks to see if this object has any listeners for a specified event

                    Available since: 1.1.0

                    Parameters

                    • eventName : String

                      The name of the event to check for

                    Returns

                    • Boolean

                      True if the event is being listened for, else false

                    Ext.data.Model
                    view source
                    ( rec ) : String
                    Generates a sequential id. ...

                    Generates a sequential id. This method is typically called when a record is created and no id has been specified. The returned id takes the form: {PREFIX}-{AUTO_ID}.

                    • PREFIX : String

                      Ext.data.Model.PREFIX (defaults to 'ext-record')

                    • AUTO_ID : String

                      Ext.data.Model.AUTO_ID (defaults to 1 initially)

                    Available since: 1.1.0

                    Parameters

                    • rec : Record

                      The record being created. The record does not exist, it's a phantom.

                    Returns

                    • String

                      auto-generated string id, "ext-record-i++';

                    Returns true if the passed field name has been modified since the load or last commit. ...

                    Returns true if the passed field name has been modified since the load or last commit.

                    Available since: 1.1.0

                    Parameters

                    Returns

                    • Boolean
                    Ext.data.Model
                    view source
                    ( store )
                    Tells this model instance that it has been added to a store ...

                    Tells this model instance that it has been added to a store

                    Available since: 1.1.0

                    Parameters

                    ...

                    Available since: 1.1.0

                    ( eventName, handler, [scope], [options] )
                    Appends an event handler to this object (shorthand for addListener.) ...

                    Appends an event handler to this object (shorthand for addListener.)

                    Available since: 1.1.0

                    Parameters

                    • eventName : String

                      The type of event to listen for

                    • handler : Function

                      The method the event invokes

                    • scope : Object (optional)

                      The scope (this reference) in which the handler function is executed. If omitted, defaults to the object which fired the event.

                    • options : Object (optional)

                      An object containing handler configuration.

                    ...

                    Available since: 1.1.0

                    ...

                    Available since: 1.1.0

                    Usually called by the Ext.data.Store to which this model instance has been joined. ...

                    Usually called by the Ext.data.Store to which this model instance has been joined. Rejects all changes made to the model instance since either creation, or the last commit operation. Modified fields are reverted to their original values.

                    Developers should subscribe to the Ext.data.Store.update event to have their code notified of reject operations.

                    Available since: 1.1.0

                    Parameters

                    • silent : Boolean (optional)

                      True to skip notification of the owning store of the change (defaults to false)

                    Fires

                      Relays selected events from the specified Observable as if the events were fired by this. ...

                      Relays selected events from the specified Observable as if the events were fired by this.

                      Available since: 1.1.0

                      Parameters

                      • o : Object

                        The Observable whose events this object is to relay.

                      • events : Array

                        Array of event names to relay.

                      ( eventName, handler, [scope] )
                      Removes an event handler. ...

                      Removes an event handler.

                      Available since: 1.1.0

                      Parameters

                      • eventName : String

                        The type of event the handler was associated with.

                      • handler : Function

                        The handler to remove. This must be a reference to the function passed into the addListener call.

                      • scope : Object (optional)

                        The scope originally specified for the handler.

                      Fires

                        Removes listeners that were added by the mon method. ...

                        Removes listeners that were added by the mon method.

                        Available since: 1.1.0

                        Parameters

                        • item : Observable|Element

                          The item from which to remove a listener/listeners.

                        • ename : Object|String

                          The event name, or an object containing event name properties.

                        • fn : Function

                          Optional. If the ename parameter was an event name, this is the handler function.

                        • scope : Object

                          Optional. If the ename parameter was an event name, this is the scope (this reference) in which the handler function is executed.

                        Fires

                          Resume firing events. ...

                          Resume firing events. (see suspendEvents) If events were suspended using the queueSuspended parameter, then all events fired during event suspension will be sent to any listeners now.

                          Available since: 1.1.0

                          Ext.data.Model
                          view source
                          ( options ) : Ext.data.Model
                          Saves the model instance using the configured proxy ...

                          Saves the model instance using the configured proxy

                          Available since: 1.1.0

                          Parameters

                          • options : Object

                            Options to pass to the proxy

                          Returns

                          Fires

                            Sets the given field to the given value, marks the instance as dirty ...

                            Sets the given field to the given value, marks the instance as dirty

                            Available since: 1.1.0

                            Parameters

                            • fieldName : String|Object

                              The field to set, or an object containing key/value pairs

                            • value : Mixed

                              The value to set

                            Fires

                              Marks this Record as dirty. ...

                              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.

                              Available since: 1.1.0

                              Ext.data.Model
                              view source
                              ( id )
                              Sets the model instance's id field to the given id ...

                              Sets the model instance's id field to the given id

                              Available since: 1.1.0

                              Parameters

                              • id : Number

                                The new id

                              Fires

                                Ext.data.Model
                                view source
                                ( proxy )
                                Sets the Proxy to use for this model. ...

                                Sets the Proxy to use for this model. Accepts any options that can be accepted by Ext.data.ProxyMgr.create

                                Available since: 1.1.0

                                Parameters

                                Suspend the firing of all events. ...

                                Suspend the firing of all events. (see resumeEvents)

                                Available since: 1.1.0

                                Parameters

                                • queueSuspended : Boolean

                                  Pass as true to queue up suspended events to be fired after the resumeEvents call instead of discarding all suspended events;

                                ( eventName, handler, [scope] )
                                Removes an event handler (shorthand for removeListener.) ...

                                Removes an event handler (shorthand for removeListener.)

                                Available since: 1.1.0

                                Parameters

                                • eventName : String

                                  The type of event the handler was associated with.

                                • handler : Function

                                  The handler to remove. This must be a reference to the function passed into the addListener call.

                                • scope : Object (optional)

                                  The scope originally specified for the handler.

                                Ext.data.Model
                                view source
                                ( store )
                                Tells this model instance that it has been removed from the store ...

                                Tells this model instance that it has been removed from the store

                                Available since: 1.1.0

                                Parameters

                                Validates the current data against all of its configured validations and returns an Errors object ...

                                Validates the current data against all of its configured validations and returns an Errors object

                                Available since: 1.1.0

                                Returns

                                Fires

                                  Defined By

                                  Static methods

                                  Ext.data.Model
                                  view source
                                  ( id, config )static
                                  Static. ...

                                  Static. Asynchronously loads a model instance by id. Sample usage:

                                  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
                                      }
                                  });
                                  

                                  Available since: 1.1.0

                                  Parameters

                                  • id : Number

                                    The id of the model to load

                                  • config : Object

                                    Optional config object containing success, failure and callback functions, plus optional scope