Clear Up
SharpKit Reference

Ext.form Namespace

Download SDK: SharpKit.ExtJs.zip

Classes

Name Description
Basic

Provides input field management, validation, submission, and form loading services for the collection of Field instances within a Ext.container.Container. It is recommended that you use a Ext.form.Panel as the form container, as that has logic to automatically hook up an instance of Ext.form.Basic (plus other conveniences related to field configuration.)

Form Actions

The Basic class delegates the handling of form loads and submits to instances of Ext.form.action.Action. See the various Action implementations for specific details of each one's functionality, as well as the documentation for doAction which details the configuration options that can be specified in each action call.

The default submit Action is Ext.form.action.Submit, which uses an Ajax request to submit the form's values to a configured URL. To enable normal browser submission of an Ext form, use the standardSubmit config option.

File uploads

File uploads are not performed using normal 'Ajax' techniques; see the description for hasUpload for details. If you're using file uploads you should read the method description.

Example usage:

  
    Ext.create('Ext.form.Panel', {
            title: 'Basic Form',
            renderTo: Ext.getBody(),
            bodyPadding: 5,
            width: 350,
            // Any configuration items here will be automatically passed along to
            // the Ext.form.Basic instance when it gets created.
            // The form will submit an AJAX request to this URL when submitted
            url: 'save-form.php',
            items: [{
            xtype: 'textfield',
            fieldLabel: 'Field',
            name: 'theField'
            }],
            buttons: [{
            text: 'Submit',
            handler: function() {
            // The getForm() method returns the Ext.form.Basic instance:
            var form = this.up('form').getForm();
            if (form.isValid()) {
            // Submit the Ajax request and handle the response
            form.submit({
            success: function(form, action) {
            Ext.Msg.alert('Success', action.result.message);
            },
            failure: function(form, action) {
            Ext.Msg.alert('Failed', action.result ? action.result.message : 'No response');
            }
            });
            }
            }
            }]
            });
            
BasicConfig
BasicEvents
CheckboxGroup

A field container which has a specialized layout for arranging Ext.form.field.Checkbox controls into columns, and provides convenience Ext.form.field.Field methods for getting, setting, and validating the group of checkboxes as a whole.

Validation

Individual checkbox fields themselves have no default validation behavior, but sometimes you want to require a user to select at least one of a group of checkboxes. CheckboxGroup allows this by setting the config allowBlank:false; when the user does not check at least one of the checkboxes, the entire group will be highlighted as invalid and the error message will be displayed according to the msgTarget config.

Layout

The default layout for CheckboxGroup makes it easy to arrange the checkboxes into columns; see the columns and vertical config documentation for details. You may also use a completely different layout by setting the layout to one of the other supported layout types; for instance you may wish to use a custom arrangement of hbox and vbox containers. In that case the checkbox components at any depth will still be managed by the CheckboxGroup's validation.

  
    Ext.create('Ext.form.Panel', {
            title: 'Checkbox Group',
            width: 300,
            height: 125,
            bodyPadding: 10,
            renderTo: Ext.getBody(),
            items:[{
            xtype: 'checkboxgroup',
            fieldLabel: 'Two Columns',
            // Arrange checkboxes into two columns, distributed vertically
            columns: 2,
            vertical: true,
            items: [
            { boxLabel: 'Item 1', name: 'rb', inputValue: '1' },
            { boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true },
            { boxLabel: 'Item 3', name: 'rb', inputValue: '3' },
            { boxLabel: 'Item 4', name: 'rb', inputValue: '4' },
            { boxLabel: 'Item 5', name: 'rb', inputValue: '5' },
            { boxLabel: 'Item 6', name: 'rb', inputValue: '6' }
            ]
            }]
            });
            
CheckboxGroupConfig
CheckboxGroupEvents
CheckboxManager

NOTE This is a private utility class for internal use by the framework. Don't rely on its existence.

Private utility class for managing all Ext.form.field.Checkbox fields grouped by name.

CheckboxManagerConfig
CheckboxManagerEvents
FieldAncestorConfig
FieldAncestorEvents
FieldContainer

FieldContainer is a derivation of Container that implements the Labelable mixin. This allows it to be configured so that it is rendered with a field label and optional error message around its sub-items. This is useful for arranging a group of fields or other components within a single item in a form, so that it lines up nicely with other fields. A common use is for grouping a set of related fields under a single label in a form.

The container's configured items will be layed out within the field body area according to the configured layout type. The default layout is 'autocontainer'.

Like regular fields, FieldContainer can inherit its decoration configuration from the fieldDefaults of an enclosing FormPanel. In addition, FieldContainer itself can pass fieldDefaults to any fields it may itself contain.

If you are grouping a set of Checkbox or Radio fields in a single labeled container, consider using a Ext.form.CheckboxGroup or Ext.form.RadioGroup instead as they are specialized for handling those types.

Example

  
    Ext.create('Ext.form.Panel', {
            title: 'FieldContainer Example',
            width: 550,
            bodyPadding: 10,
            items: [{
            xtype: 'fieldcontainer',
            fieldLabel: 'Last Three Jobs',
            labelWidth: 100,
            // The body area will contain three text fields, arranged
            // horizontally, separated by draggable splitters.
            layout: 'hbox',
            items: [{
            xtype: 'textfield',
            flex: 1
            }, {
            xtype: 'splitter'
            }, {
            xtype: 'textfield',
            flex: 1
            }, {
            xtype: 'splitter'
            }, {
            xtype: 'textfield',
            flex: 1
            }]
            }],
            renderTo: Ext.getBody()
            });
            

Usage of fieldDefaults

  
    Ext.create('Ext.form.Panel', {
            title: 'FieldContainer Example',
            width: 350,
            bodyPadding: 10,
            items: [{
            xtype: 'fieldcontainer',
            fieldLabel: 'Your Name',
            labelWidth: 75,
            defaultType: 'textfield',
            // Arrange fields vertically, stretched to full width
            layout: 'anchor',
            defaults: {
            layout: '100%'
            },
            // These config values will be applied to both sub-fields, except
            // for Last Name which will use its own msgTarget.
            fieldDefaults: {
            msgTarget: 'under',
            labelAlign: 'top'
            },
            items: [{
            fieldLabel: 'First Name',
            name: 'firstName'
            }, {
            fieldLabel: 'Last Name',
            name: 'lastName',
            msgTarget: 'under'
            }]
            }],
            renderTo: Ext.getBody()
            });
            
FieldContainerConfig
FieldContainerEvents
FieldSet

A container for grouping sets of fields, rendered as a HTML fieldset element. The title config will be rendered as the fieldset's legend.

While FieldSets commonly contain simple groups of fields, they are general Containers and may therefore contain any type of components in their items, including other nested containers. The default layout for the FieldSet's items is 'anchor', but it can be configured to use any other layout type.

FieldSets may also be collapsed if configured to do so; this can be done in two ways:

  1. Set the collapsible config to true; this will result in a collapse button being rendered next to the legend title, or:
  2. Set the checkboxToggle config to true; this is similar to using collapsible but renders a checkbox in place of the toggle button. The fieldset will be expanded when the checkbox is checked and collapsed when it is unchecked. The checkbox will also be included in the form submit parameters using the checkboxName as its parameter name.

Example usage

  
    Ext.create('Ext.form.Panel', {
            title: 'Simple Form with FieldSets',
            labelWidth: 75, // label settings here cascade unless overridden
            url: 'save-form.php',
            frame: true,
            bodyStyle: 'padding:5px 5px 0',
            width: 550,
            renderTo: Ext.getBody(),
            layout: 'column', // arrange fieldsets side by side
            defaults: {
            bodyPadding: 4
            },
            items: [{
            // Fieldset in Column 1 - collapsible via toggle button
            xtype:'fieldset',
            columnWidth: 0.5,
            title: 'Fieldset 1',
            collapsible: true,
            defaultType: 'textfield',
            defaults: {anchor: '100%'},
            layout: 'anchor',
            items :[{
            fieldLabel: 'Field 1',
            name: 'field1'
            }, {
            fieldLabel: 'Field 2',
            name: 'field2'
            }]
            }, {
            // Fieldset in Column 2 - collapsible via checkbox, collapsed by default, contains a panel
            xtype:'fieldset',
            title: 'Show Panel', // title or checkboxToggle creates fieldset header
            columnWidth: 0.5,
            checkboxToggle: true,
            collapsed: true, // fieldset initially collapsed
            layout:'anchor',
            items :[{
            xtype: 'panel',
            anchor: '100%',
            title: 'Panel inside a fieldset',
            frame: true,
            height: 52
            }]
            }]
            });
            
FieldSetConfig
FieldSetEvents
Label

Produces a standalone <label /> element which can be inserted into a form and be associated with a field in that form using the forId property.

NOTE: in most cases it will be more appropriate to use the fieldLabel and associated config properties (Ext.form.Labelable.labelAlign, Ext.form.Labelable.labelWidth, etc.) in field components themselves, as that allows labels to be uniformly sized throughout the form. Ext.form.Label should only be used when your layout can not be achieved with the standard field layout.

You will likely be associating the label with a field component that extends Ext.form.field.Base, so you should make sure the forId is set to the same value as the inputId of that field.

The label's text can be set using either the text or html configuration properties; the difference between the two is that the former will automatically escape HTML characters when rendering, while the latter will not.

Example

This example creates a Label after its associated Text field, an arrangement that cannot currently be achieved using the standard Field layout's labelAlign.

  
    Ext.create('Ext.form.Panel', {
            title: 'Field with Label',
            width: 400,
            bodyPadding: 10,
            renderTo: Ext.getBody(),
            layout: {
            type: 'hbox',
            align: 'middle'
            },
            items: [{
            xtype: 'textfield',
            hideLabel: true,
            flex: 1
            }, {
            xtype: 'label',
            forId: 'myFieldId',
            text: 'My Awesome Field',
            margin: '0 0 0 10'
            }]
            });
            
LabelableConfig
LabelableEvents
LabelConfig
LabelEvents
Panel

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()
            });
            
PanelConfig
PanelEvents
RadioGroup

A field container which has a specialized layout for arranging Ext.form.field.Radio controls into columns, and provides convenience Ext.form.field.Field methods for getting, setting, and validating the group of radio buttons as a whole.

Validation

Individual radio buttons themselves have no default validation behavior, but sometimes you want to require a user to select one of a group of radios. RadioGroup allows this by setting the config allowBlank:false; when the user does not check at one of the radio buttons, the entire group will be highlighted as invalid and the error message will be displayed according to the msgTarget config.

Layout

The default layout for RadioGroup makes it easy to arrange the radio buttons into columns; see the columns and vertical config documentation for details. You may also use a completely different layout by setting the layout to one of the other supported layout types; for instance you may wish to use a custom arrangement of hbox and vbox containers. In that case the Radio components at any depth will still be managed by the RadioGroup's validation.

Example usage

  
    Ext.create('Ext.form.Panel', {
            title: 'RadioGroup Example',
            width: 300,
            height: 125,
            bodyPadding: 10,
            renderTo: Ext.getBody(),
            items:[{
            xtype: 'radiogroup',
            fieldLabel: 'Two Columns',
            // Arrange radio buttons into two columns, distributed vertically
            columns: 2,
            vertical: true,
            items: [
            { boxLabel: 'Item 1', name: 'rb', inputValue: '1' },
            { boxLabel: 'Item 2', name: 'rb', inputValue: '2', checked: true},
            { boxLabel: 'Item 3', name: 'rb', inputValue: '3' },
            { boxLabel: 'Item 4', name: 'rb', inputValue: '4' },
            { boxLabel: 'Item 5', name: 'rb', inputValue: '5' },
            { boxLabel: 'Item 6', name: 'rb', inputValue: '6' }
            ]
            }]
            });
            
RadioGroupConfig
RadioGroupEvents
RadioManager

NOTE This is a private utility class for internal use by the framework. Don't rely on its existence.

Private utility class for managing all Ext.form.field.Radio fields grouped by name.

RadioManagerConfig
RadioManagerEvents

Interfaces

Name Description
FieldAncestor

A mixin for Ext.container.Container components that are likely to have form fields in their items subtree. Adds the following capabilities:

  • Methods for handling the addition and removal of Ext.form.Labelable and Ext.form.field.Field instances at any depth within the container.
  • Events (fieldvaliditychange and fielderrorchange) for handling changes to the state of individual fields at the container level.
  • Automatic application of fieldDefaults config properties to each field added within the container, to facilitate uniform configuration of all fields.

This mixin is primarily for internal use by Ext.form.Panel and Ext.form.FieldContainer, and should not normally need to be used directly.

Labelable

A mixin which allows a component to be configured and decorated with a label and/or error message as is common for form fields. This is used by e.g. Ext.form.field.Base and Ext.form.FieldContainer to let them be managed by the Field layout.

NOTE: This mixin is mainly for internal library use and most users should not need to use it directly. It is more likely you will want to use one of the component classes that import this mixin, such as Ext.form.field.Base or Ext.form.FieldContainer.

Use of this mixin does not make a component a field in the logical sense, meaning it does not provide any logic or state related to values or validation; that is handled by the related Ext.form.field.Field mixin. These two mixins may be used separately (for example Ext.form.FieldContainer is Labelable but not a Field), or in combination (for example Ext.form.field.Base implements both and has logic for connecting the two.)

Component classes which use this mixin should use the Field layout or a derivation thereof to properly size and position the label and message according to the component config. They must also call the initLabelable method during component initialization to ensure the mixin gets set up correctly.

© Copyright 2005-2011 SharpKit. All rights reserved.