src/widgets/Editor.js

   1 /*!
   2  * Ext JS Library 3.0.3
   3  * Copyright(c) 2006-2009 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.Editor
   9  * @extends Ext.Component
  10  * A base editor field that handles displaying/hiding on demand and has some built-in sizing and event handling logic.
  11  * @constructor
  12  * Create a new Editor
  13  * @param {Object} config The config object
  14  * @xtype editor
  15  */
  16 Ext.Editor = function(field, config){
  17     if(field.field){
  18         this.field = Ext.create(field.field, 'textfield');
  19         config = Ext.apply({}, field); // copy so we don't disturb original config
  20         delete config.field;
  21     }else{
  22         this.field = field;
  23     }
  24     Ext.Editor.superclass.constructor.call(this, config);
  25 };
  26
  27 Ext.extend(Ext.Editor, Ext.Component, {
  28     /**
  29     * @cfg {Ext.form.Field} field
  30     * The Field object (or descendant) or config object for field
  31     */
  32     /**
  33      * @cfg {Boolean} allowBlur
  34      * True to {@link #completeEdit complete the editing process} if in edit mode when the
  35      * field is blurred. Defaults to <tt>false</tt>.
  36      */
  37     /**
  38      * @cfg {Boolean/String} autoSize
  39      * True for the editor to automatically adopt the size of the underlying field, "width" to adopt the width only,
  40      * or "height" to adopt the height only, "none" to always use the field dimensions. (defaults to false)
  41      */
  42     /**
  43      * @cfg {Boolean} revertInvalid
  44      * True to automatically revert the field value and cancel the edit when the user completes an edit and the field
  45      * validation fails (defaults to true)
  46      */
  47     /**
  48      * @cfg {Boolean} ignoreNoChange
  49      * True to skip the edit completion process (no save, no events fired) if the user completes an edit and
  50      * the value has not changed (defaults to false).  Applies only to string values - edits for other data types
  51      * will never be ignored.
  52      */
  53     /**
  54      * @cfg {Boolean} hideEl
  55      * False to keep the bound element visible while the editor is displayed (defaults to true)
  56      */
  57     /**
  58      * @cfg {Mixed} value
  59      * The data value of the underlying field (defaults to "")
  60      */
  61     value : "",
  62     /**
  63      * @cfg {String} alignment
  64      * The position to align to (see {@link Ext.Element#alignTo} for more details, defaults to "c-c?").
  65      */
  66     alignment: "c-c?",
  67     /**
  68      * @cfg {Boolean/String} shadow "sides" for sides/bottom only, "frame" for 4-way shadow, and "drop"
  69      * for bottom-right shadow (defaults to "frame")
  70      */
  71     shadow : "frame",
  72     /**
  73      * @cfg {Boolean} constrain True to constrain the editor to the viewport
  74      */
  75     constrain : false,
  76     /**
  77      * @cfg {Boolean} swallowKeys Handle the keydown/keypress events so they don't propagate (defaults to true)
  78      */
  79     swallowKeys : true,
  80     /**
  81      * @cfg {Boolean} completeOnEnter True to complete the edit when the enter key is pressed. Defaults to <tt>true</tt>.
  82      */
  83     completeOnEnter : true,
  84     /**
  85      * @cfg {Boolean} cancelOnEsc True to cancel the edit when the escape key is pressed. Defaults to <tt>true</tt>.
  86      */
  87     cancelOnEsc : true,
  88     /**
  89      * @cfg {Boolean} updateEl True to update the innerHTML of the bound element when the update completes (defaults to false)
  90      */
  91     updateEl : false,
  92
  93     initComponent : function(){
  94         Ext.Editor.superclass.initComponent.call(this);
  95         this.addEvents(
  96             /**
  97              * @event beforestartedit
  98              * Fires when editing is initiated, but before the value changes.  Editing can be canceled by returning
  99              * false from the handler of this event.
 100              * @param {Editor} this
 101              * @param {Ext.Element} boundEl The underlying element bound to this editor
 102              * @param {Mixed} value The field value being set
 103              */
 104             "beforestartedit",
 105             /**
 106              * @event startedit
 107              * Fires when this editor is displayed
 108              * @param {Ext.Element} boundEl The underlying element bound to this editor
 109              * @param {Mixed} value The starting field value
 110              */
 111             "startedit",
 112             /**
 113              * @event beforecomplete
 114              * Fires after a change has been made to the field, but before the change is reflected in the underlying
 115              * field.  Saving the change to the field can be canceled by returning false from the handler of this event.
 116              * Note that if the value has not changed and ignoreNoChange = true, the editing will still end but this
 117              * event will not fire since no edit actually occurred.
 118              * @param {Editor} this
 119              * @param {Mixed} value The current field value
 120              * @param {Mixed} startValue The original field value
 121              */
 122             "beforecomplete",
 123             /**
 124              * @event complete
 125              * Fires after editing is complete and any changed value has been written to the underlying field.
 126              * @param {Editor} this
 127              * @param {Mixed} value The current field value
 128              * @param {Mixed} startValue The original field value
 129              */
 130             "complete",
 131             /**
 132              * @event canceledit
 133              * Fires after editing has been canceled and the editor's value has been reset.
 134              * @param {Editor} this
 135              * @param {Mixed} value The user-entered field value that was discarded
 136              * @param {Mixed} startValue The original field value that was set back into the editor after cancel
 137              */
 138             "canceledit",
 139             /**
 140              * @event specialkey
 141              * Fires when any key related to navigation (arrows, tab, enter, esc, etc.) is pressed.  You can check
 142              * {@link Ext.EventObject#getKey} to determine which key was pressed.
 143              * @param {Ext.form.Field} this
 144              * @param {Ext.EventObject} e The event object
 145              */
 146             "specialkey"
 147         );
 148     },
 149
 150     // private
 151     onRender : function(ct, position){
 152         this.el = new Ext.Layer({
 153             shadow: this.shadow,
 154             cls: "x-editor",
 155             parentEl : ct,
 156             shim : this.shim,
 157             shadowOffset: this.shadowOffset || 4,
 158             id: this.id,
 159             constrain: this.constrain
 160         });
 161         if(this.zIndex){
 162             this.el.setZIndex(this.zIndex);
 163         }
 164         this.el.setStyle("overflow", Ext.isGecko ? "auto" : "hidden");
 165         if(this.field.msgTarget != 'title'){
 166             this.field.msgTarget = 'qtip';
 167         }
 168         this.field.inEditor = true;
 169         this.mon(this.field, {
 170             scope: this,
 171             blur: this.onBlur,
 172             specialkey: this.onSpecialKey
 173         });
 174         if(this.field.grow){
 175             this.mon(this.field, "autosize", this.el.sync,  this.el, {delay:1});
 176         }
 177         this.field.render(this.el).show();
 178         this.field.getEl().dom.name = '';
 179         if(this.swallowKeys){
 180             this.field.el.swallowEvent([
 181                 'keypress', // *** Opera
 182                 'keydown'   // *** all other browsers
 183             ]);
 184         }
 185     },
 186
 187     // private
 188     onSpecialKey : function(field, e){
 189         var key = e.getKey(),
 190             complete = this.completeOnEnter && key == e.ENTER,
 191             cancel = this.cancelOnEsc && key == e.ESC;
 192         if(complete || cancel){
 193             e.stopEvent();
 194             if(complete){
 195                 this.completeEdit();
 196             }else{
 197                 this.cancelEdit();
 198             }
 199             if(field.triggerBlur){
 200                 field.triggerBlur();
 201             }
 202         }
 203         this.fireEvent('specialkey', field, e);
 204     },
 205
 206     /**
 207      * Starts the editing process and shows the editor.
 208      * @param {Mixed} el The element to edit
 209      * @param {String} value (optional) A value to initialize the editor with. If a value is not provided, it defaults
 210       * to the innerHTML of el.
 211      */
 212     startEdit : function(el, value){
 213         if(this.editing){
 214             this.completeEdit();
 215         }
 216         this.boundEl = Ext.get(el);
 217         var v = value !== undefined ? value : this.boundEl.dom.innerHTML;
 218         if(!this.rendered){
 219             this.render(this.parentEl || document.body);
 220         }
 221         if(this.fireEvent("beforestartedit", this, this.boundEl, v) !== false){
 222             this.startValue = v;
 223             this.field.setValue(v);
 224             this.doAutoSize();
 225             this.el.alignTo(this.boundEl, this.alignment);
 226             this.editing = true;
 227             this.show();
 228         }
 229     },
 230
 231     // private
 232     doAutoSize : function(){
 233         if(this.autoSize){
 234             var sz = this.boundEl.getSize(),
 235                 fs = this.field.getSize();
 236
 237             switch(this.autoSize){
 238                 case "width":
 239                     this.setSize(sz.width, fs.height);
 240                     break;
 241                 case "height":
 242                     this.setSize(fs.width, sz.height);
 243                     break;
 244                 case "none":
 245                     this.setSize(fs.width, fs.height);
 246                     break;
 247                 default:
 248                     this.setSize(sz.width, sz.height);
 249             }
 250         }
 251     },
 252
 253     /**
 254      * Sets the height and width of this editor.
 255      * @param {Number} width The new width
 256      * @param {Number} height The new height
 257      */
 258     setSize : function(w, h){
 259         delete this.field.lastSize;
 260         this.field.setSize(w, h);
 261         if(this.el){
 262             if(Ext.isGecko2 || Ext.isOpera){
 263                 // prevent layer scrollbars
 264                 this.el.setSize(w, h);
 265             }
 266             this.el.sync();
 267         }
 268     },
 269
 270     /**
 271      * Realigns the editor to the bound field based on the current alignment config value.
 272      */
 273     realign : function(){
 274         this.el.alignTo(this.boundEl, this.alignment);
 275     },
 276
 277     /**
 278      * Ends the editing process, persists the changed value to the underlying field, and hides the editor.
 279      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after edit (defaults to false)
 280      */
 281     completeEdit : function(remainVisible){
 282         if(!this.editing){
 283             return;
 284         }
 285         var v = this.getValue();
 286         if(!this.field.isValid()){
 287             if(this.revertInvalid !== false){
 288                 this.cancelEdit(remainVisible);
 289             }
 290             return;
 291         }
 292         if(String(v) === String(this.startValue) && this.ignoreNoChange){
 293             this.hideEdit(remainVisible);
 294             return;
 295         }
 296         if(this.fireEvent("beforecomplete", this, v, this.startValue) !== false){
 297             v = this.getValue();
 298             if(this.updateEl && this.boundEl){
 299                 this.boundEl.update(v);
 300             }
 301             this.hideEdit(remainVisible);
 302             this.fireEvent("complete", this, v, this.startValue);
 303         }
 304     },
 305
 306     // private
 307     onShow : function(){
 308         this.el.show();
 309         if(this.hideEl !== false){
 310             this.boundEl.hide();
 311         }
 312         this.field.show().focus(false, true);
 313         this.fireEvent("startedit", this.boundEl, this.startValue);
 314     },
 315
 316     /**
 317      * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
 318      * reverted to the original starting value.
 319      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after
 320      * cancel (defaults to false)
 321      */
 322     cancelEdit : function(remainVisible){
 323         if(this.editing){
 324             var v = this.getValue();
 325             this.setValue(this.startValue);
 326             this.hideEdit(remainVisible);
 327             this.fireEvent("canceledit", this, v, this.startValue);
 328         }
 329     },
 330
 331     // private
 332     hideEdit: function(remainVisible){
 333         if(remainVisible !== true){
 334             this.editing = false;
 335             this.hide();
 336         }
 337     },
 338
 339     // private
 340     onBlur : function(){
 341         if(this.allowBlur !== true && this.editing){
 342             this.completeEdit();
 343         }
 344     },
 345
 346     // private
 347     onHide : function(){
 348         if(this.editing){
 349             this.completeEdit();
 350             return;
 351         }
 352         this.field.blur();
 353         if(this.field.collapse){
 354             this.field.collapse();
 355         }
 356         this.el.hide();
 357         if(this.hideEl !== false){
 358             this.boundEl.show();
 359         }
 360     },
 361
 362     /**
 363      * Sets the data value of the editor
 364      * @param {Mixed} value Any valid value supported by the underlying field
 365      */
 366     setValue : function(v){
 367         this.field.setValue(v);
 368     },
 369
 370     /**
 371      * Gets the data value of the editor
 372      * @return {Mixed} The data value
 373      */
 374     getValue : function(){
 375         return this.field.getValue();
 376     },
 377
 378     beforeDestroy : function(){
 379         Ext.destroy(this.field);
 380         this.field = null;
 381     }
 382 });
 383 Ext.reg('editor', Ext.Editor);