docs/source/Field.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-form.field.Field'>/**
   2 </span> * @class Ext.form.field.Field
   3
   4 This mixin provides a common interface for the logical behavior and state of form fields, including:
   5
   6 - Getter and setter methods for field values
   7 - Events and methods for tracking value and validity changes
   8 - Methods for triggering validation
   9
  10 **NOTE**: When implementing custom fields, it is most likely that you will want to extend the {@link Ext.form.field.Base}
  11 component class rather than using this mixin directly, as BaseField contains additional logic for generating an
  12 actual DOM complete with {@link Ext.form.Labelable label and error message} display and a form input field,
  13 plus methods that bind the Field value getters and setters to the input field's value.
  14
  15 If you do want to implement this mixin directly and don't want to extend {@link Ext.form.field.Base}, then
  16 you will most likely want to override the following methods with custom implementations: {@link #getValue},
  17 {@link #setValue}, and {@link #getErrors}. Other methods may be overridden as needed but their base
  18 implementations should be sufficient for common cases. You will also need to make sure that {@link #initField}
  19 is called during the component's initialization.
  20
  21  * @markdown
  22  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  23  */
  24 Ext.define('Ext.form.field.Field', {
  25
  26 <span id='Ext-form.field.Field-property-isFormField'>    /**
  27 </span>     * @property isFormField
  28      * @type {Boolean}
  29      * Flag denoting that this component is a Field. Always true.
  30      */
  31     isFormField : true,
  32
  33 <span id='Ext-form.field.Field-cfg-value'>    /**
  34 </span>     * @cfg {Mixed} value A value to initialize this field with (defaults to undefined).
  35      */
  36
  37 <span id='Ext-form.field.Field-cfg-name'>    /**
  38 </span>     * @cfg {String} name The name of the field (defaults to undefined). By default this is used as the parameter
  39      * name when including the {@link #getSubmitData field value} in a {@link Ext.form.Basic#submit form submit()}.
  40      * To prevent the field from being included in the form submit, set {@link #submitValue} to &lt;tt&gt;false&lt;/tt&gt;.
  41      */
  42
  43 <span id='Ext-form.field.Field-cfg-disabled'>    /**
  44 </span>     * @cfg {Boolean} disabled True to disable the field (defaults to false). Disabled Fields will not be
  45      * {@link Ext.form.Basic#submit submitted}.&lt;/p&gt;
  46      */
  47     disabled : false,
  48
  49 <span id='Ext-form.field.Field-cfg-submitValue'>    /**
  50 </span>     * @cfg {Boolean} submitValue Setting this to &lt;tt&gt;false&lt;/tt&gt; will prevent the field from being
  51      * {@link Ext.form.Basic#submit submitted} even when it is not disabled. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
  52      */
  53     submitValue: true,
  54
  55 <span id='Ext-form.field.Field-cfg-validateOnChange'>    /**
  56 </span>     * @cfg {Boolean} validateOnChange
  57      * &lt;p&gt;Specifies whether this field should be validated immediately whenever a change in its value is detected.
  58      * Defaults to &lt;tt&gt;true&lt;/tt&gt;. If the validation results in a change in the field's validity, a
  59      * {@link #validitychange} event will be fired. This allows the field to show feedback about the
  60      * validity of its contents immediately as the user is typing.&lt;/p&gt;
  61      * &lt;p&gt;When set to &lt;tt&gt;false&lt;/tt&gt;, feedback will not be immediate. However the form will still be validated
  62      * before submitting if the &lt;tt&gt;clientValidation&lt;/tt&gt; option to {@link Ext.form.Basic#doAction} is
  63      * enabled, or if the field or form are validated manually.&lt;/p&gt;
  64      * &lt;p&gt;See also {@link Ext.form.field.Base#checkChangeEvents}for controlling how changes to the field's value are detected.&lt;/p&gt;
  65      */
  66     validateOnChange: true,
  67
  68 <span id='Ext-form.field.Field-property-suspendCheckChange'>    /**
  69 </span>     * @private
  70      */
  71     suspendCheckChange: 0,
  72
  73 <span id='Ext-form.field.Field-method-initField'>    /**
  74 </span>     * Initializes this Field mixin on the current instance. Components using this mixin should call
  75      * this method during their own initialization process.
  76      */
  77     initField: function() {
  78         this.addEvents(
  79 <span id='Ext-form.field.Field-event-change'>            /**
  80 </span>             * @event change
  81              * Fires when a user-initiated change is detected in the value of the field.
  82              * @param {Ext.form.field.Field} this
  83              * @param {Mixed} newValue The new value
  84              * @param {Mixed} oldValue The original value
  85              */
  86             'change',
  87 <span id='Ext-form.field.Field-event-validitychange'>            /**
  88 </span>             * @event validitychange
  89              * Fires when a change in the field's validity is detected.
  90              * @param {Ext.form.field.Field} this
  91              * @param {Boolean} isValid Whether or not the field is now valid
  92              */
  93             'validitychange',
  94 <span id='Ext-form.field.Field-event-dirtychange'>            /**
  95 </span>             * @event dirtychange
  96              * Fires when a change in the field's {@link #isDirty} state is detected.
  97              * @param {Ext.form.field.Field} this
  98              * @param {Boolean} isDirty Whether or not the field is now dirty
  99              */
 100             'dirtychange'
 101         );
 102
 103         this.initValue();
 104     },
 105
 106 <span id='Ext-form.field.Field-method-initValue'>    /**
 107 </span>     * @protected
 108      * Initializes the field's value based on the initial config.
 109      */
 110     initValue: function() {
 111         var me = this;
 112
 113 <span id='Ext-form.field.Field-property-originalValue'>        /**
 114 </span>         * @property originalValue
 115          * @type Mixed
 116          * The original value of the field as configured in the {@link #value} configuration, or as loaded by
 117          * the last form load operation if the form's {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
 118          * setting is &lt;code&gt;true&lt;/code&gt;.
 119          */
 120         me.originalValue = me.lastValue = me.value;
 121
 122         // Set the initial value - prevent validation on initial set
 123         me.suspendCheckChange++;
 124         me.setValue(me.value);
 125         me.suspendCheckChange--;
 126     },
 127
 128 <span id='Ext-form.field.Field-method-getName'>    /**
 129 </span>     * Returns the {@link Ext.form.field.Field#name name} attribute of the field. This is used as the parameter
 130      * name when including the field value in a {@link Ext.form.Basic#submit form submit()}.
 131      * @return {String} name The field {@link Ext.form.field.Field#name name}
 132      */
 133     getName: function() {
 134         return this.name;
 135     },
 136
 137 <span id='Ext-form.field.Field-method-getValue'>    /**
 138 </span>     * Returns the current data value of the field. The type of value returned is particular to the type of the
 139      * particular field (e.g. a Date object for {@link Ext.form.field.Date}).
 140      * @return {Mixed} value The field value
 141      */
 142     getValue: function() {
 143         return this.value;
 144     },
 145
 146 <span id='Ext-form.field.Field-method-setValue'>    /**
 147 </span>     * Sets a data value into the field and runs the change detection and validation.
 148      * @param {Mixed} value The value to set
 149      * @return {Ext.form.field.Field} this
 150      */
 151     setValue: function(value) {
 152         var me = this;
 153         me.value = value;
 154         me.checkChange();
 155         return me;
 156     },
 157
 158 <span id='Ext-form.field.Field-method-isEqual'>    /**
 159 </span>     * Returns whether two field {@link #getValue values} are logically equal. Field implementations may override
 160      * this to provide custom comparison logic appropriate for the particular field's data type.
 161      * @param {Mixed} value1 The first value to compare
 162      * @param {Mixed} value2 The second value to compare
 163      * @return {Boolean} True if the values are equal, false if inequal.
 164      */
 165     isEqual: function(value1, value2) {
 166         return String(value1) === String(value2);
 167     },
 168
 169 <span id='Ext-form.field.Field-method-getSubmitData'>    /**
 170 </span>     * &lt;p&gt;Returns the parameter(s) that would be included in a standard form submit for this field. Typically this
 171      * will be an object with a single name-value pair, the name being this field's {@link #getName name} and the
 172      * value being its current stringified value. More advanced field implementations may return more than one
 173      * name-value pair.&lt;/p&gt;
 174      * &lt;p&gt;Note that the values returned from this method are not guaranteed to have been successfully
 175      * {@link #validate validated}.&lt;/p&gt;
 176      * @return {Object} A mapping of submit parameter names to values; each value should be a string, or an array
 177      * of strings if that particular name has multiple values. It can also return &lt;tt&gt;null&lt;/tt&gt; if there are no
 178      * parameters to be submitted.
 179      */
 180     getSubmitData: function() {
 181         var me = this,
 182             data = null;
 183         if (!me.disabled &amp;&amp; me.submitValue &amp;&amp; !me.isFileUpload()) {
 184             data = {};
 185             data[me.getName()] = '' + me.getValue();
 186         }
 187         return data;
 188     },
 189
 190 <span id='Ext-form.field.Field-method-getModelData'>    /**
 191 </span>     * &lt;p&gt;Returns the value(s) that should be saved to the {@link Ext.data.Model} instance for this field, when
 192      * {@link Ext.form.Basic#updateRecord} is called. Typically this will be an object with a single name-value
 193      * pair, the name being this field's {@link #getName name} and the value being its current data value. More
 194      * advanced field implementations may return more than one name-value pair. The returned values will be
 195      * saved to the corresponding field names in the Model.&lt;/p&gt;
 196      * &lt;p&gt;Note that the values returned from this method are not guaranteed to have been successfully
 197      * {@link #validate validated}.&lt;/p&gt;
 198      * @return {Object} A mapping of submit parameter names to values; each value should be a string, or an array
 199      * of strings if that particular name has multiple values. It can also return &lt;tt&gt;null&lt;/tt&gt; if there are no
 200      * parameters to be submitted.
 201      */
 202     getModelData: function() {
 203         var me = this,
 204             data = null;
 205         if (!me.disabled &amp;&amp; !me.isFileUpload()) {
 206             data = {};
 207             data[me.getName()] = me.getValue();
 208         }
 209         return data;
 210     },
 211
 212 <span id='Ext-form.field.Field-method-reset'>    /**
 213 </span>     * Resets the current field value to the originally loaded value and clears any validation messages.
 214      * See {@link Ext.form.Basic}.{@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
 215      */
 216     reset : function(){
 217         var me = this;
 218
 219         me.setValue(me.originalValue);
 220         me.clearInvalid();
 221         // delete here so we reset back to the original state
 222         delete me.wasValid;
 223     },
 224
 225 <span id='Ext-form.field.Field-method-resetOriginalValue'>    /**
 226 </span>     * Resets the field's {@link #originalValue} property so it matches the current {@link #getValue value}.
 227      * This is called by {@link Ext.form.Basic}.{@link Ext.form.Basic#setValues setValues} if the form's
 228      * {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad} property is set to true.
 229      */
 230     resetOriginalValue: function() {
 231         this.originalValue = this.getValue();
 232         this.checkDirty();
 233     },
 234
 235 <span id='Ext-form.field.Field-method-checkChange'>    /**
 236 </span>     * &lt;p&gt;Checks whether the value of the field has changed since the last time it was checked. If the value
 237      * has changed, it:&lt;/p&gt;
 238      * &lt;ol&gt;
 239      * &lt;li&gt;Fires the {@link #change change event},&lt;/li&gt;
 240      * &lt;li&gt;Performs validation if the {@link #validateOnChange} config is enabled, firing the
 241      * {@link #validationchange validationchange event} if the validity has changed, and&lt;/li&gt;
 242      * &lt;li&gt;Checks the {@link #isDirty dirty state} of the field and fires the {@link #dirtychange dirtychange event}
 243      * if it has changed.&lt;/li&gt;
 244      * &lt;/ol&gt;
 245      */
 246     checkChange: function() {
 247         if (!this.suspendCheckChange) {
 248             var me = this,
 249                 newVal = me.getValue(),
 250                 oldVal = me.lastValue;
 251             if (!me.isEqual(newVal, oldVal) &amp;&amp; !me.isDestroyed) {
 252                 me.lastValue = newVal;
 253                 me.fireEvent('change', me, newVal, oldVal);
 254                 me.onChange(newVal, oldVal);
 255             }
 256         }
 257     },
 258
 259 <span id='Ext-form.field.Field-method-onChange'>    /**
 260 </span>     * @private
 261      * Called when the field's value changes. Performs validation if the {@link #validateOnChange}
 262      * config is enabled, and invokes the dirty check.
 263      */
 264     onChange: function(newVal, oldVal) {
 265         if (this.validateOnChange) {
 266             this.validate();
 267         }
 268         this.checkDirty();
 269     },
 270
 271 <span id='Ext-form.field.Field-method-isDirty'>    /**
 272 </span>     * &lt;p&gt;Returns true if the value of this Field has been changed from its {@link #originalValue}.
 273      * Will always return false if the field is disabled.&lt;/p&gt;
 274      * &lt;p&gt;Note that if the owning {@link Ext.form.Basic form} was configured with
 275      * {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}
 276      * then the {@link #originalValue} is updated when the values are loaded by
 277      * {@link Ext.form.Basic}.{@link Ext.form.Basic#setValues setValues}.&lt;/p&gt;
 278      * @return {Boolean} True if this field has been changed from its original value (and
 279      * is not disabled), false otherwise.
 280      */
 281     isDirty : function() {
 282         var me = this;
 283         return !me.disabled &amp;&amp; !me.isEqual(me.getValue(), me.originalValue);
 284     },
 285
 286 <span id='Ext-form.field.Field-method-checkDirty'>    /**
 287 </span>     * Checks the {@link #isDirty} state of the field and if it has changed since the last time
 288      * it was checked, fires the {@link #dirtychange} event.
 289      */
 290     checkDirty: function() {
 291         var me = this,
 292             isDirty = me.isDirty();
 293         if (isDirty !== me.wasDirty) {
 294             me.fireEvent('dirtychange', me, isDirty);
 295             me.onDirtyChange(isDirty);
 296             me.wasDirty = isDirty;
 297         }
 298     },
 299
 300 <span id='Ext-form.field.Field-property-onDirtyChange'>    /**
 301 </span>     * @private Called when the field's dirty state changes.
 302      * @param {Boolean} isDirty
 303      */
 304     onDirtyChange: Ext.emptyFn,
 305
 306 <span id='Ext-form.field.Field-method-getErrors'>    /**
 307 </span>     * &lt;p&gt;Runs this field's validators and returns an array of error messages for any validation failures.
 308      * This is called internally during validation and would not usually need to be used manually.&lt;/p&gt;
 309      * &lt;p&gt;Each subclass should override or augment the return value to provide their own errors.&lt;/p&gt;
 310      * @param {Mixed} value The value to get errors for (defaults to the current field value)
 311      * @return {Array} All error messages for this field; an empty Array if none.
 312      */
 313     getErrors: function(value) {
 314         return [];
 315     },
 316
 317 <span id='Ext-form.field.Field-method-isValid'>    /**
 318 </span>     * &lt;p&gt;Returns whether or not the field value is currently valid by {@link #getErrors validating} the
 319      * field's current value. The {@link #validitychange} event will not be fired; use {@link #validate}
 320      * instead if you want the event to fire. &lt;b&gt;Note&lt;/b&gt;: {@link #disabled} fields are always treated as valid.&lt;/p&gt;
 321      * &lt;p&gt;Implementations are encouraged to ensure that this method does not have side-effects such as
 322      * triggering error message display.&lt;/p&gt;
 323      * @return {Boolean} True if the value is valid, else false
 324      */
 325     isValid : function() {
 326         var me = this;
 327         return me.disabled || Ext.isEmpty(me.getErrors());
 328     },
 329
 330 <span id='Ext-form.field.Field-method-validate'>    /**
 331 </span>     * &lt;p&gt;Returns whether or not the field value is currently valid by {@link #getErrors validating} the
 332      * field's current value, and fires the {@link #validitychange} event if the field's validity has
 333      * changed since the last validation. &lt;b&gt;Note&lt;/b&gt;: {@link #disabled} fields are always treated as valid.&lt;/p&gt;
 334      * &lt;p&gt;Custom implementations of this method are allowed to have side-effects such as triggering error
 335      * message display. To validate without side-effects, use {@link #isValid}.&lt;/p&gt;
 336      * @return {Boolean} True if the value is valid, else false
 337      */
 338     validate : function() {
 339         var me = this,
 340             isValid = me.isValid();
 341         if (isValid !== me.wasValid) {
 342             me.wasValid = isValid;
 343             me.fireEvent('validitychange', me, isValid);
 344         }
 345         return isValid;
 346     },
 347
 348 <span id='Ext-form.field.Field-method-batchChanges'>    /**
 349 </span>     * A utility for grouping a set of modifications which may trigger value changes into a single
 350      * transaction, to prevent excessive firing of {@link #change} events. This is useful for instance
 351      * if the field has sub-fields which are being updated as a group; you don't want the container
 352      * field to check its own changed state for each subfield change.
 353      * @param fn A function containing the transaction code
 354      */
 355     batchChanges: function(fn) {
 356         this.suspendCheckChange++;
 357         fn();
 358         this.suspendCheckChange--;
 359         this.checkChange();
 360     },
 361
 362 <span id='Ext-form.field.Field-method-isFileUpload'>    /**
 363 </span>     * Returns whether this Field is a file upload field; if it returns true, forms will use
 364      * special techniques for {@link Ext.form.Basic#submit submitting the form} via AJAX. See
 365      * {@link Ext.form.Basic#hasUpload} for details. If this returns true, the {@link #extractFileInput}
 366      * method must also be implemented to return the corresponding file input element.
 367      * @return {Boolean}
 368      */
 369     isFileUpload: function() {
 370         return false;
 371     },
 372
 373 <span id='Ext-form.field.Field-method-extractFileInput'>    /**
 374 </span>     * Only relevant if the instance's {@link #isFileUpload} method returns true. Returns a reference
 375      * to the file input DOM element holding the user's selected file. The input will be appended into
 376      * the submission form and will not be returned, so this method should also create a replacement.
 377      * @return {HTMLInputElement}
 378      */
 379     extractFileInput: function() {
 380         return null;
 381     },
 382
 383 <span id='Ext-form.field.Field-property-markInvalid'>    /**
 384 </span>     * &lt;p&gt;Associate one or more error messages with this field. Components using this mixin should implement
 385      * this method to update the component's rendering to display the messages.&lt;/p&gt;
 386      * &lt;p&gt;&lt;b&gt;Note&lt;/b&gt;: this method does not cause the Field's {@link #validate} or {@link #isValid} methods to
 387      * return &lt;code&gt;false&lt;/code&gt; if the value does &lt;i&gt;pass&lt;/i&gt; validation. So simply marking a Field as invalid
 388      * will not prevent submission of forms submitted with the {@link Ext.form.action.Submit#clientValidation}
 389      * option set.&lt;/p&gt;
 390      * @param {String/Array} errors The error message(s) for the field.
 391      */
 392     markInvalid: Ext.emptyFn,
 393
 394 <span id='Ext-form.field.Field-property-clearInvalid'>    /**
 395 </span>     * &lt;p&gt;Clear any invalid styles/messages for this field. Components using this mixin should implement
 396      * this method to update the components rendering to clear any existing messages.&lt;/p&gt;
 397      * &lt;p&gt;&lt;b&gt;Note&lt;/b&gt;: this method does not cause the Field's {@link #validate} or {@link #isValid} methods to
 398      * return &lt;code&gt;true&lt;/code&gt; if the value does not &lt;i&gt;pass&lt;/i&gt; validation. So simply clearing a field's errors
 399      * will not necessarily allow submission of forms submitted with the {@link Ext.form.action.Submit#clientValidation}
 400      * option set.&lt;/p&gt;
 401      */
 402     clearInvalid: Ext.emptyFn
 403
 404 });
 405 </pre></pre></body></html>