allowNull : Boolean

Use when converting received data into a Ext.data.field.Integer, Ext.data.field.Number, Ext.data.field.Boolean or Ext.data.field.String type. If the value cannot be parsed, null will be used if allowNull is true, otherwise a default value for that type will be used:

• for int and float - 0.
• for string - "".
• for bool - false.

Note that when parsing of Ext.data.field.Date type fails, the value will be null regardless of this setting.

Defaults to:

false

calculate : Function

This config defines a simple field calculation function. A calculate method only has access to the record data and should return the value of the calculated field. When provided in this way, the depends config is automatically determined by parsing the calculate function. For example:

 fields: [{
     name: 'firstName',
     type: 'string'
 },{
     name: 'lastName',
     type: 'string'
 },{
     name: 'fullName',
     calculate: function (data) {
         return data.firstName + ' ' + data.lastName;
     }
 }]

The above 'fullName' field is equivalent to:

 {
     name: 'fullName',
     convert: function (v, rec) {
         return rec.get('firstName') + ' ' + rec.get('lastName');
     },
     depends: ['firstName', 'lastName']
 }

The restrictions on form for a calculate method are that the accesses to field values must match the following regular expression (case insensitive):

 data.([a-z_][a-z0-9_]*)
 // where 'data' is the param passed to the calculate method

The only advantage of a calculate method over a convert method is automatic determination of depends.

Note: The use of calculate and convert are exclusive. The calculate method will override the convert method if both are configured.

Parameters

Returns

convert : Function

If specified this config overrides the convert method. See also calculate for simple field calculations.

Note: The use of calculate and convert are exclusive. The calculate method will override the convert method if both are configured.

critical : Boolean

A critical field is a field that must always be sent to the server even if it has not changed. The most common example of such a field is the "id" of a record (see Ext.data.Model#idProperty but the Ext.data.Model#versionProperty is similarly a critical field.

Defaults to:

false

defaultValue : Object

The default value used when the creating an instance from a raw data object, and the property referenced by the mapping does not exist in that data object.

The value undefined prevents defaulting in a value.

Defaults to:

undefined

depends : String / String[]

The field name or names within the Ext.data.Model on which the value of this field depends, and from which a new value may be calculated. These values are the values used by the convert method. If you do not have a convert method then this config should not be specified.

Before using this config you should consider if using a calculate method instead of a convert method would be simpler.

Whenever any of the named fields are set using the set method, this fields will have its convert method called passing the Ext.data.Model so that the dependent value can be calculated from all fields which it needs.

For example, to display a person's full name, using two separate firstName and lastName fields, configure the name field like this:

{
    name: 'name',

    // Will be called whenever forename or surname fields are set
    convert: function (v, rec) {
        return rec.get('firstName') + ' ' + rec.get('lastName');
    },

    depends: [ 'firstName', 'lastName' ],

    // It should not be returned to the server - it's not a database field
    persist: false
}

Note that if you do not want the calculated field to be part of the field set sent back to the server when the store is synchronized, you should configure the field with persist set to false.

Defaults to:

null

mapping : String / Number / Function

(Optional) A path expression for use by the Ext.data.reader.Reader implementation that is creating the Ext.data.Model to extract the Field value from the data object. If the path expression is the same as the field name, the mapping may be omitted. A function may be passed to do complex data extraction. The examples below are simple just to demonstrate the capability, typically, a function would not be used to extract such simple data.

The form of the mapping expression depends on the Reader being used.

• Ext.data.reader.Json

  The mapping is a string containing the javascript expression to reference the data from an element of the data item's rootProperty Array. Defaults to the field name. If a function is passed, a single argument is received which contains the raw json object:

  // Server returns [{"name": "Foo", "age": 1}, {"name": "Bar", "age": 2}]
  mapping: function(data) {
      return data.name;
  }
  

• Ext.data.reader.Xml

  The mapping is an Ext.DomQuery path to the data item relative to the DOM element that represents the record. Defaults to the field name. If a function is passed, a single argument is received which contains the record node:

  // Server returns <Root><Person><Name>Foo</Name><Age>1</Age></Person><Person><Name>Bar</Name><Age>2</Age></Person></Root>
  mapping: function(data) {
      return data.firstChild.textContent;
  }
  

• Ext.data.reader.Array

  The mapping is a number indicating the Array index of the field's value. Defaults to the field specification's Array position. If a function is passed, a single argument is received which contains the child array.

  // Server returns [["Foo", 1], ["Bar", 2]]
  mapping: function(data) {
      return data[0];
  }
  

If a more complex value extraction strategy is required, then configure the Field with a cfg-convert function. This is passed the whole row object, and may interrogate it in whatever way is necessary in order to return the desired data.

Defaults to:

null

name : String

The name by which the field is referenced within the Model. This is referenced by, for example, the dataIndex property in column definition objects passed to Ext.grid.property.HeaderContainer.

Note: In the simplest case, if no properties other than name are required, a field definition may consist of just a String for the field name.

Defaults to:

null

persist : Boolean

False to exclude this field from the Ext.data.Model#modified fields in a record. This will also exclude the field from being written using a Ext.data.writer.Writer. This option is useful when fields are used to keep state on the client but do not need to be persisted to the server.

Defaults to false for calculated fields and true otherwise.

Defaults to:

null

reference : String / Object

The name of the entity referenced by this field. In most databases, this relationship is represented by a "foreign key". That is, a value for such a field matches the value of the id for an entity of this type.

 Ext.define('MyApp.models.Organization', {
     extend: 'Ext.data.Model',
     ...
 });

 Ext.define('MyApp.models.User', {
     extend: 'Ext.data.Model',

     fields: [
         { name: 'organizationId', reference: 'Organization' }
     ],
     ...
 });

If a reference is not nullable, set the Ext.data.field.Field#allowBlank property to false.

 Ext.define('MyApp.models.User', {
     extend: 'Ext.data.Model',

     fields: [
         { name: 'organizationId', reference: 'Organization', allowBlank: false }
     ],
     ...
 });

If the name of the generated Ext.data.schema.Association or other aspects need to be specified, the reference can be an object. The following usage shows what would be generated by default given the above examples using the string form.

 Ext.define('MyApp.models.User', {
     extend: 'Ext.data.Model',

     fields: [{
         name: 'organizationId',
         reference: {
             type: 'Organization',
             association: 'UsersByOrganization',
             role: 'organization',
             inverse: 'users'
         }
     }],
     ...
 });

Finally, a reference can also describe ownership between the entities. By default, no ownership relationship is assumed. If, however, the User entities are owned by their Organization, we could say this:

 Ext.define('MyApp.models.User', {
     extend: 'Ext.data.Model',

     fields: [{
         name: 'organizationId',
         reference: {
             parent: 'Organization' // Organization is the parent of User
         }
     }],
     ...
 });

Defaults to:

null

Properties

type : String

The type which this field references. This is the value set by the string form of reference. If the referenced entity has an ownership relationship this field should be omitted and reference.parent or reference.child should be specified instead.

association : String

The name of the association. By default, the name of the association is the capitalized inverse plus "By" plus the capitalized role.

child : String

Set this property instead of reference.type to indicate that the referenced entity is an owned child of this entity. That is, the reference entity should be deleted when this entity is deleted.

parent : String

Set this property instead of reference.type to indicate that the referenced entity is the owning parent of this entity. That is, this entity should be deleted when the reference entity is deleted.

role : String

The name of the role played by the referenced entity. By default, this is the field name (minus its "Id" suffix if present).

inverse : String/Object

The name of the inverse role (of this entity with respect to the reference entity). By default, this is the pluralized name of this entity, unless this reference is unique, in which case the default name is the singularized name of this entity.

This config may also be an object containing a role, getter, or setter.

serialize : Function

sortType : Function / String

A function which converts a Field's value to a comparable value in order to ensure correct sort ordering.

Predefined functions are provided in Ext.data.SortTypes. A custom sort example:

// current sort     after sort we want
// +-+------+          +-+------+
// |1|First |          |1|First |
// |2|Last  |          |3|Second|
// |3|Second|          |2|Last  |
// +-+------+          +-+------+

sortType: function(value) {
   switch (value.toLowerCase()) // native toLowerCase():
   {
      case 'first': return 1;
      case 'second': return 2;
      default: return 3;
   }
}

May also be set to a String value, corresponding to one of the named sort types in Ext.data.SortTypes.

unique : Boolean

true if the value of this field is unique amongst all instances. When used with a reference this describes a "one-to-one" relationship. It is almost always the case that a unique field cannot also be nullable.

Defaults to:

false

validators : Object[]

An array of Ext.data.validator.Validator for this field. These validators will only be passed a field value to validate.

calculated : Boolean

readonly ro

This property is true if this field has a calculate method or a convert method that operates on the entire record as opposed to just the data value. This property is determined from the length of the convert function which means this is not calculated:

 convert: function (value) {
     return ...
 }

While this is calculated:

 convert: function (value, record) {
     return ...
 }

NOTE: It is recommended for such fields to use calculate or explicitly specify the fields used by convert using depends.

Defaults to:

false

defaultInvalidMessage : String

The default message to present for an invalid field.

Defaults to:

'This field is invalid'

Available since: 5.0.0

definedBy : Ext.Class

The class (derived from Ext.data.Model) that defined this field.

 Ext.define('MyApp.models.Foo', {
     extend: 'Ext.data.Model',

     fields: [
         { name: 'bar' }
     ],
     ...
 });

 var barField = MyApp.models.Foo.getField('bar');

 alert(barField.definedBy === MyApp.models.Foo); // alerts 'true'

When a field is inherited, this value will reference the class that originally defined the field.

 Ext.define('MyApp.models.Base', {
     extend: 'Ext.data.Model',

     fields: [
         { name: 'foo' }
     ],
     ...
 });

 Ext.define('MyApp.models.Derived', {
     extend: 'MyApp.models.Base',

     fields: [
         { name: 'bar' }
     ],
     ...
 });

 var fooField = MyApp.models.Derived.getField('foo');

 alert(fooField.definedBy === MyApp.models.Base); // alerts 'true'

Defaults to:

null

identifier : Boolean

readonly ro

This property is set to true if this is an id field.

Defaults to:

false

ordinal : Number

The position of this field in the Ext.data.Model in which it was defined.

Defaults to:

undefined

collate ( value1, value2 ) : Number

Compares two values to retrieve their relative position in sort order, taking into account any sortType. Also see compare.

Parameters

Returns

compare ( value1, value2 ) : Number

Compares two values to retrieve their relative position in sort order. Also see collate.

Parameters

Returns

convert ( value, record ) : Mixed

A function which converts the value provided by the Reader into the value that will be stored in the record. This method can be overridden by a derived class or set as a convert config.

If configured as null, then no conversion will be applied to the raw data property when this Field is read. This will increase performance. but you must ensure that the data is of the correct type and does not need converting.

Example of convert functions:

function fullName(v, record){
    return record.data.last + ', ' + record.data.first;
}

function location(v, record){
    return !record.data.city ? '' : (record.data.city + ', ' + record.data.state);
}

Ext.define('Dude', {
    extend: 'Ext.data.Model',
    fields: [
        {name: 'fullname',  convert: fullName},
        {name: 'firstname', mapping: 'name.first'},
        {name: 'lastname',  mapping: 'name.last'},
        {name: 'city', defaultValue: 'unknown'},
        'state',
        {name: 'location',  convert: location}
    ]
});

// create the data store
var store = Ext.create('Ext.data.Store', {
    model: 'Dude',
    proxy: {
        type: 'memory',
        reader: {
            type: 'json',
            rootProperty: 'daRoot',
            totalProperty: 'total'
        }
    }
});

var myData = [
    { key: 1,
      name: { first: 'Fat',    last:  'Albert' }
      // notice no city, state provided in data object
    },
    { key: 2,
      name: { first: 'Barney', last:  'Rubble' },
      city: 'Bedrock', state: 'Stoneridge'
    },
    { key: 3,
      name: { first: 'Cliff',  last:  'Claven' },
      city: 'Boston',  state: 'MA'
    }
];

Parameters

Returns

getAllowBlank

getAllowNull

getConvert

getDefaultValue

getDepends

getMapping

getName

getPersist

getSortType

getType String

Gets a string representation of the type of this field.

Returns

hasMapping Boolean

Checks if this field has a mapping applied.

Returns

isEqual ( value1, value2 ) : Boolean

Tests whether two values are equal based on this field type. This uses the compare method to determine equality, so this method should generally not be overridden.

Parameters

Returns

serialize ( value, record ) : String

A function which converts the Model's value for this Field into a form which can be used by whatever Ext.data.writer.Writer is being used to sync data with the server.

Parameters

Returns