docs/source/Field.html

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