X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/ee06f37b0f6f6d94cd05a6ffae556660f7c4a2bc..c930e9176a5a85509c5b0230e2bff5c22a591432:/docs/source/BasicForm.html?ds=sidebyside diff --git a/docs/source/BasicForm.html b/docs/source/BasicForm.html new file mode 100644 index 00000000..66605289 --- /dev/null +++ b/docs/source/BasicForm.html @@ -0,0 +1,738 @@ + +
+/** + * @class Ext.form.BasicForm + * @extends Ext.util.Observable + *Encapsulates the DOM <form> element at the heart of the {@link Ext.form.FormPanel FormPanel} class, and provides + * input field management, validation, submission, and form loading services.
+ *By default, Ext Forms are submitted through Ajax, using an instance of {@link Ext.form.Action.Submit}. + * To enable normal browser submission of an Ext Form, use the {@link #standardSubmit} config option.
+ *File Uploads
+ *{@link #fileUpload File uploads} are not performed using Ajax submission, that + * is they are not performed using XMLHttpRequests. Instead the form is submitted in the standard + * manner with the DOM <form> element temporarily modified to have its + * target set to refer + * to a dynamically generated, hidden <iframe> which is inserted into the document + * but removed after the return data has been gathered.
+ *The server response is parsed by the browser to create the document for the IFRAME. If the + * server is using JSON to send the return object, then the + * Content-Type header + * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.
+ *Characters which are significant to an HTML parser must be sent as HTML entities, so encode + * "<" as "<", "&" as "&" etc.
+ *The response text is retrieved from the document, and a fake XMLHttpRequest object + * is created containing a responseText property in order to conform to the + * requirements of event handlers and callbacks.
+ *Be aware that file upload packets are sent with the content type multipart/form + * and some server technologies (notably JEE) may require some custom processing in order to + * retrieve parameter names and parameter values from the packet content.
+ * @constructor + * @param {Mixed} el The form element or its id + * @param {Object} config Configuration options + */ +Ext.form.BasicForm = function(el, config){ + Ext.apply(this, config); + if(Ext.isString(this.paramOrder)){ + this.paramOrder = this.paramOrder.split(/[\s,|]/); + } + /* + * @property items + * A {@link Ext.util.MixedCollection MixedCollection) containing all the Ext.form.Fields in this form. + * @type MixedCollection + */ + this.items = new Ext.util.MixedCollection(false, function(o){ + return o.itemId || o.id || (o.id = Ext.id()); + }); + this.addEvents( + /** + * @event beforeaction + * Fires before any action is performed. Return false to cancel the action. + * @param {Form} this + * @param {Action} action The {@link Ext.form.Action} to be performed + */ + 'beforeaction', + /** + * @event actionfailed + * Fires when an action fails. + * @param {Form} this + * @param {Action} action The {@link Ext.form.Action} that failed + */ + 'actionfailed', + /** + * @event actioncomplete + * Fires when an action is completed. + * @param {Form} this + * @param {Action} action The {@link Ext.form.Action} that completed + */ + 'actioncomplete' + ); + + if(el){ + this.initEl(el); + } + Ext.form.BasicForm.superclass.constructor.call(this); +}; + +Ext.extend(Ext.form.BasicForm, Ext.util.Observable, { + /** + * @cfg {String} method + * The request method to use (GET or POST) for form actions if one isn't supplied in the action options. + */ + /** + * @cfg {DataReader} reader + * An Ext.data.DataReader (e.g. {@link Ext.data.XmlReader}) to be used to read + * data when executing 'load' actions. This is optional as there is built-in + * support for processing JSON. For additional information on using an XMLReader + * see the example provided in examples/form/xml-form.html. + */ + /** + * @cfg {DataReader} errorReader + *An Ext.data.DataReader (e.g. {@link Ext.data.XmlReader}) to be used to + * read field error messages returned from 'submit' actions. This is optional + * as there is built-in support for processing JSON.
+ *The Records which provide messages for the invalid Fields must use the + * Field name (or id) as the Record ID, and must contain a field called 'msg' + * which contains the error message.
+ *The errorReader does not have to be a full-blown implementation of a + * DataReader. It simply needs to implement a read(xhr) function + * which returns an Array of Records in an object with the following + * structure:
+ */ + /** + * @cfg {String} url + * The URL to use for form actions if one isn't supplied in the + *+{ + records: recordArray +} +
{@link #doAction doAction} options
. + */ + /** + * @cfg {Boolean} fileUpload + * Set to true if this form is a file upload. + *File uploads are not performed using normal 'Ajax' techniques, that is they are not + * performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the + * DOM <form> element temporarily modified to have its + * target set to refer + * to a dynamically generated, hidden <iframe> which is inserted into the document + * but removed after the return data has been gathered.
+ *The server response is parsed by the browser to create the document for the IFRAME. If the + * server is using JSON to send the return object, then the + * Content-Type header + * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.
+ *Characters which are significant to an HTML parser must be sent as HTML entities, so encode + * "<" as "<", "&" as "&" etc.
+ *The response text is retrieved from the document, and a fake XMLHttpRequest object + * is created containing a responseText property in order to conform to the + * requirements of event handlers and callbacks.
+ *Be aware that file upload packets are sent with the content type multipart/form + * and some server technologies (notably JEE) may require some custom processing in order to + * retrieve parameter names and parameter values from the packet content.
+ */ + /** + * @cfg {Object} baseParams + *Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}.
+ *Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.
+ */ + /** + * @cfg {Number} timeout Timeout for form actions in seconds (default is 30 seconds). + */ + timeout: 30, + + /** + * @cfg {Object} api (Optional) If specified load and submit actions will be handled + * with {@link Ext.form.Action.DirectLoad} and {@link Ext.form.Action.DirectSubmit}. + * Methods which have been imported by Ext.Direct can be specified here to load and submit + * forms. + * Such as the following:+ *+api: { + load: App.ss.MyProfile.load, + submit: App.ss.MyProfile.submit +} +
Load actions can use
+ */ + + /** + * @cfg {Array/String} paramOrder{@link #paramOrder}
or{@link #paramsAsHash}
+ * to customize how the load method is invoked. + * Submit actions will always use a standard form submit. The formHandler configuration must + * be set on the associated server-side method which has been imported by Ext.DirectA list of params to be executed server side. + * Defaults to undefined. Only used for the
+ *{@link #api}
+ *load
configuration.Specify the params in the order in which they must be executed on the + * server-side as either (1) an Array of String values, or (2) a String of params + * delimited by either whitespace, comma, or pipe. For example, + * any of the following would be acceptable:
+ */ + paramOrder: undefined, + + /** + * @cfg {Boolean} paramsAsHash Only used for the+paramOrder: ['param1','param2','param3'] +paramOrder: 'param1 param2 param3' +paramOrder: 'param1,param2,param3' +paramOrder: 'param1|param2|param' +
{@link #api}
+ *load
configuration. Send parameters as a collection of named + * arguments (defaults to false). Providing a + * {@link #paramOrder} nullifies this configuration. + */ + paramsAsHash: false, + + + // private + activeAction : null, + + /** + * @cfg {Boolean} trackResetOnLoad If set to true, {@link #reset}() resets to the last loaded + * or {@link #setValues}() data instead of when the form was first created. Defaults to false. + */ + trackResetOnLoad : false, + + /** + * @cfg {Boolean} standardSubmit If set to true, standard HTML form submits are used instead of XHR (Ajax) style + * form submissions. (defaults to false)
+ *Note: When using standardSubmit, the options to {@link #submit} are ignored because Ext's + * Ajax infrastracture is bypassed. To pass extra parameters (baseParams and params), you will need to + * create hidden fields within the form.
+ *The url config option is also bypassed, so set the action as well:
+ *+ * An example encapsulating the above: + *+PANEL.getForm().getEl().dom.action = 'URL' + *
+ */ + /** + * By default wait messages are displayed with Ext.MessageBox.wait. You can target a specific + * element by passing it or its id or mask the form itself by passing in true. + * @type Mixed + * @property waitMsgTarget + */ + + // private + initEl : function(el){ + this.el = Ext.get(el); + this.id = this.el.id || Ext.id(); + if(!this.standardSubmit){ + this.el.on('submit', this.onSubmit, this); + } + this.el.addClass('x-form'); + }, + + /** + * Get the HTML form Element + * @return Ext.Element + */ + getEl: function(){ + return this.el; + }, + + // private + onSubmit : function(e){ + e.stopEvent(); + }, + + // private + destroy: function() { + this.items.each(function(f){ + Ext.destroy(f); + }); + if(this.el){ + this.el.removeAllListeners(); + this.el.remove(); + } + this.purgeListeners(); + }, + + /** + * Returns true if client-side validation on the form is successful. + * @return Boolean + */ + isValid : function(){ + var valid = true; + this.items.each(function(f){ + if(!f.validate()){ + valid = false; + } + }); + return valid; + }, + + /** + *+new Ext.FormPanel({ + standardSubmit: true, + baseParams: { + foo: 'bar' + }, + url: 'myProcess.php', + items: [{ + xtype: 'textfield', + name: 'userName' + }], + buttons: [{ + text: 'Save', + handler: function(){ + var O = this.ownerCt; + if (O.getForm().isValid()) { + if (O.url) + O.getForm().getEl().dom.action = O.url; + if (O.baseParams) { + for (i in O.baseParams) { + O.add({ + xtype: 'hidden', + name: i, + value: O.baseParams[i] + }) + } + O.doLayout(); + } + O.getForm().submit(); + } + } + }] +}); + *
Returns true if any fields in this form have changed from their original values.
+ *Note that if this BasicForm was configured with {@link #trackResetOnLoad} then the + * Fields' original values are updated when the values are loaded by {@link #setValues} + * or {@link #loadRecord}.
+ * @return Boolean + */ + isDirty : function(){ + var dirty = false; + this.items.each(function(f){ + if(f.isDirty()){ + dirty = true; + return false; + } + }); + return dirty; + }, + + /** + * Performs a predefined action ({@link Ext.form.Action.Submit} or + * {@link Ext.form.Action.Load}) or a custom extension of {@link Ext.form.Action} + * to perform application-specific processing. + * @param {String/Object} actionName The name of the predefined action type, + * or instance of {@link Ext.form.Action} to perform. + * @param {Object} options (optional) The options to pass to the {@link Ext.form.Action}. + * All of the config options listed below are supported by both the + * {@link Ext.form.Action.Submit submit} and {@link Ext.form.Action.Load load} + * actions unless otherwise noted (custom actions could also accept + * other config options):
The params to pass + * (defaults to the form's baseParams, or none if not defined)
+ *Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.
Note: this is ignored when using the {@link #standardSubmit} option.
+ *The following code:
+myFormPanel.getForm().submit({
+ clientValidation: true,
+ url: 'updateConsignment.php',
+ params: {
+ newStatus: 'delivered'
+ },
+ success: function(form, action) {
+ Ext.Msg.alert('Success', action.result.msg);
+ },
+ failure: function(form, action) {
+ switch (action.failureType) {
+ case Ext.form.Action.CLIENT_INVALID:
+ Ext.Msg.alert('Failure', 'Form fields may not be submitted with invalid values');
+ break;
+ case Ext.form.Action.CONNECT_FAILURE:
+ Ext.Msg.alert('Failure', 'Ajax communication failed');
+ break;
+ case Ext.form.Action.SERVER_INVALID:
+ Ext.Msg.alert('Failure', action.result.msg);
+ }
+ }
+});
+
+ * would process the following server response for a successful submission:
+{
+ "success":true, // note this is Boolean, not string
+ "msg":"Consignment updated"
+}
+
+ * and the following server response for a failed submission:
+{
+ "success":false, // note this is Boolean, not string
+ "msg":"You do not have permission to perform this operation"
+}
+
+ * @return {BasicForm} this
+ */
+ submit : function(options){
+ if(this.standardSubmit){
+ var v = this.isValid();
+ if(v){
+ this.el.dom.submit();
+ }
+ return v;
+ }
+ var submitAction = String.format('{0}submit', this.api ? 'direct' : '');
+ this.doAction(submitAction, options);
+ return this;
+ },
+
+ /**
+ * Shortcut to {@link #doAction do} a {@link Ext.form.Action.Load load action}.
+ * @param {Object} options The options to pass to the action (see {@link #doAction} for details)
+ * @return {BasicForm} this
+ */
+ load : function(options){
+ var loadAction = String.format('{0}load', this.api ? 'direct' : '');
+ this.doAction(loadAction, options);
+ return this;
+ },
+
+ /**
+ * Persists the values in this form into the passed {@link Ext.data.Record} object in a beginEdit/endEdit block.
+ * @param {Record} record The record to edit
+ * @return {BasicForm} this
+ */
+ updateRecord : function(record){
+ record.beginEdit();
+ var fs = record.fields;
+ fs.each(function(f){
+ var field = this.findField(f.name);
+ if(field){
+ record.set(f.name, field.getValue());
+ }
+ }, this);
+ record.endEdit();
+ return this;
+ },
+
+ /**
+ * Loads an {@link Ext.data.Record} into this form by calling {@link #setValues} with the
+ * {@link Ext.data.Record#data record data}.
+ * See also {@link #trackResetOnLoad}.
+ * @param {Record} record The record to load
+ * @return {BasicForm} this
+ */
+ loadRecord : function(record){
+ this.setValues(record.data);
+ return this;
+ },
+
+ // private
+ beforeAction : function(action){
+ var o = action.options;
+ if(o.waitMsg){
+ if(this.waitMsgTarget === true){
+ this.el.mask(o.waitMsg, 'x-mask-loading');
+ }else if(this.waitMsgTarget){
+ this.waitMsgTarget = Ext.get(this.waitMsgTarget);
+ this.waitMsgTarget.mask(o.waitMsg, 'x-mask-loading');
+ }else{
+ Ext.MessageBox.wait(o.waitMsg, o.waitTitle || this.waitTitle || 'Please Wait...');
+ }
+ }
+ },
+
+ // private
+ afterAction : function(action, success){
+ this.activeAction = null;
+ var o = action.options;
+ if(o.waitMsg){
+ if(this.waitMsgTarget === true){
+ this.el.unmask();
+ }else if(this.waitMsgTarget){
+ this.waitMsgTarget.unmask();
+ }else{
+ Ext.MessageBox.updateProgress(1);
+ Ext.MessageBox.hide();
+ }
+ }
+ if(success){
+ if(o.reset){
+ this.reset();
+ }
+ Ext.callback(o.success, o.scope, [this, action]);
+ this.fireEvent('actioncomplete', this, action);
+ }else{
+ Ext.callback(o.failure, o.scope, [this, action]);
+ this.fireEvent('actionfailed', this, action);
+ }
+ },
+
+ /**
+ * Find a {@link Ext.form.Field} in this form.
+ * @param {String} id The value to search for (specify either a {@link Ext.Component#id id},
+ * {@link Ext.grid.Column#dataIndex dataIndex}, {@link Ext.form.Field#getName name or hiddenName}).
+ * @return Field
+ */
+ findField : function(id){
+ var field = this.items.get(id);
+ if(!Ext.isObject(field)){
+ this.items.each(function(f){
+ if(f.isFormField && (f.dataIndex == id || f.id == id || f.getName() == id)){
+ field = f;
+ return false;
+ }
+ });
+ }
+ return field || null;
+ },
+
+
+ /**
+ * Mark fields in this form invalid in bulk.
+ * @param {Array/Object} errors Either an array in the form [{id:'fieldId', msg:'The message'},...] or an object hash of {id: msg, id2: msg2}
+ * @return {BasicForm} this
+ */
+ markInvalid : function(errors){
+ if(Ext.isArray(errors)){
+ for(var i = 0, len = errors.length; i < len; i++){
+ var fieldError = errors[i];
+ var f = this.findField(fieldError.id);
+ if(f){
+ f.markInvalid(fieldError.msg);
+ }
+ }
+ }else{
+ var field, id;
+ for(id in errors){
+ if(!Ext.isFunction(errors[id]) && (field = this.findField(id))){
+ field.markInvalid(errors[id]);
+ }
+ }
+ }
+ return this;
+ },
+
+ /**
+ * Set values for fields in this form in bulk.
+ * @param {Array/Object} values Either an array in the form:
+[{id:'clientName', value:'Fred. Olsen Lines'},
+ {id:'portOfLoading', value:'FXT'},
+ {id:'portOfDischarge', value:'OSL'} ]
+ * or an object hash of the form:
+{
+ clientName: 'Fred. Olsen Lines',
+ portOfLoading: 'FXT',
+ portOfDischarge: 'OSL'
+}
+ * @return {BasicForm} this
+ */
+ setValues : function(values){
+ if(Ext.isArray(values)){ // array of objects
+ for(var i = 0, len = values.length; i < len; i++){
+ var v = values[i];
+ var f = this.findField(v.id);
+ if(f){
+ f.setValue(v.value);
+ if(this.trackResetOnLoad){
+ f.originalValue = f.getValue();
+ }
+ }
+ }
+ }else{ // object hash
+ var field, id;
+ for(id in values){
+ if(!Ext.isFunction(values[id]) && (field = this.findField(id))){
+ field.setValue(values[id]);
+ if(this.trackResetOnLoad){
+ field.originalValue = field.getValue();
+ }
+ }
+ }
+ }
+ return this;
+ },
+
+ /**
+ * Returns the fields in this form as an object with key/value pairs as they would be submitted using a standard form submit. + * If multiple fields exist with the same name they are returned as an array.
+ *Note: The values are collected from all enabled HTML input elements within the form, not from + * the Ext Field objects. This means that all returned values are Strings (or Arrays of Strings) and that the + * value can potentially be the emptyText of a field.
+ * @param {Boolean} asString (optional) Pass true to return the values as a string. (defaults to false, returning an Object) + * @return {String/Object} + */ + getValues : function(asString){ + var fs = Ext.lib.Ajax.serializeForm(this.el.dom); + if(asString === true){ + return fs; + } + return Ext.urlDecode(fs); + }, + + getFieldValues : function(){ + var o = {}; + this.items.each(function(f){ + o[f.getName()] = f.getValue(); + }); + return o; + }, + + /** + * Clears all invalid messages in this form. + * @return {BasicForm} this + */ + clearInvalid : function(){ + this.items.each(function(f){ + f.clearInvalid(); + }); + return this; + }, + + /** + * Resets this form. + * @return {BasicForm} this + */ + reset : function(){ + this.items.each(function(f){ + f.reset(); + }); + return this; + }, + + /** + * Add Ext.form Components to this form's Collection. This does not result in rendering of + * the passed Component, it just enables the form to validate Fields, and distribute values to + * Fields. + *You will not usually call this function. In order to be rendered, a Field must be added + * to a {@link Ext.Container Container}, usually an {@link Ext.form.FormPanel FormPanel}. + * The FormPanel to which the field is added takes care of adding the Field to the BasicForm's + * collection.
+ * @param {Field} field1 + * @param {Field} field2 (optional) + * @param {Field} etc (optional) + * @return {BasicForm} this + */ + add : function(){ + this.items.addAll(Array.prototype.slice.call(arguments, 0)); + return this; + }, + + + /** + * Removes a field from the items collection (does NOT remove its markup). + * @param {Field} field + * @return {BasicForm} this + */ + remove : function(field){ + this.items.remove(field); + return this; + }, + + /** + * Iterates through the {@link Ext.form.Field Field}s which have been {@link #add add}ed to this BasicForm, + * checks them for an id attribute, and calls {@link Ext.form.Field#applyToMarkup} on the existing dom element with that id. + * @return {BasicForm} this + */ + render : function(){ + this.items.each(function(f){ + if(f.isFormField && !f.rendered && document.getElementById(f.id)){ // if the element exists + f.applyToMarkup(f.id); + } + }); + return this; + }, + + /** + * Calls {@link Ext#apply} for all fields in this form with the passed object. + * @param {Object} values + * @return {BasicForm} this + */ + applyToFields : function(o){ + this.items.each(function(f){ + Ext.apply(f, o); + }); + return this; + }, + + /** + * Calls {@link Ext#applyIf} for all field in this form with the passed object. + * @param {Object} values + * @return {BasicForm} this + */ + applyIfToFields : function(o){ + this.items.each(function(f){ + Ext.applyIf(f, o); + }); + return this; + }, + + callFieldMethod : function(fnName, args){ + args = args || []; + this.items.each(function(f){ + if(Ext.isFunction(f[fnName])){ + f[fnName].apply(f, args); + } + }); + return this; + } +}); + +// back compat +Ext.BasicForm = Ext.form.BasicForm; + + \ No newline at end of file