Print Friendly

# Class Ext.form.Form

Package: | Ext.form
Class: | Form
Extends: | BasicForm
Defined In: | Form.js

Adds the ability to dynamically render forms with JavaScript to Ext.form.BasicForm.
Properties - Methods - Events - Config Options

## Public Properties

Property | Defined By
--- | ---
| buttons : Array | Form
Array of all the buttons that have been added to this form via addButton
| waitMsgTarget : Mixed | BasicForm
By default wait messages are displayed with Ext.MessageBox.wait. You can target a specific element by passing it or i...

## Public Methods

Method | Defined By
--- | ---
| Form( `Object config` ) | Form
| add( `Field field1`, [`Field field2`], [`Field etc.`] ) : Form | Form
Add Ext.form components to the current open container (e.g. column, fieldset, etc.). Fields added via this method ca...
| addButton( `String/Object config`, `Function handler`, [`Object scope`] ) : Ext.Button | Form
Adds a button to the footer of the form - this must be called before the form is rendered.
| addEvents( `Object object` ) : void | Observable
Used to define events on this Observable
| addListener( `String eventName`, `Function handler`, [`Object scope`], [`Object options`] ) : void | Observable
Appends an event handler to this component
| applyIfToFields( `Object values` ) : BasicForm | BasicForm
Calls Ext.applyIf for all field in this form with the passed object.
| applyToFields( `Object values` ) : BasicForm | BasicForm
Calls Ext.apply for all fields in this form with the passed object.
| clearInvalid() : BasicForm | BasicForm
Clears all invalid messages in this form.
| column( `Object config`, [`Field field1`], [`Field field2`], [`Field etc`] ) : Column | Form
Opens a new Ext.form.Column container in the layout stack. If fields are passed after the config, the fields are adde...
| container( `Object config`, [`Field field1`], [`Field field2`], [`Field etc`] ) : Layout | Form
Opens a new Ext.form.Layout container in the layout stack. If fields are passed after the config, the fields are adde...
| doAction( `String actionName`, `Object options` ) : BasicForm | BasicForm
Performs a predefined action (submit or load) or custom actions you define on this form.
| end() : Form | Form
Closes the current open container
| fieldset( `Object config`, [`Field field1`], [`Field field2`], [`Field etc`] ) : FieldSet | Form
Opens a new Ext.form.FieldSet container in the layout stack. If fields are passed after the config, the fields are ad...
| findField( `String id` ) : Field | BasicForm
Find a Ext.form.Field in this form by id, dataIndex, name or hiddenName
| fireEvent( `String eventName`, `Object... args` ) : Boolean | Observable
Fires the specified event with the passed parameters (minus the event name).
| getValues( `Boolean asString` ) : Object | BasicForm
Returns the fields in this form as an object with key/value pairs. If multiple fields exist with the same name they a...
| hasListener( `String eventName` ) : Boolean | Observable
Checks to see if this object has any listeners for a specified event
| isDirty() : Boolean | BasicForm
Returns true if any fields in this form have changed since their original load.
| isValid() : Boolean | BasicForm
Returns true if client-side validation on the form is successful.
| load( `Object options` ) : BasicForm | BasicForm
Shortcut to do a load action.
| loadRecord( `Record record` ) : BasicForm | BasicForm
Loads an Ext.data.Record into this form.
| markInvalid( `Array/Object errors` ) : BasicForm | BasicForm
Mark fields in this form invalid in bulk.
| on( `String eventName`, `Function handler`, [`Object scope`], [`Object options`] ) : void | Observable
Appends an event handler to this element (shorthand for addListener)
| purgeListeners() : void | Observable
Removes all listeners for this object
| remove( `Field field` ) : BasicForm | BasicForm
Removes a field from the items collection (does NOT remove its markup).
| removeListener( `String eventName`, `Function handler`, [`Object scope`] ) : void | Observable
Removes a listener
| render( `String/HTMLElement/Element container` ) : Form | Form
Render this form into the passed container. This should only be called once!
| reset() : BasicForm | BasicForm
Resets this form.
| setValues( `Array/Object values` ) : BasicForm | BasicForm
Set values for fields in this form in bulk.
| start( `Object container` ) : Form | Form
Opens the passed container in the layout stack. The container can be any Ext.form.Layout or subclass.
| startMonitoring() : void | Form
Starts monitoring of the valid state of this form. Usually this is done by passing the config option "monitorValid"
| stopMonitoring() : void | Form
Stops monitoring of the valid state of this form
| submit( `Object options` ) : BasicForm | BasicForm
Shortcut to do a submit action.
| un( `String eventName`, `Function handler`, [`Object scope`] ) : void | Observable
Removes a listener (shorthand for removeListener)
| updateRecord( `Record record` ) : BasicForm | BasicForm
Persists the values in this form into the passed Ext.data.Record object in a beginEdit/endEdit block.

## Public Events

Event | Defined By
--- | ---
| actioncomplete : ( `Form this`, `Action action` ) | BasicForm
Fires when an action is completed.
| actionfailed : ( `Form this`, `Action action` ) | BasicForm
Fires when an action fails.
| beforeaction : ( `Form this`, `Action action` ) | BasicForm
Fires before any action is performed. Return false to cancel the action.
| clientvalidation : ( `Form this`, `Boolean valid` ) | Form
If the monitorValid config option is true, this event fires repetitively to notify of valid state

## Config Options

Config Options | Defined By
--- | ---
| baseParams : Object | BasicForm
Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}.
| buttonAlign : String | Form
Valid values are "left," "center" and "right" (defaults to "center")
| errorReader : DataReader | BasicForm
An Ext.data.DataReader (e.g. Ext.data.XmlReader) to be used to read data when reading validation errors on "submit" a...
| fileUpload : Boolean | BasicForm
Set to true if this form is a file upload.
| itemCls : String | Form
A css class to apply to the x-form-item of fields. This property cascades to child containers.
| labelAlign : String | Form
Valid values are "left," "top" and "right" (defaults to "left"). This property cascades to child containers if not set.
| labelWidth : Number | Form
The width of labels. This property cascades to child containers.
| method : String | BasicForm
The request method to use (GET or POST) for form actions if one isn't supplied in the action options.
| minButtonWidth : Number | Form
Minimum width of all buttons in pixels (defaults to 75)
| monitorPoll : Number | Form
The milliseconds to poll valid state, ignored if monitorValid is not true (defaults to 200)
| monitorValid : Boolean | Form
If true the form monitors its valid state client-side and fires a looping event with that state. This is required to ...
| reader : DataReader | BasicForm
An Ext.data.DataReader (e.g. Ext.data.XmlReader) to be used to read data when executing "load" actions. This is optio...
| timeout : Number | BasicForm
Timeout for form actions in seconds (default is 30 seconds).
| trackResetOnLoad : Boolean | BasicForm
If set to true, form.reset() resets to the last loaded or setValues() data instead of when the form was first created.
| url : String | BasicForm
The URL to use for form actions if one isn't supplied in the action options.

## Property Details

### buttons

`public Array buttons`
Array of all the buttons that have been added to this form via addButton
This property is defined by Form.

### waitMsgTarget

`public Mixed waitMsgTarget`
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.
This property is defined by BasicForm.

## Constructor Details

### Form

`public function Form( `Object config` )`
Parameters:

- `config` : Object
  Configuration options

## Method Details

### add

`public function add( `Field field1`, [`Field field2`], [`Field etc.`] )`
Add Ext.form components to the current open container (e.g. column, fieldset, etc.). Fields added via this method can also be passed with an additional property of fieldLabel, which if supplied, will provide the text to display as the label of the field.
Parameters:

- `field1` : Field
- `field2` : Field
  (optional)
- `etc.` : Field
  (optional)

Returns:

- `Form`
  this

This method is defined by Form.

### addButton

`public function addButton( `String/Object config`, `Function handler`, [`Object scope`] )`
Adds a button to the footer of the form - this must be called before the form is rendered.
Parameters:

- `config` : String/Object
  A string becomes the button text, an object can either be a Button config object or a valid Ext.DomHelper element config
- `handler` : Function
  The function called when the button is clicked
- `scope` : Object
  (optional) The scope of the handler function

Returns:

- `Ext.Button`

This method is defined by Form.

### addEvents

`public function addEvents( `Object object` )`
Used to define events on this Observable
Parameters:

- `object` : Object
  The object with the events defined

Returns:

- `void`

This method is defined by Observable.

### addListener

`public function addListener( `String eventName`, `Function handler`, [`Object scope`], [`Object options`] )`
Appends an event handler to this component
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `scope` : Object
  (optional) The scope in which to execute the handler function. The handler function's "this" context.
- `options` : Object
  (optional) An object containing handler configuration properties. This may contain any of the following properties:
  - scope {Object} The scope in which to execute the handler function. The handler function's "this" context.
  - delay {Number} The number of milliseconds to delay the invocation of the handler after te event fires.
  - single {Boolean} True to add a handler to handle just the next firing of the event, and then remove itself.
  - buffer {Number} Causes the handler to be scheduled to run in an Ext.util.DelayedTask delayed by the specified number of milliseconds. If the event fires again within that time, the original handler is not invoked, but the new handler is scheduled in its place.

  Combining Options
  Using the options argument, it is possible to combine different types of listeners:
  A normalized, delayed, one-time listener that auto stops the event and passes a custom argument (forumId)

      el.on('click', this.onClick, this, {
       			single: true,
          		delay: 100,
          		forumId: 4
      		});

  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 handlers.

      el.on({
      			'click': {
              		fn: this.onClick,
              		scope: this,
              		delay: 100
          		},
          		'mouseover': {
              		fn: this.onMouseOver,
              		scope: this
          		},
          		'mouseout': {
              		fn: this.onMouseOut,
              		scope: this
          		}
      		});

  Or a shorthand syntax which passes the same scope object to all handlers:

      el.on({
      			'click': this.onClick,
          		'mouseover': this.onMouseOver,
          		'mouseout': this.onMouseOut,
          		scope: this
      		});

Returns:

- `void`

This method is defined by Observable.

### applyIfToFields

`public function applyIfToFields( `Object values` )`
Calls Ext.applyIf for all field in this form with the passed object.
Parameters:

- `values` : Object

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### applyToFields

`public function applyToFields( `Object values` )`
Calls Ext.apply for all fields in this form with the passed object.
Parameters:

- `values` : Object

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### clearInvalid

`public function clearInvalid()`
Clears all invalid messages in this form.
Parameters:

- None.

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### column

`public function column( `Object config`, [`Field field1`], [`Field field2`], [`Field etc`] )`
Opens a new Ext.form.Column container in the layout stack. If fields are passed after the config, the fields are added and the column is closed. If no fields are passed the column remains open until end() is called.
Parameters:

- `config` : Object
  The config to pass to the column
- `field1` : Field
  (optional)
- `field2` : Field
  (optional)
- `etc` : Field
  (optional)

Returns:

- `Column`
  The column container object

This method is defined by Form.

### container

`public function container( `Object config`, [`Field field1`], [`Field field2`], [`Field etc`] )`
Opens a new Ext.form.Layout container in the layout stack. If fields are passed after the config, the fields are added and the container is closed. If no fields are passed the container remains open until end() is called.
Parameters:

- `config` : Object
  The config to pass to the Layout
- `field1` : Field
  (optional)
- `field2` : Field
  (optional)
- `etc` : Field
  (optional)

Returns:

- `Layout`
  The container object

This method is defined by Form.

### doAction

`public function doAction( `String actionName`, `Object options` )`
Performs a predefined action (submit or load) or custom actions you define on this form.
Parameters:

- `actionName` : String
  The name of the action type
- `options` : Object
  The options to pass to the action

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### end

`public function end()`
Closes the current open container
Parameters:

- None.

Returns:

- `Form`
  this

This method is defined by Form.

### fieldset

`public function fieldset( `Object config`, [`Field field1`], [`Field field2`], [`Field etc`] )`
Opens a new Ext.form.FieldSet container in the layout stack. If fields are passed after the config, the fields are added and the fieldset is closed. If no fields are passed the fieldset remains open until end() is called.
Parameters:

- `config` : Object
  The config to pass to the fieldset
- `field1` : Field
  (optional)
- `field2` : Field
  (optional)
- `etc` : Field
  (optional)

Returns:

- `FieldSet`
  The fieldset container object

This method is defined by Form.

### findField

`public function findField( `String id` )`
Find a Ext.form.Field in this form by id, dataIndex, name or hiddenName
Parameters:

- `id` : String
  The value to search for

Returns:

- `Field`

This method is defined by BasicForm.

### fireEvent

`public function fireEvent( `String eventName`, `Object... args` )`
Fires the specified event with the passed parameters (minus the event name).
Parameters:

- `eventName` : String
- `args` : Object...
  Variable number of parameters are passed to handlers

Returns:

- `Boolean`
  returns false if any of the handlers return false otherwise it returns true

This method is defined by Observable.

### getValues

`public function getValues( `Boolean asString` )`
Returns the fields in this form as an object with key/value pairs. If multiple fields exist with the same name they are returned as an array.
Parameters:

- `asString` : Boolean

Returns:

- `Object`

This method is defined by BasicForm.

### hasListener

`public function hasListener( `String eventName` )`
Checks to see if this object has any listeners for a specified event
Parameters:

- `eventName` : String
  The name of the event to check for

Returns:

- `Boolean`
  True if the event is being listened for, else false

This method is defined by Observable.

### isDirty

`public function isDirty()`
Returns true if any fields in this form have changed since their original load.
Parameters:

- None.

Returns:

- `Boolean`

This method is defined by BasicForm.

### isValid

`public function isValid()`
Returns true if client-side validation on the form is successful.
Parameters:

- None.

Returns:

- `Boolean`

This method is defined by BasicForm.

### load

`public function load( `Object options` )`
Shortcut to do a load action.
Parameters:

- `options` : Object
  The options to pass to the action

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### loadRecord

`public function loadRecord( `Record record` )`
Loads an Ext.data.Record into this form.
Parameters:

- `record` : Record
  The record to load

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### markInvalid

`public function markInvalid( `Array/Object errors` )`
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

This method is defined by BasicForm.

### on

`public function on( `String eventName`, `Function handler`, [`Object scope`], [`Object options`] )`
Appends an event handler to this element (shorthand for addListener)
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `scope` : Object
  (optional) The scope in which to execute the handler function. The handler function's "this" context.
- `options` : Object
  (optional)

Returns:

- `void`

This method is defined by Observable.

### purgeListeners

`public function purgeListeners()`
Removes all listeners for this object
Parameters:

- None.

Returns:

- `void`

This method is defined by Observable.

### remove

`public function remove( `Field field` )`
Removes a field from the items collection (does NOT remove its markup).
Parameters:

- `field` : Field

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### removeListener

`public function removeListener( `String eventName`, `Function handler`, [`Object scope`] )`
Removes a listener
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

### render

`public function render( `String/HTMLElement/Element container` )`
Render this form into the passed container. This should only be called once!
Parameters:

- `container` : String/HTMLElement/Element
  The element this component should be rendered into

Returns:

- `Form`
  this

This method is defined by Form.

### reset

`public function reset()`
Resets this form.
Parameters:

- None.

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### setValues

`public function setValues( `Array/Object values` )`
Set values for fields in this form in bulk.
Parameters:

- `values` : Array/Object
  Either an array in the form [{id:'fieldId', value:'foo'},...] or an object hash of {id: value, id2: value2}

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### start

`public function start( `Object container` )`
Opens the passed container in the layout stack. The container can be any Ext.form.Layout or subclass.
Parameters:

- `container` : Object
  A Ext.form.Layout or subclass of Layout

Returns:

- `Form`
  this

This method is defined by Form.

### startMonitoring

`public function startMonitoring()`
Starts monitoring of the valid state of this form. Usually this is done by passing the config option "monitorValid"
Parameters:

- None.

Returns:

- `void`

This method is defined by Form.

### stopMonitoring

`public function stopMonitoring()`
Stops monitoring of the valid state of this form
Parameters:

- None.

Returns:

- `void`

This method is defined by Form.

### submit

`public function submit( `Object options` )`
Shortcut to do a submit action.
Parameters:

- `options` : Object
  The options to pass to the action

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

### un

`public function un( `String eventName`, `Function handler`, [`Object scope`] )`
Removes a listener (shorthand for removeListener)
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

### updateRecord

`public function updateRecord( `Record record` )`
Persists the values in this form into the passed Ext.data.Record object in a beginEdit/endEdit block.
Parameters:

- `record` : Record
  The record to edit

Returns:

- `BasicForm`
  this

This method is defined by BasicForm.

## Event Details

### actioncomplete

`public event actioncomplete`
Fires when an action is completed.
Subscribers will be called with the following parameters:

- `this` : Form
- `action` : Action
  The action that completed

This event is defined by BasicForm.

### actionfailed

`public event actionfailed`
Fires when an action fails.
Subscribers will be called with the following parameters:

- `this` : Form
- `action` : Action
  The action that failed

This event is defined by BasicForm.

### beforeaction

`public event beforeaction`
Fires before any action is performed. Return false to cancel the action.
Subscribers will be called with the following parameters:

- `this` : Form
- `action` : Action
  The action to be performed

This event is defined by BasicForm.

### clientvalidation

`public event clientvalidation`
If the monitorValid config option is true, this event fires repetitively to notify of valid state
Subscribers will be called with the following parameters:

- `this` : Form
- `valid` : Boolean
  true if the form has passed client-side validation

This event is defined by Form.

## Config Details

### baseParams

`baseParams : Object`
Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}.
This config option is defined by BasicForm.

### buttonAlign

`buttonAlign : String`
Valid values are "left," "center" and "right" (defaults to "center")
This config option is defined by Form.

### errorReader

`errorReader : DataReader`
An Ext.data.DataReader (e.g. Ext.data.XmlReader) to be used to read data when reading validation errors on "submit" actions. This is completely optional as there is built-in support for processing JSON.
This config option is defined by BasicForm.

### fileUpload

`fileUpload : Boolean`
Set to true if this form is a file upload.
This config option is defined by BasicForm.

### itemCls

`itemCls : String`
A css class to apply to the x-form-item of fields. This property cascades to child containers.
This config option is defined by Form.

### labelAlign

`labelAlign : String`
Valid values are "left," "top" and "right" (defaults to "left"). This property cascades to child containers if not set.
This config option is defined by Form.

### labelWidth

`labelWidth : Number`
The width of labels. This property cascades to child containers.
This config option is defined by Form.

### method

`method : String`
The request method to use (GET or POST) for form actions if one isn't supplied in the action options.
This config option is defined by BasicForm.

### minButtonWidth

`minButtonWidth : Number`
Minimum width of all buttons in pixels (defaults to 75)
This config option is defined by Form.

### monitorPoll

`monitorPoll : Number`
The milliseconds to poll valid state, ignored if monitorValid is not true (defaults to 200)
This config option is defined by Form.

### monitorValid

`monitorValid : Boolean`
If true the form monitors its valid state client-side and fires a looping event with that state. This is required to bind buttons to the valid state using the config value formBind:true on the button.
This config option is defined by Form.

### reader

`reader : DataReader`
An Ext.data.DataReader (e.g. 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.
This config option is defined by BasicForm.

### timeout

`timeout : Number`
Timeout for form actions in seconds (default is 30 seconds).
This config option is defined by BasicForm.

### trackResetOnLoad

`trackResetOnLoad : Boolean`
If set to true, form.reset() resets to the last loaded or setValues() data instead of when the form was first created.
This config option is defined by BasicForm.

### url

`url : String`
The URL to use for form actions if one isn't supplied in the action options.
This config option is defined by BasicForm.

Ext - Copyright © 2006-2007 Ext JS, LLC
All rights reserved.