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