Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / docs / source / Action.html
1 <html>\r
2 <head>\r
3   <title>The source code</title>\r
4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
6 </head>\r
7 <body  onload="prettyPrint();">\r
8     <pre class="prettyprint lang-js"><div id="cls-Ext.form.Action"></div>/**
9  * @class Ext.form.Action
10  * <p>The subclasses of this class provide actions to perform upon {@link Ext.form.BasicForm Form}s.</p>
11  * <p>Instances of this class are only created by a {@link Ext.form.BasicForm Form} when
12  * the Form needs to perform an action such as submit or load. The Configuration options
13  * listed for this class are set through the Form's action methods: {@link Ext.form.BasicForm#submit submit},
14  * {@link Ext.form.BasicForm#load load} and {@link Ext.form.BasicForm#doAction doAction}</p>
15  * <p>The instance of Action which performed the action is passed to the success
16  * and failure callbacks of the Form's action methods ({@link Ext.form.BasicForm#submit submit},
17  * {@link Ext.form.BasicForm#load load} and {@link Ext.form.BasicForm#doAction doAction}),
18  * and to the {@link Ext.form.BasicForm#actioncomplete actioncomplete} and
19  * {@link Ext.form.BasicForm#actionfailed actionfailed} event handlers.</p>
20  */
21 Ext.form.Action = function(form, options){
22     this.form = form;
23     this.options = options || {};
24 };
25
26 <div id="prop-Ext.form.Action-CLIENT_INVALID"></div>/**
27  * Failure type returned when client side validation of the Form fails
28  * thus aborting a submit action. Client side validation is performed unless
29  * {@link #clientValidation} is explicitly set to <tt>false</tt>.
30  * @type {String}
31  * @static
32  */
33 Ext.form.Action.CLIENT_INVALID = 'client';
34 <div id="prop-Ext.form.Action-SERVER_INVALID"></div>/**
35  * <p>Failure type returned when server side processing fails and the {@link #result}'s
36  * <tt style="font-weight:bold">success</tt> property is set to <tt>false</tt>.</p>
37  * <p>In the case of a form submission, field-specific error messages may be returned in the
38  * {@link #result}'s <tt style="font-weight:bold">errors</tt> property.</p>
39  * @type {String}
40  * @static
41  */
42 Ext.form.Action.SERVER_INVALID = 'server';
43 <div id="prop-Ext.form.Action-CONNECT_FAILURE"></div>/**
44  * Failure type returned when a communication error happens when attempting
45  * to send a request to the remote server. The {@link #response} may be examined to
46  * provide further information.
47  * @type {String}
48  * @static
49  */
50 Ext.form.Action.CONNECT_FAILURE = 'connect';
51 <div id="prop-Ext.form.Action-LOAD_FAILURE"></div>/**
52  * Failure type returned when the response's <tt style="font-weight:bold">success</tt>
53  * property is set to <tt>false</tt>, or no field values are returned in the response's
54  * <tt style="font-weight:bold">data</tt> property.
55  * @type {String}
56  * @static
57  */
58 Ext.form.Action.LOAD_FAILURE = 'load';
59
60 Ext.form.Action.prototype = {
61 <div id="cfg-Ext.form.Action-url"></div>/**
62  * @cfg {String} url The URL that the Action is to invoke.
63  */
64 <div id="cfg-Ext.form.Action-reset"></div>/**
65  * @cfg {Boolean} reset When set to <tt><b>true</b></tt>, causes the Form to be
66  * {@link Ext.form.BasicForm.reset reset} on Action success. If specified, this happens
67  * <b>before</b> the {@link #success} callback is called and before the Form's
68  * {@link Ext.form.BasicForm.actioncomplete actioncomplete} event fires.
69  */
70 <div id="cfg-Ext.form.Action-method"></div>/**
71  * @cfg {String} method The HTTP method to use to access the requested URL. Defaults to the
72  * {@link Ext.form.BasicForm}'s method, or if that is not specified, the underlying DOM form's method.
73  */
74 <div id="cfg-Ext.form.Action-params"></div>/**
75  * @cfg {Mixed} params <p>Extra parameter values to pass. These are added to the Form's
76  * {@link Ext.form.BasicForm#baseParams} and passed to the specified URL along with the Form's
77  * input fields.</p>
78  * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.</p>
79  */
80 <div id="cfg-Ext.form.Action-timeout"></div>/**
81  * @cfg {Number} timeout The number of seconds to wait for a server response before
82  * failing with the {@link #failureType} as {@link #Action.CONNECT_FAILURE}. If not specified,
83  * defaults to the configured <tt>{@link Ext.form.BasicForm#timeout timeout}</tt> of the
84  * {@link Ext.form.BasicForm form}.
85  */
86 <div id="cfg-Ext.form.Action-success"></div>/**
87  * @cfg {Function} success The function to call when a valid success return packet is recieved.
88  * The function is passed the following parameters:<ul class="mdetail-params">
89  * <li><b>form</b> : Ext.form.BasicForm<div class="sub-desc">The form that requested the action</div></li>
90  * <li><b>action</b> : Ext.form.Action<div class="sub-desc">The Action class. The {@link #result}
91  * property of this object may be examined to perform custom postprocessing.</div></li>
92  * </ul>
93  */
94 <div id="cfg-Ext.form.Action-failure"></div>/**
95  * @cfg {Function} failure The function to call when a failure packet was recieved, or when an
96  * error ocurred in the Ajax communication.
97  * The function is passed the following parameters:<ul class="mdetail-params">
98  * <li><b>form</b> : Ext.form.BasicForm<div class="sub-desc">The form that requested the action</div></li>
99  * <li><b>action</b> : Ext.form.Action<div class="sub-desc">The Action class. If an Ajax
100  * error ocurred, the failure type will be in {@link #failureType}. The {@link #result}
101  * property of this object may be examined to perform custom postprocessing.</div></li>
102  * </ul>
103  */
104 <div id="cfg-Ext.form.Action-scope"></div>/**
105  * @cfg {Object} scope The scope in which to call the callback functions (The <tt>this</tt> reference
106  * for the callback functions).
107  */
108 <div id="cfg-Ext.form.Action-waitMsg"></div>/**
109  * @cfg {String} waitMsg The message to be displayed by a call to {@link Ext.MessageBox#wait}
110  * during the time the action is being processed.
111  */
112 <div id="cfg-Ext.form.Action-waitTitle"></div>/**
113  * @cfg {String} waitTitle The title to be displayed by a call to {@link Ext.MessageBox#wait}
114  * during the time the action is being processed.
115  */
116
117 <div id="prop-Ext.form.Action-type"></div>/**
118  * The type of action this Action instance performs.
119  * Currently only "submit" and "load" are supported.
120  * @type {String}
121  */
122     type : 'default',
123 <div id="prop-Ext.form.Action-failureType"></div>/**
124  * The type of failure detected will be one of these: {@link #CLIENT_INVALID},
125  * {@link #SERVER_INVALID}, {@link #CONNECT_FAILURE}, or {@link #LOAD_FAILURE}.  Usage:
126  * <pre><code>
127 var fp = new Ext.form.FormPanel({
128 ...
129 buttons: [{
130     text: 'Save',
131     formBind: true,
132     handler: function(){
133         if(fp.getForm().isValid()){
134             fp.getForm().submit({
135                 url: 'form-submit.php',
136                 waitMsg: 'Submitting your data...',
137                 success: function(form, action){
138                     // server responded with success = true
139                     var result = action.{@link #result};
140                 },
141                 failure: function(form, action){
142                     if (action.{@link #failureType} === Ext.form.Action.{@link #CONNECT_FAILURE}) {
143                         Ext.Msg.alert('Error',
144                             'Status:'+action.{@link #response}.status+': '+
145                             action.{@link #response}.statusText);
146                     }
147                     if (action.failureType === Ext.form.Action.{@link #SERVER_INVALID}){
148                         // server responded with success = false
149                         Ext.Msg.alert('Invalid', action.{@link #result}.errormsg);
150                     }
151                 }
152             });
153         }
154     }
155 },{
156     text: 'Reset',
157     handler: function(){
158         fp.getForm().reset();
159     }
160 }]
161  * </code></pre>
162  * @property failureType
163  * @type {String}
164  */
165  <div id="prop-Ext.form.Action-response"></div>/**
166  * The XMLHttpRequest object used to perform the action.
167  * @property response
168  * @type {Object}
169  */
170  <div id="prop-Ext.form.Action-result"></div>/**
171  * The decoded response object containing a boolean <tt style="font-weight:bold">success</tt> property and
172  * other, action-specific properties.
173  * @property result
174  * @type {Object}
175  */
176
177     // interface method
178     run : function(options){
179
180     },
181
182     // interface method
183     success : function(response){
184
185     },
186
187     // interface method
188     handleResponse : function(response){
189
190     },
191
192     // default connection failure
193     failure : function(response){
194         this.response = response;
195         this.failureType = Ext.form.Action.CONNECT_FAILURE;
196         this.form.afterAction(this, false);
197     },
198
199     // private
200     // shared code among all Actions to validate that there was a response
201     // with either responseText or responseXml
202     processResponse : function(response){
203         this.response = response;
204         if(!response.responseText && !response.responseXML){
205             return true;
206         }
207         this.result = this.handleResponse(response);
208         return this.result;
209     },
210
211     // utility functions used internally
212     getUrl : function(appendParams){
213         var url = this.options.url || this.form.url || this.form.el.dom.action;
214         if(appendParams){
215             var p = this.getParams();
216             if(p){
217                 url = Ext.urlAppend(url, p);
218             }
219         }
220         return url;
221     },
222
223     // private
224     getMethod : function(){
225         return (this.options.method || this.form.method || this.form.el.dom.method || 'POST').toUpperCase();
226     },
227
228     // private
229     getParams : function(){
230         var bp = this.form.baseParams;
231         var p = this.options.params;
232         if(p){
233             if(typeof p == "object"){
234                 p = Ext.urlEncode(Ext.applyIf(p, bp));
235             }else if(typeof p == 'string' && bp){
236                 p += '&' + Ext.urlEncode(bp);
237             }
238         }else if(bp){
239             p = Ext.urlEncode(bp);
240         }
241         return p;
242     },
243
244     // private
245     createCallback : function(opts){
246         var opts = opts || {};
247         return {
248             success: this.success,
249             failure: this.failure,
250             scope: this,
251             timeout: (opts.timeout*1000) || (this.form.timeout*1000),
252             upload: this.form.fileUpload ? this.success : undefined
253         };
254     }
255 };
256
257 <div id="cls-Ext.form.Action.Submit"></div>/**
258  * @class Ext.form.Action.Submit
259  * @extends Ext.form.Action
260  * <p>A class which handles submission of data from {@link Ext.form.BasicForm Form}s
261  * and processes the returned response.</p>
262  * <p>Instances of this class are only created by a {@link Ext.form.BasicForm Form} when
263  * {@link Ext.form.BasicForm#submit submit}ting.</p>
264  * <p><u><b>Response Packet Criteria</b></u></p>
265  * <p>A response packet may contain:
266  * <div class="mdetail-params"><ul>
267  * <li><b><code>success</code></b> property : Boolean
268  * <div class="sub-desc">The <code>success</code> property is required.</div></li>
269  * <li><b><code>errors</code></b> property : Object
270  * <div class="sub-desc"><div class="sub-desc">The <code>errors</code> property,
271  * which is optional, contains error messages for invalid fields.</div></li>
272  * </ul></div>
273  * <p><u><b>JSON Packets</b></u></p>
274  * <p>By default, response packets are assumed to be JSON, so a typical response
275  * packet may look like this:</p><pre><code>
276 {
277     success: false,
278     errors: {
279         clientCode: "Client not found",
280         portOfLoading: "This field must not be null"
281     }
282 }</code></pre>
283  * <p>Other data may be placed into the response for processing by the {@link Ext.form.BasicForm}'s callback
284  * or event handler methods. The object decoded from this JSON is available in the
285  * {@link Ext.form.Action#result result} property.</p>
286  * <p>Alternatively, if an {@link #errorReader} is specified as an {@link Ext.data.XmlReader XmlReader}:</p><pre><code>
287     errorReader: new Ext.data.XmlReader({
288             record : 'field',
289             success: '@success'
290         }, [
291             'id', 'msg'
292         ]
293     )
294 </code></pre>
295  * <p>then the results may be sent back in XML format:</p><pre><code>
296 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
297 &lt;message success="false"&gt;
298 &lt;errors&gt;
299     &lt;field&gt;
300         &lt;id&gt;clientCode&lt;/id&gt;
301         &lt;msg&gt;&lt;![CDATA[Code not found. &lt;br /&gt;&lt;i&gt;This is a test validation message from the server &lt;/i&gt;]]&gt;&lt;/msg&gt;
302     &lt;/field&gt;
303     &lt;field&gt;
304         &lt;id&gt;portOfLoading&lt;/id&gt;
305         &lt;msg&gt;&lt;![CDATA[Port not found. &lt;br /&gt;&lt;i&gt;This is a test validation message from the server &lt;/i&gt;]]&gt;&lt;/msg&gt;
306     &lt;/field&gt;
307 &lt;/errors&gt;
308 &lt;/message&gt;
309 </code></pre>
310  * <p>Other elements may be placed into the response XML for processing by the {@link Ext.form.BasicForm}'s callback
311  * or event handler methods. The XML document is available in the {@link #errorReader}'s {@link Ext.data.XmlReader#xmlData xmlData} property.</p>
312  */
313 Ext.form.Action.Submit = function(form, options){
314     Ext.form.Action.Submit.superclass.constructor.call(this, form, options);
315 };
316
317 Ext.extend(Ext.form.Action.Submit, Ext.form.Action, {
318     <div id="cfg-Ext.form.Action.Submit-errorReader"></div>/**
319      * @cfg {Ext.data.DataReader} errorReader <p><b>Optional. JSON is interpreted with
320      * no need for an errorReader.</b></p>
321      * <p>A Reader which reads a single record from the returned data. The DataReader's
322      * <b>success</b> property specifies how submission success is determined. The Record's
323      * data provides the error messages to apply to any invalid form Fields.</p>
324      */
325     <div id="cfg-Ext.form.Action.Submit-clientValidation"></div>/**
326      * @cfg {boolean} clientValidation Determines whether a Form's fields are validated
327      * in a final call to {@link Ext.form.BasicForm#isValid isValid} prior to submission.
328      * Pass <tt>false</tt> in the Form's submit options to prevent this. If not defined, pre-submission field validation
329      * is performed.
330      */
331     type : 'submit',
332
333     // private
334     run : function(){
335         var o = this.options;
336         var method = this.getMethod();
337         var isGet = method == 'GET';
338         if(o.clientValidation === false || this.form.isValid()){
339             Ext.Ajax.request(Ext.apply(this.createCallback(o), {
340                 form:this.form.el.dom,
341                 url:this.getUrl(isGet),
342                 method: method,
343                 headers: o.headers,
344                 params:!isGet ? this.getParams() : null,
345                 isUpload: this.form.fileUpload
346             }));
347         }else if (o.clientValidation !== false){ // client validation failed
348             this.failureType = Ext.form.Action.CLIENT_INVALID;
349             this.form.afterAction(this, false);
350         }
351     },
352
353     // private
354     success : function(response){
355         var result = this.processResponse(response);
356         if(result === true || result.success){
357             this.form.afterAction(this, true);
358             return;
359         }
360         if(result.errors){
361             this.form.markInvalid(result.errors);
362             this.failureType = Ext.form.Action.SERVER_INVALID;
363         }
364         this.form.afterAction(this, false);
365     },
366
367     // private
368     handleResponse : function(response){
369         if(this.form.errorReader){
370             var rs = this.form.errorReader.read(response);
371             var errors = [];
372             if(rs.records){
373                 for(var i = 0, len = rs.records.length; i < len; i++) {
374                     var r = rs.records[i];
375                     errors[i] = r.data;
376                 }
377             }
378             if(errors.length < 1){
379                 errors = null;
380             }
381             return {
382                 success : rs.success,
383                 errors : errors
384             };
385         }
386         return Ext.decode(response.responseText);
387     }
388 });
389
390
391 <div id="cls-Ext.form.Action.Load"></div>/**
392  * @class Ext.form.Action.Load
393  * @extends Ext.form.Action
394  * <p>A class which handles loading of data from a server into the Fields of an {@link Ext.form.BasicForm}.</p>
395  * <p>Instances of this class are only created by a {@link Ext.form.BasicForm Form} when
396  * {@link Ext.form.BasicForm#load load}ing.</p>
397  * <p><u><b>Response Packet Criteria</b></u></p>
398  * <p>A response packet <b>must</b> contain:
399  * <div class="mdetail-params"><ul>
400  * <li><b><code>success</code></b> property : Boolean</li>
401  * <li><b><code>data</code></b> property : Object</li>
402  * <div class="sub-desc">The <code>data</code> property contains the values of Fields to load.
403  * The individual value object for each Field is passed to the Field's
404  * {@link Ext.form.Field#setValue setValue} method.</div></li>
405  * </ul></div>
406  * <p><u><b>JSON Packets</b></u></p>
407  * <p>By default, response packets are assumed to be JSON, so for the following form load call:<pre><code>
408 var myFormPanel = new Ext.form.FormPanel({
409     title: 'Client and routing info',
410     items: [{
411         fieldLabel: 'Client',
412         name: 'clientName'
413     }, {
414         fieldLabel: 'Port of loading',
415         name: 'portOfLoading'
416     }, {
417         fieldLabel: 'Port of discharge',
418         name: 'portOfDischarge'
419     }]
420 });
421 myFormPanel.{@link Ext.form.FormPanel#getForm getForm}().{@link Ext.form.BasicForm#load load}({
422     url: '/getRoutingInfo.php',
423     params: {
424         consignmentRef: myConsignmentRef
425     },
426     failure: function(form, action() {
427         Ext.Msg.alert("Load failed", action.result.errorMessage);
428     }
429 });
430 </code></pre>
431  * a <b>success response</b> packet may look like this:</p><pre><code>
432 {
433     success: true,
434     data: {
435         clientName: "Fred. Olsen Lines",
436         portOfLoading: "FXT",
437         portOfDischarge: "OSL"
438     }
439 }</code></pre>
440  * while a <b>failure response</b> packet may look like this:</p><pre><code>
441 {
442     success: false,
443     errorMessage: "Consignment reference not found"
444 }</code></pre>
445  * <p>Other data may be placed into the response for processing the {@link Ext.form.BasicForm Form}'s
446  * callback or event handler methods. The object decoded from this JSON is available in the
447  * {@link Ext.form.Action#result result} property.</p>
448  */
449 Ext.form.Action.Load = function(form, options){
450     Ext.form.Action.Load.superclass.constructor.call(this, form, options);
451     this.reader = this.form.reader;
452 };
453
454 Ext.extend(Ext.form.Action.Load, Ext.form.Action, {
455     // private
456     type : 'load',
457
458     // private
459     run : function(){
460         Ext.Ajax.request(Ext.apply(
461                 this.createCallback(this.options), {
462                     method:this.getMethod(),
463                     url:this.getUrl(false),
464                     headers: this.options.headers,
465                     params:this.getParams()
466         }));
467     },
468
469     // private
470     success : function(response){
471         var result = this.processResponse(response);
472         if(result === true || !result.success || !result.data){
473             this.failureType = Ext.form.Action.LOAD_FAILURE;
474             this.form.afterAction(this, false);
475             return;
476         }
477         this.form.clearInvalid();
478         this.form.setValues(result.data);
479         this.form.afterAction(this, true);
480     },
481
482     // private
483     handleResponse : function(response){
484         if(this.form.reader){
485             var rs = this.form.reader.read(response);
486             var data = rs.records && rs.records[0] ? rs.records[0].data : null;
487             return {
488                 success : rs.success,
489                 data : data
490             };
491         }
492         return Ext.decode(response.responseText);
493     }
494 });
495
496
497
498 <div id="cls-Ext.form.Action.DirectLoad"></div>/**
499  * @class Ext.form.Action.DirectLoad
500  * @extends Ext.form.Action.Load
501  * Provides Ext.direct support for loading form data. This example illustrates usage
502  * of Ext.Direct to load a submit a form through Ext.Direct.
503  * <pre><code>
504 var myFormPanel = new Ext.form.FormPanel({
505     // configs for FormPanel
506     title: 'Basic Information',
507     border: false,
508     padding: 10,
509     buttons:[{
510         text: 'Submit',
511         handler: function(){
512             basicInfo.getForm().submit({
513                 params: {
514                     uid: 5
515                 }
516             });
517         }
518     }],
519     
520     // configs apply to child items
521     defaults: {anchor: '100%'},
522     defaultType: 'textfield',
523     items: [
524         // form fields go here
525     ],
526     
527     // configs for BasicForm
528     api: {
529         load: Profile.getBasicInfo,
530         // The server-side must mark the submit handler as a 'formHandler'
531         submit: Profile.updateBasicInfo
532     },    
533     paramOrder: ['uid']
534 });
535
536 // load the form
537 myFormPanel.getForm().load({
538     params: {
539         uid: 5
540     }
541 });
542  * </code></pre>
543  */
544 Ext.form.Action.DirectLoad = Ext.extend(Ext.form.Action.Load, {
545     constructor: function(form, opts) {        
546         Ext.form.Action.DirectLoad.superclass.constructor.call(this, form, opts);
547     },
548     type: 'directload',
549     
550     run : function(){
551         var args = this.getParams();
552         args.push(this.success, this);                
553         this.form.api.load.apply(window, args);
554     },
555     
556     getParams: function() {
557         var buf = [], o = {};
558         var bp = this.form.baseParams;
559         var p = this.options.params;
560         Ext.apply(o, p, bp);
561         var paramOrder = this.form.paramOrder;
562         if(paramOrder){
563             for(var i = 0, len = paramOrder.length; i < len; i++){
564                 buf.push(o[paramOrder[i]]);
565             }
566         }else if(this.form.paramsAsHash){
567             buf.push(o);
568         }
569         return buf;
570     },
571     // Direct actions have already been processed and therefore
572     // we can directly set the result; Direct Actions do not have
573     // a this.response property.
574     processResponse: function(result) {
575         this.result = result;
576         return result;          
577     }
578 });
579
580 <div id="cls-Ext.form.Action.DirectSubmit"></div>/**
581  * @class Ext.form.Action.DirectSubmit
582  * @extends Ext.form.Action.Submit
583  * Provides Ext.direct support for submitting form data.
584  * See {@link Ext.form.Action.DirectLoad}.
585  */
586 Ext.form.Action.DirectSubmit = Ext.extend(Ext.form.Action.Submit, {
587     constructor: function(form, opts) {
588         Ext.form.Action.DirectSubmit.superclass.constructor.call(this, form, opts);
589     },
590     type: 'directsubmit',
591     // override of Submit
592     run : function(){
593         var o = this.options;
594         if(o.clientValidation === false || this.form.isValid()){
595             // tag on any additional params to be posted in the
596             // form scope
597             this.success.params = this.getParams();
598             this.form.api.submit(this.form.el.dom, this.success, this);
599         }else if (o.clientValidation !== false){ // client validation failed
600             this.failureType = Ext.form.Action.CLIENT_INVALID;
601             this.form.afterAction(this, false);
602         }
603     },
604     
605     getParams: function() {
606         var o = {};
607         var bp = this.form.baseParams;
608         var p = this.options.params;
609         Ext.apply(o, p, bp);
610         return o;
611     },    
612     // Direct actions have already been processed and therefore
613     // we can directly set the result; Direct Actions do not have
614     // a this.response property.
615     processResponse: function(result) {
616         this.result = result;
617         return result;          
618     }
619 });
620
621
622 Ext.form.Action.ACTION_TYPES = {
623     'load' : Ext.form.Action.Load,
624     'submit' : Ext.form.Action.Submit,
625     'directload': Ext.form.Action.DirectLoad,
626     'directsubmit': Ext.form.Action.DirectSubmit
627 };
628 </pre>    \r
629 </body>\r
630 </html>