module Ext_data_Model: sig .. end

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.define('User', {
    extend: 'Ext.data.Model',
    fields: [
        {name: 'name',  type: 'string'},
        {name: 'age',   type: 'int', convert: null},
        {name: 'phone', type: 'string'},
        {name: 'alive', type: 'boolean', defaultValue: true, convert: null}
    ],

    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 ModelManager, and all other functions and properties are copied to the new Model's prototype.

A Model definition always has an identifying field which should yield a unique key for each instance. By default, a field named "id" will be created with a mapping of "id". This happens because of the default idProperty provided in Model definitions.

To alter which field is the identifying field, use the idProperty config.

If the Model should not have any identifying field (for example if you are defining ab abstract base class for your application models), configure the {@liknk idProperty} as null.

By default, the built in numeric and boolean field types have a Ext.data.Field.convert function which coerces string values in raw data into the field's type. For better performance with Json or Array readers if you are in control of the data fed into this Model, you can null out the default convert function which will cause the raw property to be copied directly into the Field's value.

Now we can create instances of our User model and call any model logic we defined:

var user = Ext.create('User', {
    id   : 'ABCD12345',
    name : 'Conan',
    age  : 24,
    phone: '555-555-5555'
});

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.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 validate function, which returns a Ext.data.Errors object:

var instance = Ext.create('User', {
    name: 'Ed',
    gender: 'Male',
    username: 'edspencer'
});

var errors = instance.validate();

Associations

Models can have associations with other Models via Ext.data.association.HasOne, 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.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 Ext.data.association.HasOne, Ext.data.association.BelongsTo and Ext.data.association.HasMany 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 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 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.create('User', {name: 'Ed Spencer', email: 'ed@sencha.com'});

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.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 Store:

var store = Ext.create('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.

class type t = object .. end

class type configs = object .. end

class type events = object .. end

class type statics = object .. end

val get_static : unit -> statics Js.t

val static : statics Js.t

val getFields : unit -> Ext_data_Field.t Js.js_array Js.t

val getProxy : unit -> 'a Js.t

val id : 'a Js.t -> Js.js_string Js.t

val load : 'a Js.t -> 'b Js.t Js.optdef -> unit

val setFields : 'a Js.t -> 'b Js.t -> 'c Js.t -> unit

val setProxy : 'a Js.t -> 'b Js.t

val of_configs : configs Js.t -> t Js.t

val to_configs : t Js.t -> configs Js.t