Clear Up
SharpKit Reference

Panel Class

FormPanel provides a standard container for forms. It is essentially a standard Ext.panel.Panel which automatically creates a BasicForm for managing any Ext.form.field.Field objects that are added as descendants of the panel. It also includes conveniences for configuring and working with the BasicForm and the collection of Fields.

Layout

By default, FormPanel is configured with layout:'anchor' for the layout of its immediate child items. This can be changed to any of the supported container layouts. The layout of sub-containers is configured in the standard way.

BasicForm

Although not listed as configuration options of FormPanel, the FormPanel class accepts all of the config options supported by the Ext.form.Basic class, and will pass them along to the internal BasicForm when it is created.

The following events fired by the BasicForm will be re-fired by the FormPanel and can therefore be listened for on the FormPanel itself:

  • beforeaction
  • actionfailed
  • actioncomplete
  • validitychange
  • dirtychange

Field Defaults

The fieldDefaults config option conveniently allows centralized configuration of default values for all fields added as descendants of the FormPanel. Any config option recognized by implementations of Ext.form.Labelable may be included in this object. See the fieldDefaults documentation for details of how the defaults are applied.

Form Validation

With the default configuration, form fields are validated on-the-fly while the user edits their values. This can be controlled on a per-field basis (or via the fieldDefaults config) with the field config properties Ext.form.field.Field.validateOnChange and Ext.form.field.Base.checkChangeEvents, and the FormPanel's config properties pollForChanges and pollInterval.

Any component within the FormPanel can be configured with formBind: true. This will cause that component to be automatically disabled when the form is invalid, and enabled when it is valid. This is most commonly used for Button components to prevent submitting the form in an invalid state, but can be used on any component type.

For more information on form validation see the following:

  • Ext.form.field.Field.validateOnChange
  • pollForChanges and pollInterval
  • Ext.form.field.VTypes
  • BasicForm.doAction clientValidation notes

Form Submission

By default, Ext Forms are submitted through Ajax, using Ext.form.action.Action. See the documentation for Ext.form.Basic for details.

Example usage

  
    Ext.create('Ext.form.Panel', {
            title: 'Simple Form',
            bodyPadding: 5,
            width: 350,
            // The form will submit an AJAX request to this URL when submitted
            url: 'save-form.php',
            // Fields will be arranged vertically, stretched to full width
            layout: 'anchor',
            defaults: {
            anchor: '100%'
            },
            // The fields
            defaultType: 'textfield',
            items: [{
            fieldLabel: 'First Name',
            name: 'first',
            allowBlank: false
            },{
            fieldLabel: 'Last Name',
            name: 'last',
            allowBlank: false
            }],
            // Reset and Submit buttons
            buttons: [{
            text: 'Reset',
            handler: function() {
            this.up('form').getForm().reset();
            }
            }, {
            text: 'Submit',
            formBind: true, //only enabled once the form is valid
            disabled: true,
            handler: function() {
            var form = this.up('form').getForm();
            if (form.isValid()) {
            form.submit({
            success: function(form, action) {
            Ext.Msg.alert('Success', action.result.msg);
            },
            failure: function(form, action) {
            Ext.Msg.alert('Failed', action.result.msg);
            }
            });
            }
            }
            }],
            renderTo: Ext.getBody()
            });
            

Namespace: Ext.form

Derived Types

Constructors

Methods

Name Description
checkChange() Forces each field within the form panel to check if its value has changed.
getForm() Provides access to the Form which this Panel contains.
getRecord() Returns the currently loaded Ext.data.Model instance if one was loaded via loadRecord.
getValues(object, object, object, object) Convenience function for fetching the current value of each field in the form. This is the same as calling this.getForm().getValues(). Retrieves the fields in the form as a set of key/value pairs, using their getSubmitData() method to collect the values. If multiple fields return values under the same name those values will be combined into an Array. This is similar to getFieldValues except that this method collects only String values for submission, while getFieldValues collects type-specific data values (e.g. Date objects for date fields.)
handleFieldErrorChange(object, object) Handle errorchange events on sub-fields; invoke the aggregated event and method
handleFieldValidityChange(object, object) Handle validitychange events on sub-fields; invoke the aggregated event and method
initFieldAncestor() Initializes the FieldAncestor's state; this must be called from the initComponent method of any components importing this mixin.
initFieldDefaults() Initialize the fieldDefaults object
load(object) This is a proxy for the underlying BasicForm's Ext.form.Basic.load call.
loadRecord(Model) Loads an Ext.data.Model into this form (internally just calls Ext.form.Basic.loadRecord) See also trackResetOnLoad.
onFieldAdded(Field) Called when a Ext.form.field.Field instance is added to the container's subtree.
onFieldAncestorSubtreeChange(object, object) Handle the addition and removal of components in the FieldAncestor component's child tree.
onFieldErrorChange(Labelable, JsString) Fired when the error message of any field within the container changes.
onFieldRemoved(Field) Called when a Ext.form.field.Field instance is removed from the container's subtree.
onFieldValidityChange(Field, bool) Fired when the validity of any field within the container changes.
onLabelableAdded(Labelable) Called when a Ext.form.Labelable instance is added to the container's subtree.
onLabelableRemoved(Labelable) Called when a Ext.form.Labelable instance is removed from the container's subtree.
startPolling(JsNumber) Start an interval task to continuously poll all the fields in the form for changes in their values. This is normally started automatically by setting the pollForChanges config.
stopPolling() Stop a running interval task that was started by startPolling.
submit(object) This is a proxy for the underlying BasicForm's Ext.form.Basic.submit call.

Fields

Name Description
fieldDefaults If specified, the properties in this object are used as default config values for each Ext.form.Labelable instance (e.g. Ext.form.field.Base or Ext.form.FieldContainer) that is added as a descendant of this container. Corresponding values specified in an individual field's own configuration, or from the defaults config of its parent container, will take precedence. See the documentation for Ext.form.Labelable to see what config options may be specified in the fieldDefaults. Example:
new Ext.form.Panel({
            fieldDefaults: {
            labelAlign: 'left',
            labelWidth: 100
            },
            items: [{
            xtype: 'fieldset',
            defaults: {
            labelAlign: 'top'
            },
            items: [{
            name: 'field1'
            }, {
            name: 'field2'
            }]
            }, {
            xtype: 'fieldset',
            items: [{
            name: 'field3',
            labelWidth: 150
            }, {
            name: 'field4'
            }]
            }]
            });
            
In this example, field1 and field2 will get labelAlign:'top' (from the fieldset's defaults) and labelWidth:100 (from fieldDefaults), field3 and field4 will both get labelAlign:'left' (from fieldDefaults and field3 will use the labelWidth:150 from its own config.
pollForChanges If set to true, sets up an interval task (using the pollInterval) in which the panel's fields are repeatedly checked for changes in their values. This is in addition to the normal detection each field does on its own input element, and is not needed in most cases. It does, however, provide a means to absolutely guarantee detection of all changes including some edge cases in some browsers which do not fire native events. Defaults to false.
pollInterval Interval in milliseconds at which the form's fields are checked for value changes. Only used if the pollForChanges option is set to true. Defaults to 500 milliseconds.
© Copyright 2005-2011 SharpKit. All rights reserved.