Provides input field management, validation, submission, and form loading services for the collection of Field instances within a Ext.form.FormPanel.
By default, Ext Forms are submitted through Ajax, using an instance of Ext.form.action.Submit. To enable normal browser submission of an Ext Form, use the standardSubmit config option.
Note: File uploads are not performed using normal 'Ajax' techniques; see the description for hasUpload for details.
api: {
load: App.ss.MyProfile.load,
submit: App.ss.MyProfile.submit
}
Load actions can use paramOrder
or 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.Direct.
Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}.
Parameters are encoded as standard HTTP parameters using Ext.urlEncode.
An Ext.data.DataReader (e.g. 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 responses.
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 Reader. It simply needs to implement a read(xhr) function which returns an Array of Records in an object with the following structure:
{
records: recordArray
}
A config object containing one or more event handlers to be added to this object during initialization. This should be a valid listeners config object as specified in the addListener example for attaching multiple handlers at once.
DOM events from ExtJs Components
While some ExtJs Component classes export selected DOM events (e.g. "click", "mouseover" etc), this
is usually only done when extra value can be added. For example the DataView's
click
event passing the node clicked on. To access DOM
events directly from a child element of a Component, we need to specify the element
option to
identify the Component property to add a DOM listener to:
new Ext.Panel({
width: 400,
height: 200,
dockedItems: [{
xtype: 'toolbar'
}],
listeners: {
click: {
element: 'el', //bind to the underlying el property on the panel
fn: function(){ console.log('click el'); }
},
dblclick: {
element: 'body', //bind to the underlying body property on the panel
fn: function(){ console.log('dblclick body'); }
}
}
});
A list of params to be executed server side.
Defaults to undefined. Only used for the 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: ['param1','param2','param3']
paramOrder: 'param1 param2 param3'
paramOrder: 'param1,param2,param3'
paramOrder: 'param1|param2|param'
api
load
configuration. If true, parameters will be sent as a
single hash collection of named arguments (defaults to false). Providing a
paramOrder nullifies this configuration.If set to true, a standard HTML form submit is used instead
of a XHR (Ajax) style form submission. Defaults to false. All of
the field values, plus any additional params configured via baseParams
and/or the options
to submit, will be included in the
values submitted in the form.
You will not usually call this function. In order to be rendered, a Field must be added to a Container, usually an FormPanel. The FormPanel to which the field is added takes care of adding the Field to the BasicForm's collection.
true
or the first event name string if multiple event names are being passed as separate parameters.this.addEvents('storeloaded', 'storecleared');
this
reference) in which the handler function is executed.
If omitted, defaults to the object which fired the event.this
reference) in which the handler function is executed.
If omitted, defaults to the object which fired the event.This option is useful during Component construction to add DOM event listeners to elements of Components which will exist only after the Component is rendered. For example, to add a click listener to a Panel's body:
new Ext.Panel({
title: 'The title',
listeners: {
click: this.handlePanelClick,
element: 'body'
}
});
When added in this way, the options available are the options applicable to Ext.core.Element.addListener
Combining Options
Using the options argument, it is possible to combine different types of listeners:
A delayed, one-time listener.
myPanel.on('hide', this.handleClick, this, {
single: true,
delay: 100
});
Attaching multiple handlers in 1 call
The method also allows for a single argument to be passed which is a config object containing properties
which specify multiple events. For example:
myGridPanel.on({
cellClick: this.onCellClick,
mouseover: this.onMouseOver,
mouseout: this.onMouseOut,
scope: this // Important. Ensure "this" is correct during handler execution
});
.
Adds listeners to any Observable object (or Element) which are automatically removed when this Component is destroyed.
ename
parameter was an event name, this
is the handler function.ename
parameter was an event name, this
is the scope (this
reference) in which the handler function is executed.ename
parameter was an event name, this
is the addListener options.this
reference) in which the handler function is executed.
If omitted, defaults to the object which fired the event.All of the config options listed below are supported by both the submit and 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 Ext.urlEncode.
Enables events fired by this Observable to bubble up an owner hierarchy by calling
this.getBubbleTarget()
if present. There is no implementation in the Observable base class.
This is commonly used by Ext.Components to bubble events to owner Containers. See Ext.Component.getBubbleTarget. The default implementation in Ext.Component returns the Component's immediate owner. But if a known target is required, this can be overridden to access the required target more quickly.
Example:
Ext.override(Ext.form.Field, {
// Add functionality to Field's initComponent to enable the change event to bubble
initComponent : Ext.Function.createSequence(Ext.form.Field.prototype.initComponent, function() {
this.enableBubble('change');
}),
// We know that we want Field's events to bubble directly to the FormPanel.
getBubbleTarget : function() {
if (!this.formPanel) {
this.formPanel = this.findParentByType('form');
}
return this.formPanel;
}
});
var myForm = new Ext.formPanel({
title: 'User Details',
items: [{
...
}],
listeners: {
change: function() {
// Title goes red if form has been modified.
myForm.header.setStyle('color', 'red');
}
}
});
Fires the specified event with the passed parameters (minus the event name).
An event may be set to bubble up an Observable parent hierarchy (See Ext.Component.getBubbleTarget) by calling enableBubble.
Returns true if the form contains a file upload field. This is used to determine the method for submitting the form: File uploads are not performed using normal 'Ajax' techniques, that is they are not performed using XMLHttpRequests. Instead a hidden <form> element containing all the fields is created temporarily and submitted with 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.
Returns true if any fields in this form have changed from their original values.
Note that if this BasicForm was configured with trackResetOnLoad then the Fields' original values are updated when the values are loaded by setValues or loadRecord.
[{id:'fieldId', msg:'The message'}, ...]
or an object hash of {id: msg, id2: msg2}
this
.ename
parameter was an event name, this
is the handler function.ename
parameter was an event name, this
is the scope (this
reference) in which the handler function is executed.queueSuspended
parameter, then all
events fired during event suspension will be sent to any listeners now.[{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'
}
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.Action.CLIENT_INVALID:
Ext.Msg.alert('Failure', 'Form fields may not be submitted with invalid values');
break;
case Ext.form.action.Action.CONNECT_FAILURE:
Ext.Msg.alert('Failure', 'Ajax communication failed');
break;
case Ext.form.action.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"
}