/javascripts/lib/docs/source/TextField.html
HTML | 557 lines | 523 code | 34 blank | 0 comment | 0 complexity | 7b881602a356c51a60a68d85f024ecca MD5 | raw file
Possible License(s): GPL-3.0
1<html> 2<head> 3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 4 <title>The source code</title> 5 <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" /> 6 <script type="text/javascript" src="../resources/prettify/prettify.js"></script> 7</head> 8<body onload="prettyPrint();"> 9 <pre class="prettyprint lang-js">/*! 10 * Ext JS Library 3.2.1 11 * Copyright(c) 2006-2010 Ext JS, Inc. 12 * licensing@extjs.com 13 * http://www.extjs.com/license 14 */ 15<div id="cls-Ext.form.TextField"></div>/** 16 * @class Ext.form.TextField 17 * @extends Ext.form.Field 18 * <p>Basic text field. Can be used as a direct replacement for traditional text inputs, 19 * or as the base class for more sophisticated input controls (like {@link Ext.form.TextArea} 20 * and {@link Ext.form.ComboBox}).</p> 21 * <p><b><u>Validation</u></b></p> 22 * <p>The validation procedure is described in the documentation for {@link #validateValue}.</p> 23 * <p><b><u>Alter Validation Behavior</u></b></p> 24 * <p>Validation behavior for each field can be configured:</p> 25 * <div class="mdetail-params"><ul> 26 * <li><code>{@link Ext.form.TextField#invalidText invalidText}</code> : the default validation message to 27 * show if any validation step above does not provide a message when invalid</li> 28 * <li><code>{@link Ext.form.TextField#maskRe maskRe}</code> : filter out keystrokes before any validation occurs</li> 29 * <li><code>{@link Ext.form.TextField#stripCharsRe stripCharsRe}</code> : filter characters after being typed in, 30 * but before being validated</li> 31 * <li><code>{@link Ext.form.Field#invalidClass invalidClass}</code> : alternate style when invalid</li> 32 * <li><code>{@link Ext.form.Field#validateOnBlur validateOnBlur}</code>, 33 * <code>{@link Ext.form.Field#validationDelay validationDelay}</code>, and 34 * <code>{@link Ext.form.Field#validationEvent validationEvent}</code> : modify how/when validation is triggered</li> 35 * </ul></div> 36 * 37 * @constructor Creates a new TextField 38 * @param {Object} config Configuration options 39 * 40 * @xtype textfield 41 */ 42Ext.form.TextField = Ext.extend(Ext.form.Field, { 43 <div id="cfg-Ext.form.TextField-vtypeText"></div>/** 44 * @cfg {String} vtypeText A custom error message to display in place of the default message provided 45 * for the <b><code>{@link #vtype}</code></b> currently set for this field (defaults to <tt>''</tt>). <b>Note</b>: 46 * only applies if <b><code>{@link #vtype}</code></b> is set, else ignored. 47 */ 48 <div id="cfg-Ext.form.TextField-stripCharsRe"></div>/** 49 * @cfg {RegExp} stripCharsRe A JavaScript RegExp object used to strip unwanted content from the value 50 * before validation (defaults to <tt>null</tt>). 51 */ 52 <div id="cfg-Ext.form.TextField-grow"></div>/** 53 * @cfg {Boolean} grow <tt>true</tt> if this field should automatically grow and shrink to its content 54 * (defaults to <tt>false</tt>) 55 */ 56 grow : false, 57 <div id="cfg-Ext.form.TextField-growMin"></div>/** 58 * @cfg {Number} growMin The minimum width to allow when <code><b>{@link #grow}</b> = true</code> (defaults 59 * to <tt>30</tt>) 60 */ 61 growMin : 30, 62 <div id="cfg-Ext.form.TextField-growMax"></div>/** 63 * @cfg {Number} growMax The maximum width to allow when <code><b>{@link #grow}</b> = true</code> (defaults 64 * to <tt>800</tt>) 65 */ 66 growMax : 800, 67 <div id="cfg-Ext.form.TextField-vtype"></div>/** 68 * @cfg {String} vtype A validation type name as defined in {@link Ext.form.VTypes} (defaults to <tt>null</tt>) 69 */ 70 vtype : null, 71 <div id="cfg-Ext.form.TextField-maskRe"></div>/** 72 * @cfg {RegExp} maskRe An input mask regular expression that will be used to filter keystrokes that do 73 * not match (defaults to <tt>null</tt>) 74 */ 75 maskRe : null, 76 <div id="cfg-Ext.form.TextField-disableKeyFilter"></div>/** 77 * @cfg {Boolean} disableKeyFilter Specify <tt>true</tt> to disable input keystroke filtering (defaults 78 * to <tt>false</tt>) 79 */ 80 disableKeyFilter : false, 81 <div id="cfg-Ext.form.TextField-allowBlank"></div>/** 82 * @cfg {Boolean} allowBlank Specify <tt>false</tt> to validate that the value's length is > 0 (defaults to 83 * <tt>true</tt>) 84 */ 85 allowBlank : true, 86 <div id="cfg-Ext.form.TextField-minLength"></div>/** 87 * @cfg {Number} minLength Minimum input field length required (defaults to <tt>0</tt>) 88 */ 89 minLength : 0, 90 <div id="cfg-Ext.form.TextField-maxLength"></div>/** 91 * @cfg {Number} maxLength Maximum input field length allowed by validation (defaults to Number.MAX_VALUE). 92 * This behavior is intended to provide instant feedback to the user by improving usability to allow pasting 93 * and editing or overtyping and back tracking. To restrict the maximum number of characters that can be 94 * entered into the field use <tt><b>{@link Ext.form.Field#autoCreate autoCreate}</b></tt> to add 95 * any attributes you want to a field, for example:<pre><code> 96var myField = new Ext.form.NumberField({ 97 id: 'mobile', 98 anchor:'90%', 99 fieldLabel: 'Mobile', 100 maxLength: 16, // for validation 101 autoCreate: {tag: 'input', type: 'text', size: '20', autocomplete: 'off', maxlength: '10'} 102}); 103</code></pre> 104 */ 105 maxLength : Number.MAX_VALUE, 106 <div id="cfg-Ext.form.TextField-minLengthText"></div>/** 107 * @cfg {String} minLengthText Error text to display if the <b><tt>{@link #minLength minimum length}</tt></b> 108 * validation fails (defaults to <tt>'The minimum length for this field is {minLength}'</tt>) 109 */ 110 minLengthText : 'The minimum length for this field is {0}', 111 <div id="cfg-Ext.form.TextField-maxLengthText"></div>/** 112 * @cfg {String} maxLengthText Error text to display if the <b><tt>{@link #maxLength maximum length}</tt></b> 113 * validation fails (defaults to <tt>'The maximum length for this field is {maxLength}'</tt>) 114 */ 115 maxLengthText : 'The maximum length for this field is {0}', 116 <div id="cfg-Ext.form.TextField-selectOnFocus"></div>/** 117 * @cfg {Boolean} selectOnFocus <tt>true</tt> to automatically select any existing field text when the field 118 * receives input focus (defaults to <tt>false</tt>) 119 */ 120 selectOnFocus : false, 121 <div id="cfg-Ext.form.TextField-blankText"></div>/** 122 * @cfg {String} blankText The error text to display if the <b><tt>{@link #allowBlank}</tt></b> validation 123 * fails (defaults to <tt>'This field is required'</tt>) 124 */ 125 blankText : 'This field is required', 126 <div id="cfg-Ext.form.TextField-validator"></div>/** 127 * @cfg {Function} validator 128 * <p>A custom validation function to be called during field validation ({@link #validateValue}) 129 * (defaults to <tt>null</tt>). If specified, this function will be called first, allowing the 130 * developer to override the default validation process.</p> 131 * <br><p>This function will be passed the following Parameters:</p> 132 * <div class="mdetail-params"><ul> 133 * <li><code>value</code>: <i>Mixed</i> 134 * <div class="sub-desc">The current field value</div></li> 135 * </ul></div> 136 * <br><p>This function is to Return:</p> 137 * <div class="mdetail-params"><ul> 138 * <li><code>true</code>: <i>Boolean</i> 139 * <div class="sub-desc"><code>true</code> if the value is valid</div></li> 140 * <li><code>msg</code>: <i>String</i> 141 * <div class="sub-desc">An error message if the value is invalid</div></li> 142 * </ul></div> 143 */ 144 validator : null, 145 <div id="cfg-Ext.form.TextField-regex"></div>/** 146 * @cfg {RegExp} regex A JavaScript RegExp object to be tested against the field value during validation 147 * (defaults to <tt>null</tt>). If the test fails, the field will be marked invalid using 148 * <b><tt>{@link #regexText}</tt></b>. 149 */ 150 regex : null, 151 <div id="cfg-Ext.form.TextField-regexText"></div>/** 152 * @cfg {String} regexText The error text to display if <b><tt>{@link #regex}</tt></b> is used and the 153 * test fails during validation (defaults to <tt>''</tt>) 154 */ 155 regexText : '', 156 <div id="cfg-Ext.form.TextField-emptyText"></div>/** 157 * @cfg {String} emptyText The default text to place into an empty field (defaults to <tt>null</tt>). 158 * <b>Note</b>: that this value will be submitted to the server if this field is enabled and configured 159 * with a {@link #name}. 160 */ 161 emptyText : null, 162 <div id="cfg-Ext.form.TextField-emptyClass"></div>/** 163 * @cfg {String} emptyClass The CSS class to apply to an empty field to style the <b><tt>{@link #emptyText}</tt></b> 164 * (defaults to <tt>'x-form-empty-field'</tt>). This class is automatically added and removed as needed 165 * depending on the current field value. 166 */ 167 emptyClass : 'x-form-empty-field', 168 169 <div id="cfg-Ext.form.TextField-enableKeyEvents"></div>/** 170 * @cfg {Boolean} enableKeyEvents <tt>true</tt> to enable the proxying of key events for the HTML input 171 * field (defaults to <tt>false</tt>) 172 */ 173 174 initComponent : function(){ 175 Ext.form.TextField.superclass.initComponent.call(this); 176 this.addEvents( 177 <div id="event-Ext.form.TextField-autosize"></div>/** 178 * @event autosize 179 * Fires when the <tt><b>{@link #autoSize}</b></tt> function is triggered. The field may or 180 * may not have actually changed size according to the default logic, but this event provides 181 * a hook for the developer to apply additional logic at runtime to resize the field if needed. 182 * @param {Ext.form.Field} this This text field 183 * @param {Number} width The new field width 184 */ 185 'autosize', 186 187 <div id="event-Ext.form.TextField-keydown"></div>/** 188 * @event keydown 189 * Keydown input field event. This event only fires if <tt><b>{@link #enableKeyEvents}</b></tt> 190 * is set to true. 191 * @param {Ext.form.TextField} this This text field 192 * @param {Ext.EventObject} e 193 */ 194 'keydown', 195 <div id="event-Ext.form.TextField-keyup"></div>/** 196 * @event keyup 197 * Keyup input field event. This event only fires if <tt><b>{@link #enableKeyEvents}</b></tt> 198 * is set to true. 199 * @param {Ext.form.TextField} this This text field 200 * @param {Ext.EventObject} e 201 */ 202 'keyup', 203 <div id="event-Ext.form.TextField-keypress"></div>/** 204 * @event keypress 205 * Keypress input field event. This event only fires if <tt><b>{@link #enableKeyEvents}</b></tt> 206 * is set to true. 207 * @param {Ext.form.TextField} this This text field 208 * @param {Ext.EventObject} e 209 */ 210 'keypress' 211 ); 212 }, 213 214 // private 215 initEvents : function(){ 216 Ext.form.TextField.superclass.initEvents.call(this); 217 if(this.validationEvent == 'keyup'){ 218 this.validationTask = new Ext.util.DelayedTask(this.validate, this); 219 this.mon(this.el, 'keyup', this.filterValidation, this); 220 } 221 else if(this.validationEvent !== false && this.validationEvent != 'blur'){ 222 this.mon(this.el, this.validationEvent, this.validate, this, {buffer: this.validationDelay}); 223 } 224 if(this.selectOnFocus || this.emptyText){ 225 this.mon(this.el, 'mousedown', this.onMouseDown, this); 226 227 if(this.emptyText){ 228 this.applyEmptyText(); 229 } 230 } 231 if(this.maskRe || (this.vtype && this.disableKeyFilter !== true && (this.maskRe = Ext.form.VTypes[this.vtype+'Mask']))){ 232 this.mon(this.el, 'keypress', this.filterKeys, this); 233 } 234 if(this.grow){ 235 this.mon(this.el, 'keyup', this.onKeyUpBuffered, this, {buffer: 50}); 236 this.mon(this.el, 'click', this.autoSize, this); 237 } 238 if(this.enableKeyEvents){ 239 this.mon(this.el, { 240 scope: this, 241 keyup: this.onKeyUp, 242 keydown: this.onKeyDown, 243 keypress: this.onKeyPress 244 }); 245 } 246 }, 247 248 onMouseDown: function(e){ 249 if(!this.hasFocus){ 250 this.mon(this.el, 'mouseup', Ext.emptyFn, this, { single: true, preventDefault: true }); 251 } 252 }, 253 254 processValue : function(value){ 255 if(this.stripCharsRe){ 256 var newValue = value.replace(this.stripCharsRe, ''); 257 if(newValue !== value){ 258 this.setRawValue(newValue); 259 return newValue; 260 } 261 } 262 return value; 263 }, 264 265 filterValidation : function(e){ 266 if(!e.isNavKeyPress()){ 267 this.validationTask.delay(this.validationDelay); 268 } 269 }, 270 271 //private 272 onDisable: function(){ 273 Ext.form.TextField.superclass.onDisable.call(this); 274 if(Ext.isIE){ 275 this.el.dom.unselectable = 'on'; 276 } 277 }, 278 279 //private 280 onEnable: function(){ 281 Ext.form.TextField.superclass.onEnable.call(this); 282 if(Ext.isIE){ 283 this.el.dom.unselectable = ''; 284 } 285 }, 286 287 // private 288 onKeyUpBuffered : function(e){ 289 if(this.doAutoSize(e)){ 290 this.autoSize(); 291 } 292 }, 293 294 // private 295 doAutoSize : function(e){ 296 return !e.isNavKeyPress(); 297 }, 298 299 // private 300 onKeyUp : function(e){ 301 this.fireEvent('keyup', this, e); 302 }, 303 304 // private 305 onKeyDown : function(e){ 306 this.fireEvent('keydown', this, e); 307 }, 308 309 // private 310 onKeyPress : function(e){ 311 this.fireEvent('keypress', this, e); 312 }, 313 314 <div id="method-Ext.form.TextField-reset"></div>/** 315 * Resets the current field value to the originally-loaded value and clears any validation messages. 316 * Also adds <tt><b>{@link #emptyText}</b></tt> and <tt><b>{@link #emptyClass}</b></tt> if the 317 * original value was blank. 318 */ 319 reset : function(){ 320 Ext.form.TextField.superclass.reset.call(this); 321 this.applyEmptyText(); 322 }, 323 324 applyEmptyText : function(){ 325 if(this.rendered && this.emptyText && this.getRawValue().length < 1 && !this.hasFocus){ 326 this.setRawValue(this.emptyText); 327 this.el.addClass(this.emptyClass); 328 } 329 }, 330 331 // private 332 preFocus : function(){ 333 var el = this.el; 334 if(this.emptyText){ 335 if(el.dom.value == this.emptyText){ 336 this.setRawValue(''); 337 } 338 el.removeClass(this.emptyClass); 339 } 340 if(this.selectOnFocus){ 341 el.dom.select(); 342 } 343 }, 344 345 // private 346 postBlur : function(){ 347 this.applyEmptyText(); 348 }, 349 350 // private 351 filterKeys : function(e){ 352 if(e.ctrlKey){ 353 return; 354 } 355 var k = e.getKey(); 356 if(Ext.isGecko && (e.isNavKeyPress() || k == e.BACKSPACE || (k == e.DELETE && e.button == -1))){ 357 return; 358 } 359 var cc = String.fromCharCode(e.getCharCode()); 360 if(!Ext.isGecko && e.isSpecialKey() && !cc){ 361 return; 362 } 363 if(!this.maskRe.test(cc)){ 364 e.stopEvent(); 365 } 366 }, 367 368 setValue : function(v){ 369 if(this.emptyText && this.el && !Ext.isEmpty(v)){ 370 this.el.removeClass(this.emptyClass); 371 } 372 Ext.form.TextField.superclass.setValue.apply(this, arguments); 373 this.applyEmptyText(); 374 this.autoSize(); 375 return this; 376 }, 377 378 <div id="method-Ext.form.TextField-getErrors"></div>/** 379 * <p>Validates a value according to the field's validation rules and returns an array of errors 380 * for any failing validations. Validation rules are processed in the following order:</p> 381 * <div class="mdetail-params"><ul> 382 * 383 * <li><b>1. Field specific validator</b> 384 * <div class="sub-desc"> 385 * <p>A validator offers a way to customize and reuse a validation specification. 386 * If a field is configured with a <code>{@link #validator}</code> 387 * function, it will be passed the current field value. The <code>{@link #validator}</code> 388 * function is expected to return either: 389 * <div class="mdetail-params"><ul> 390 * <li>Boolean <tt>true</tt> if the value is valid (validation continues).</li> 391 * <li>a String to represent the invalid message if invalid (validation halts).</li> 392 * </ul></div> 393 * </div></li> 394 * 395 * <li><b>2. Basic Validation</b> 396 * <div class="sub-desc"> 397 * <p>If the <code>{@link #validator}</code> has not halted validation, 398 * basic validation proceeds as follows:</p> 399 * 400 * <div class="mdetail-params"><ul> 401 * 402 * <li><code>{@link #allowBlank}</code> : (Invalid message = 403 * <code>{@link #emptyText}</code>)<div class="sub-desc"> 404 * Depending on the configuration of <code>{@link #allowBlank}</code>, a 405 * blank field will cause validation to halt at this step and return 406 * Boolean true or false accordingly. 407 * </div></li> 408 * 409 * <li><code>{@link #minLength}</code> : (Invalid message = 410 * <code>{@link #minLengthText}</code>)<div class="sub-desc"> 411 * If the passed value does not satisfy the <code>{@link #minLength}</code> 412 * specified, validation halts. 413 * </div></li> 414 * 415 * <li><code>{@link #maxLength}</code> : (Invalid message = 416 * <code>{@link #maxLengthText}</code>)<div class="sub-desc"> 417 * If the passed value does not satisfy the <code>{@link #maxLength}</code> 418 * specified, validation halts. 419 * </div></li> 420 * 421 * </ul></div> 422 * </div></li> 423 * 424 * <li><b>3. Preconfigured Validation Types (VTypes)</b> 425 * <div class="sub-desc"> 426 * <p>If none of the prior validation steps halts validation, a field 427 * configured with a <code>{@link #vtype}</code> will utilize the 428 * corresponding {@link Ext.form.VTypes VTypes} validation function. 429 * If invalid, either the field's <code>{@link #vtypeText}</code> or 430 * the VTypes vtype Text property will be used for the invalid message. 431 * Keystrokes on the field will be filtered according to the VTypes 432 * vtype Mask property.</p> 433 * </div></li> 434 * 435 * <li><b>4. Field specific regex test</b> 436 * <div class="sub-desc"> 437 * <p>If none of the prior validation steps halts validation, a field's 438 * configured <code>{@link #regex}</code> test will be processed. 439 * The invalid message for this test is configured with 440 * <code>{@link #regexText}</code>.</p> 441 * </div></li> 442 * 443 * @param {Mixed} value The value to validate. The processed raw value will be used if nothing is passed 444 * @return {Array} Array of any validation errors 445 */ 446 getErrors: function(value) { 447 var errors = Ext.form.TextField.superclass.getErrors.apply(this, arguments); 448 449 value = value || this.processValue(this.getRawValue()); 450 451 if (Ext.isFunction(this.validator)) { 452 var msg = this.validator(value); 453 if (msg !== true) { 454 errors.push(msg); 455 } 456 } 457 458 if (value.length < 1 || value === this.emptyText) { 459 if (this.allowBlank) { 460 //if value is blank and allowBlank is true, there cannot be any additional errors 461 return errors; 462 } else { 463 errors.push(this.blankText); 464 } 465 } 466 467 if (!this.allowBlank && (value.length < 1 || value === this.emptyText)) { // if it's blank 468 errors.push(this.blankText); 469 } 470 471 if (value.length < this.minLength) { 472 errors.push(String.format(this.minLengthText, this.minLength)); 473 } 474 475 if (value.length > this.maxLength) { 476 errors.push(String.format(this.maxLengthText, this.maxLength)); 477 } 478 479 if (this.vtype) { 480 var vt = Ext.form.VTypes; 481 if(!vt[this.vtype](value, this)){ 482 errors.push(this.vtypeText || vt[this.vtype +'Text']); 483 } 484 } 485 486 if (this.regex && !this.regex.test(value)) { 487 errors.push(this.regexText); 488 } 489 490 return errors; 491 }, 492 493 <div id="method-Ext.form.TextField-selectText"></div>/** 494 * Selects text in this field 495 * @param {Number} start (optional) The index where the selection should start (defaults to 0) 496 * @param {Number} end (optional) The index where the selection should end (defaults to the text length) 497 */ 498 selectText : function(start, end){ 499 var v = this.getRawValue(); 500 var doFocus = false; 501 if(v.length > 0){ 502 start = start === undefined ? 0 : start; 503 end = end === undefined ? v.length : end; 504 var d = this.el.dom; 505 if(d.setSelectionRange){ 506 d.setSelectionRange(start, end); 507 }else if(d.createTextRange){ 508 var range = d.createTextRange(); 509 range.moveStart('character', start); 510 range.moveEnd('character', end-v.length); 511 range.select(); 512 } 513 doFocus = Ext.isGecko || Ext.isOpera; 514 }else{ 515 doFocus = true; 516 } 517 if(doFocus){ 518 this.focus(); 519 } 520 }, 521 522 <div id="method-Ext.form.TextField-autoSize"></div>/** 523 * Automatically grows the field to accomodate the width of the text up to the maximum field width allowed. 524 * This only takes effect if <tt><b>{@link #grow}</b> = true</tt>, and fires the {@link #autosize} event. 525 */ 526 autoSize : function(){ 527 if(!this.grow || !this.rendered){ 528 return; 529 } 530 if(!this.metrics){ 531 this.metrics = Ext.util.TextMetrics.createInstance(this.el); 532 } 533 var el = this.el; 534 var v = el.dom.value; 535 var d = document.createElement('div'); 536 d.appendChild(document.createTextNode(v)); 537 v = d.innerHTML; 538 Ext.removeNode(d); 539 d = null; 540 v += ' '; 541 var w = Math.min(this.growMax, Math.max(this.metrics.getWidth(v) + /* add extra padding */ 10, this.growMin)); 542 this.el.setWidth(w); 543 this.fireEvent('autosize', this, w); 544 }, 545 546 onDestroy: function(){ 547 if(this.validationTask){ 548 this.validationTask.cancel(); 549 this.validationTask = null; 550 } 551 Ext.form.TextField.superclass.onDestroy.call(this); 552 } 553}); 554Ext.reg('textfield', Ext.form.TextField); 555</pre> 556</body> 557</html>