Properties

Methods

Events

Config Options

Direct Link

Observable
  BasicForm

Class CQ.Ext.form.BasicForm

Package:	CQ.Ext.form
Class:	BasicForm
Extends:	CQ.Ext.util.Observable
Clientlib:	cq.widgets

Encapsulates the DOM <form> element at the heart of the 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 CQ.Ext.form.Action.Submit. To enable normal browser submission of an Ext Form, use the standardSubmit config option.

File Uploads

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.

Config Options

Config Options		Defined By
	api : Object (Optional) If specified load and submit actions will be handled with CQ.Ext.form.Action.DirectLoad and CQ.Ext.form.Ac... (Optional) If specified load and submit actions will be handled with CQ.Ext.form.Action.DirectLoad and CQ.Ext.form.Action.DirectSubmit. Methods which have been imported by CQ.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 `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 CQ.Ext.Direct	BasicForm
	baseParams : Object Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}. Parameters are encoded as standard HT... Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}. Parameters are encoded as standard HTTP parameters using CQ.Ext.urlEncode.	BasicForm
	errorReader : DataReader An CQ.Ext.data.DataReader (e.g. CQ.Ext.data.XmlReader) to be used to read field error messages returned from 'submit'... An CQ.Ext.data.DataReader (e.g. CQ.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: `{ records: recordArray }`	BasicForm
	fileUpload : Boolean Set to true if this form is a file upload. File uploads are not performed using normal 'Ajax' techniques, that is the... 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.	BasicForm
	method : String The request method to use (GET or POST) for form actions if one isn't supplied in the action options.	BasicForm
	paramOrder : Array/String A list of params to be executed server side. Defaults to undefined. Only used for the api load configuration. Specify... 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'`	BasicForm
	paramsAsHash : Boolean Only used for the api load configuration. Send parameters as a collection of named arguments (defaults to false). Pro... Only used for the `api` `load` configuration. Send parameters as a collection of named arguments (defaults to `false`). Providing a `paramOrder` nullifies this configuration.	BasicForm
	reader : DataReader An CQ.Ext.data.DataReader (e.g. CQ.Ext.data.XmlReader) to be used to read data when executing 'load' actions. This is... An CQ.Ext.data.DataReader (e.g. CQ.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.	BasicForm
	standardSubmit : Boolean If set to true, standard HTML form submits are used instead of XHR (Ajax) style form submissions. Defaults to false. ... 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 `submit` are ignored because Ext's Ajax infrastracture is bypassed. To pass extra parameters (e.g. `baseParams` and `params`), utilize hidden fields to submit extra data, for example: new CQ.Ext.FormPanel({ standardSubmit: true, baseParams: { foo: 'bar' }, url: 'myProcess.php', items: [{ xtype: 'textfield', name: 'userName' }], buttons: [{ text: 'Save', handler: function(){ var fp = this.ownerCt.ownerCt, form = fp.getForm(); if (form.isValid()) { // check if there are baseParams and if // hiddent items have been added already if (fp.baseParams && !fp.paramsAdded) { // add hidden items for all baseParams for (i in fp.baseParams) { fp.add({ xtype: 'hidden', name: i, value: fp.baseParams[i] }); } fp.doLayout(); // set a custom flag to prevent re-adding fp.paramsAdded = true; } form.submit(); } } }] });	BasicForm
	timeout : Number Timeout for form actions in seconds (defaults to CQ.REQUEST_TIMEOUT divided by 1000). Timeout for form actions in seconds (defaults to CQ.REQUEST_TIMEOUT divided by 1000).	BasicForm
	trackResetOnLoad : Boolean If set to true, reset() resets to the last loaded or setValues() data instead of when the form was first created. Def... If set to `true`, reset() resets to the last loaded or setValues() data instead of when the form was first created. Defaults to `false`.	BasicForm
	url : String The URL to use for form actions if one isn't supplied in the doAction options. The URL to use for form actions if one isn't supplied in the `doAction options`.	BasicForm
	waitTitle : String The default title to show for the waiting message box (defaults to 'Please Wait...') The default title to show for the waiting message box (defaults to `'Please Wait...'`)	BasicForm

Public Properties

Property		Defined By
	items : MixedCollection A MixedCollection containing all the CQ.Ext.form.Fields in this form.	BasicForm
	waitMsgTarget : Mixed By default wait messages are displayed with CQ.Ext.MessageBox.wait. You can target a specific element by passing it ... By default wait messages are displayed with CQ.Ext.MessageBox.wait. You can target a specific element by passing it or its id or mask the form itself by passing in true.	BasicForm

Public Methods

Method		Defined By
	BasicForm( `Mixed el`, `Object config` ) Parameters: `el` : Mixed The form element or its id `config` : Object Configuration options Returns:	BasicForm
	add( `Field field1`, [`Field field2`], [`Field etc`] ) : BasicForm Add CQ.Ext.form Components to this form's Collection. This does not result in rendering of the passed Component, it j... Add CQ.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 Container, usually an FormPanel. The FormPanel to which the field is added takes care of adding the Field to the BasicForm's collection. Parameters: `field1` : Field `field2` : Field (optional) `etc` : Field (optional) Returns: `BasicForm` this	BasicForm
	applyIfToFields( `Object values` ) : BasicForm Calls CQ.Ext.applyIf for all field in this form with the passed object. Calls CQ.Ext.applyIf for all field in this form with the passed object. Parameters: `values` : Object Returns: `BasicForm` this	BasicForm
	applyToFields( `Object values` ) : BasicForm Calls CQ.Ext.apply for all fields in this form with the passed object. Calls CQ.Ext.apply for all fields in this form with the passed object. Parameters: `values` : Object Returns: `BasicForm` this	BasicForm
	cleanDestroyed() : void Removes all fields from the collection that have been destroyed. Removes all fields from the collection that have been destroyed. Parameters: None. Returns: `void`	BasicForm
	clearInvalid() : BasicForm Clears all invalid messages in this form. Clears all invalid messages in this form. Parameters: None. Returns: `BasicForm` this	BasicForm
	doAction( `String/Object actionName`, [`Object options`] ) : BasicForm Performs a predefined action (CQ.Ext.form.Action.Submit or CQ.Ext.form.Action.Load) or a custom extension of CQ.Ext.f... Performs a predefined action (CQ.Ext.form.Action.Submit or CQ.Ext.form.Action.Load) or a custom extension of CQ.Ext.form.Action to perform application-specific processing. Parameters: `actionName` : String/Object The name of the predefined action type, or instance of CQ.Ext.form.Action to perform. `options` : Object (optional) The options to pass to the CQ.Ext.form.Action. 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): url : String The url for the action (defaults to the form's url.) method : String The form method to use (defaults to the form's method, or POST if not defined) params : String/Object The params to pass (defaults to the form's baseParams, or none if not defined) Parameters are encoded as standard HTTP parameters using CQ.Ext.urlEncode. headers : Object Request headers to set for the action (defaults to the form's default headers) success : Function The callback that will be invoked after a successful response (see top of submit and load for a description of what constitutes a successful response). The function is passed the following parameters: `form` : CQ.Ext.form.BasicForm The form that requested the action `action` : The Action object which performed the operation. The action object contains these properties of interest: `response` `result` : interrogate for custom postprocessing `type` failure : Function The callback that will be invoked after a failed transaction attempt. The function is passed the following parameters: `form` : The CQ.Ext.form.BasicForm that requested the action. `action` : The Action object which performed the operation. The action object contains these properties of interest: `failureType` `response` `result` : interrogate for custom postprocessing `type` scope : Object The scope in which to call the callback functions (The `this` reference for the callback functions). clientValidation : Boolean Submit Action only. Determines whether a Form's fields are validated in a final call to isValid prior to submission. Set to `false` to prevent this. If undefined, pre-submission field validation is performed. Returns: `BasicForm` this	BasicForm
	enableBubble( `String/Array events` ) : void Enables events fired by this Observable to bubble up an owner hierarchy by calling this.getBubbleTarget() if present.... 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 CQ.Ext.Components to bubble events to owner Containers. See CQ.Ext.Component.getBubbleTarget. The default implementation in CQ.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: CQ.Ext.override(CQ.Ext.form.Field, { // Add functionality to Field's initComponent to enable the change event to bubble initComponent : CQ.Ext.form.Field.prototype.initComponent.createSequence(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 CQ.Ext.formPanel({ title: 'User Details', items: [{ ... }], listeners: { change: function() { // Title goes red if form has been modified. myForm.header.setStyle('color', 'red'); } } }); Parameters: `events` : String/Array The event name to bubble, or an Array of event names. Returns: `void`	Observable
	findField( `String id` ) : Field Find a CQ.Ext.form.Field in this form. Find a CQ.Ext.form.Field in this form. Parameters: `id` : String The value to search for (specify either a id, dataIndex, name or hiddenName). Returns: `Field`	BasicForm
	getEl() : CQ.Ext.Element Get the HTML form Element Get the HTML form Element Parameters: None. Returns: `CQ.Ext.Element`	BasicForm
	getFieldValues( [`Boolean dirtyOnly`] ) : Object Retrieves the fields in the form as a set of key/value pairs, using the getValue() method. If multiple fields exist w... Retrieves the fields in the form as a set of key/value pairs, using the getValue() method. If multiple fields exist with the same name they are returned as an array. Parameters: `dirtyOnly` : Boolean (optional) True to return only fields that are dirty. Returns: `Object` The values in the form	BasicForm
	getValues( [`Boolean asString`] ) : String/Object Returns the fields in this form as an object with key/value pairs as they would be submitted using a standard form su... 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. Parameters: `asString` : Boolean (optional) Pass true to return the values as a string. (defaults to false, returning an Object) Returns: `String/Object`	BasicForm
	isDirty() : Boolean Returns true if any fields in this form have changed from their original values. Note that if this BasicForm was conf... 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. Parameters: None. Returns: `Boolean`	BasicForm
	isValid() : Boolean Returns true if client-side validation on the form is successful. Returns true if client-side validation on the form is successful. Parameters: None. Returns: `Boolean`	BasicForm
	load( `Object options` ) : BasicForm Shortcut to do a load action. Shortcut to do a load action. Parameters: `options` : Object The options to pass to the action (see doAction for details) Returns: `BasicForm` this	BasicForm
	loadRecord( `Record record` ) : BasicForm Loads an CQ.Ext.data.Record into this form by calling setValues with the record data. See also trackResetOnLoad. Loads an CQ.Ext.data.Record into this form by calling setValues with the record data. See also trackResetOnLoad. Parameters: `record` : Record The record to load Returns: `BasicForm` this	BasicForm
	markInvalid( `Array/Object errors` ) : BasicForm Mark fields in this form invalid in bulk. Mark fields in this form invalid in bulk. Parameters: `errors` : Array/Object Either an array in the form [{id:'fieldId', msg:'The message'},...] or an object hash of {id: msg, id2: msg2} Returns: `BasicForm` this	BasicForm
	relayEvents( `Object o`, `Array events` ) : void Relays selected events from the specified Observable as if the events were fired by `this`. Relays selected events from the specified Observable as if the events were fired by `this`. Parameters: `o` : Object The Observable whose events this object is to relay. `events` : Array Array of event names to relay. Returns: `void`	Observable
	remove( `Field field` ) : BasicForm Removes a field from the items collection (does NOT remove its markup). Removes a field from the items collection (does NOT remove its markup). Parameters: `field` : Field Returns: `BasicForm` this	BasicForm
	render() : BasicForm Iterates through the Fields which have been added to this BasicForm, checks them for an id attribute, and calls CQ.Ex... Iterates through the Fields which have been added to this BasicForm, checks them for an id attribute, and calls CQ.Ext.form.Field.applyToMarkup on the existing dom element with that id. Parameters: None. Returns: `BasicForm` this	BasicForm
	reset() : BasicForm Resets this form. Resets this form. Parameters: None. Returns: `BasicForm` this	BasicForm
	setValues( `Array/Object values` ) : BasicForm Set values for fields in this form in bulk. Set values for fields in this form in bulk. Parameters: `values` : Array/Object 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' }` Returns: `BasicForm` this	BasicForm
	submit( `Object options` ) : BasicForm Shortcut to do a submit action. Shortcut to do a submit action. Parameters: `options` : Object The options to pass to the action (see doAction for details). Note: this is ignored when using the standardSubmit option. The following code: myFormPanel.getForm().submit({ clientValidation: true, url: 'updateConsignment.php', params: { newStatus: 'delivered' }, success: function(form, action) { CQ.Ext.Msg.alert('Success', action.result.msg); }, failure: function(form, action) { switch (action.failureType) { case CQ.Ext.form.Action.CLIENT_INVALID: CQ.Ext.Msg.alert('Failure', 'Form fields may not be submitted with invalid values'); break; case CQ.Ext.form.Action.CONNECT_FAILURE: CQ.Ext.Msg.alert('Failure', 'Ajax communication failed'); break; case CQ.Ext.form.Action.SERVER_INVALID: CQ.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" }` Returns: `BasicForm` this	BasicForm
	updateRecord( `Record record` ) : BasicForm Persists the values in this form into the passed CQ.Ext.data.Record object in a beginEdit/endEdit block. Persists the values in this form into the passed CQ.Ext.data.Record object in a beginEdit/endEdit block. Parameters: `record` : Record The record to edit Returns: `BasicForm` this	BasicForm

Public Events

Event		Defined By
	actioncomplete : ( `Form this`, `Action action` ) Fires when an action is completed. Fires when an action is completed. Listeners will be called with the following arguments: `this` : Form `action` : Action The CQ.Ext.form.Action that completed	BasicForm
	actionfailed : ( `Form this`, `Action action` ) Fires when an action fails. Fires when an action fails. Listeners will be called with the following arguments: `this` : Form `action` : Action The CQ.Ext.form.Action that failed	BasicForm
	beforeaction : ( `Form this`, `Action action` ) Fires before any action is performed. Return false to cancel the action. Fires before any action is performed. Return false to cancel the action. Listeners will be called with the following arguments: `this` : Form `action` : Action The CQ.Ext.form.Action to be performed	BasicForm