Upgrade to ExtJS 4.0.7 - Released 10/19/2011

[extjs.git] / docs / guides / forms / README.md

# Forms
______________________________________________

A {@link Ext.form.Panel Form Panel} is nothing more than a basic {@link Ext.panel.Panel Panel} with form handling abilities added.
Form Panels can be used throughout an Ext application wherever there is a need to collect data from the user.
In addition, Form Panels can use any {@link Ext.layout.container.Container Container Layout}, providing a convenient and flexible way to handle the positioning of their fields.
Form Panels can also be bound to a {@link Ext.data.Model Model}, making it easy to load data from and submit data back to the server.
Under the hood a Form Panel wraps a {@link Ext.form.Basic Basic Form} which handles all of its input field management, validation, submission, and form loading services.
This means that any of the config options of a Basic Form can be used directly on a Form Panel.

## Basic Form Panel

To start off, here's how to create a simple form that collects user data:

    @example
    Ext.create('Ext.form.Panel', {
        renderTo: Ext.getBody(),
        title: 'User Form',
        height: 130,
        width: 280,
        bodyPadding: 10,
        defaultType: 'textfield',
        items: [
            {
                fieldLabel: 'First Name',
                name: 'firstName'
            },
            {
                fieldLabel: 'Last Name',
                name: 'lastName'
            },
            {
                xtype: 'datefield',
                fieldLabel: 'Date of Birth',
                name: 'birthDate'
            }
        ]
    });

This form renders itself to the document body and has three {@link Ext.form.field.Field Field}s - "First Name", "Last Name", and "Date of Birth". Fields are added to the Form Panel using the {@link Ext.form.Panel#cfg-items items} configuration.
The {@link Ext.form.Labelable#fieldLabel fieldLabel} configuration defines what text will appear in the label next to the field, and the {@link Ext.form.field.Base#name name} configuration becomes the `name` attribute of the underlying html field.
Notice how this Form Panel has a {@link Ext.form.Panel#defaultType defaultType} of 'textfield'.  This means that any of its items that do not have an {@link Ext.Component xtype} specified (the "First Name" and "Last Name" fields in this example), are {@link Ext.form.field.Text Text Field}s.
The "Date of Birth" field on the other hand has its `xtype` explicitly defined as 'datefield' which makes it a {@link Ext.form.field.Date Date Field}. Date Fields expect to only contain valid date data, and come with a {@link Ext.menu.DatePicker DatePicker} for selecting a date.

See the [Simple Form](guides/forms/examples/simple_form/index.html) example for a live demo.

## Fields

### Field Types

Ext JS provides a set of standard Field types out of the box. Any of the Fields in the `Ext.form.field` namespace can be used in a Form Panel. For more information see the API documentaion for each Field type:

* {@link Ext.form.field.Checkbox}
* {@link Ext.form.field.ComboBox}
* {@link Ext.form.field.Date}
* {@link Ext.form.field.Display}
* {@link Ext.form.field.File}
* {@link Ext.form.field.Hidden}
* {@link Ext.form.field.HtmlEditor}
* {@link Ext.form.field.Number}
* {@link Ext.form.field.Radio}
* {@link Ext.form.field.Text}
* {@link Ext.form.field.TextArea}
* {@link Ext.form.field.Time}

### Validation

#### 1. Built-in Validations

Ext JS has built in support for validation on any type of Field, and some Fields have built in validation rules.
For example if a value is entered into a {@link Ext.form.field.Date Date Field} and that value cannot be converted into a `Date`, the Field will have the `x-form-invalid-field` CSS class added to its HTML element.
If necessary, this CSS class can be changed using the {@link Ext.form.field.Base#invalidCls invalidCls} configuration. In the default [theme](#/guide/theming), adding the `invalidCls` adds a red "invalid underline":

{@img invalid_field.png Invalid Field}

A Field containing invalid data will also display an error message. By default this message displays as a tool tip:

{@img invalid_field_hover.png Invalid Field Hover}

It's easy to change the location of a Field's error message using the {@link Ext.form.Labelable#msgTarget msgTarget} configuration, and the {@link Ext.form.field.Base#invalidText invalidText} configuration changes the error message.
Each Field provides its own implementation of `invalidText`, and many support token replacement in the error message.
For example, in a Date Field's `invalidText`, any occurrences of "{0}" will be replaced with the Field's value, and any occurrences of "{1}" will be replaced with the required date {@link Ext.form.field.Date#format format}.
The following code demonstrates placing the error message directly under the Field, and customizing the error message text:

    {
        xtype: 'datefield',
        fieldLabel: 'Date of Birth',
        name: 'birthDate',
        msgTarget: 'under', // location of the error message
        invalidText: '"{0}" bad. "{1}" good.' // custom error message text
    }

{@img custom_error_message.png Custom Error Message}

#### 2. Custom Validations

Some validation requirements cannot be met using the built-in validations. The simplest way to implement a custom validation is to use the {@link Ext.form.field.Text Text Field}'s {@link Ext.form.field.Text#regex regex} configuration to apply validation rules, and the {@link Ext.form.field.Text#maskRe maskRe} configuration to limit which characters can be typed into the field. Here's an example of a Text Field that validates a time.

    {
        fieldLabel: 'Last Login Time',
        name: 'loginTime',
        regex: /^([1-9]|1[0-9]):([0-5][0-9])(\s[a|p]m)$/i,
        maskRe: /[\d\s:amp]/i,
        invalidText: 'Not a valid time.  Must be in the format "12:34 PM".'
    }

While the above method works well for validating a single field, it is not practical for an application that has many fields that share the same custom validation.
The {@link Ext.form.field.VTypes} class provides a solution for creating reusable custom validations. Here's how a custom "time" validator can be created:

    // custom Vtype for vtype:'time'
    var timeTest = /^([1-9]|1[0-9]):([0-5][0-9])(\s[a|p]m)$/i;
    Ext.apply(Ext.form.field.VTypes, {
        //  vtype validation function
        time: function(val, field) {
            return timeTest.test(val);
        },
        // vtype Text property: The error text to display when the validation function returns false
        timeText: 'Not a valid time.  Must be in the format "12:34 PM".',
        // vtype Mask property: The keystroke filter mask
        timeMask: /[\d\s:amp]/i
    });

Once a custom validator has been created it can be used on Text Fields throughout an application using the `{@link Ext.form.field.Text#vtype vtype}` configuration:

    {
        fieldLabel: 'Last Login Time',
        name: 'loginTime',
        vtype: 'time'
    }

See [Validation Example](guides/forms/examples/validation) for a working demo. For more information on custom validations please refer to the API Documentation for {@link Ext.form.field.VTypes VTypes}.

## Handling Data

### Submitting a Form

The simplest way to submit data to the server is to use the {@link Ext.form.Basic#url url} configuration of {@link Ext.form.Basic Basic Form}. Since {@link Ext.form.Panel Form Panel} wraps a Basic Form, we can use any of Basic Form's configuration options directly on a Form Panel:


    Ext.create('Ext.form.Panel', {
        ...
        url: 'add_user',
        items: [
            ...
        ]
    });

The Basic Form's {@link Ext.form.Basic#submit submit} method can be used to submit data to the configured `url`:

    Ext.create('Ext.form.Panel', {
        ...
        url: 'add_user',
        items: [
            ...
        ],
        buttons: [
            {
                text: 'Submit',
                handler: function() {
                    var form = this.up('form').getForm(); // get the basic form
                    if (form.isValid()) { // make sure the form contains valid data before submitting
                        form.submit({
                            success: function(form, action) {
                               Ext.Msg.alert('Success', action.result.msg);
                            },
                            failure: function(form, action) {
                                Ext.Msg.alert('Failed', action.result.msg);
                            }
                        });
                    } else { // display error alert if the data is invalid
                        Ext.Msg.alert('Invalid Data', 'Please correct form errors.')
                    }
                }
            }
        ]
    });

In the above example a button is configured with a handler that handles form submission. The handler takes the following actions:

1. First a reference to the Basic Form must be acquired.
2. Then the {@link Ext.form.Basic#isValid isValid} method is called before submission to verify that none of the fields have validation errors.
3. Finally the `submit` method is called, and two callback functions are passed - `success` and `failure`.  Within these callback functions `action.result` refers to the parsed JSON response.

The above example expects a JSON response that looks something like this:

    { "success": true, "msg": "User added successfully" }

[Form Submission Example](guides/forms/examples/submit/index.html)

### Binding a Form to a Model

The {@link Ext.data.Model Model} class is used throughout Ext JS for representing various types of data, as well as retrieving and updating data on the server.
A Model representing a User would define the fields a User has, as well as a proxy for loading and saving data:

    Ext.define('User', {
        extend: 'Ext.data.Model',
        fields: ['firstName', 'lastName', 'birthDate'],
        proxy: {
            type: 'ajax',
            api: {
                read: 'data/get_user',
                update: 'data/update_user'
            },
            reader: {
                type: 'json',
                root: 'users'
            }
        }
    });

For more details on working with Models please refer to the [Data Guide](#/guide/data).

Data can be loaded into a {@link Ext.form.Panel Form Panel} directly from a {@link Ext.data.Model Model} using the {@link Ext.form.Panel#loadRecord loadRecord} method:

    Ext.ModelMgr.getModel('User').load(1, { // load user with ID of "1"
        success: function(user) {
            userForm.loadRecord(user); // when user is loaded successfully, load the data into the form
        }
    });

Finally, instead of using the {@link Ext.form.Basic#submit submit} method to save the data, Basic Form's {@link Ext.form.Basic#updateRecord updateRecord} method is used to update the record with the form data, and the Model's {@link Ext.data.Model#save save} method is called to save the data to the server:

    Ext.create('Ext.form.Panel', {
        ...
        url: 'add_user',
        items: [
            ...
        ],
        buttons: [
            {
                text: 'Submit',
                handler: function() {
                    var form = this.up('form').getForm(), // get the basic form
                        record = form.getRecord(); // get the underlying model instance
                    if (form.isValid()) { // make sure the form contains valid data before submitting
                        form.updateRecord(record); // update the record with the form data
                        record.save({ // save the record to the server
                            success: function(user) {
                                Ext.Msg.alert('Success', 'User saved successfully.')
                            },
                            failure: function(user) {
                                Ext.Msg.alert('Failure', 'Failed to save user.')
                            }
                        });
                    } else { // display error alert if the data is invalid
                        Ext.Msg.alert('Invalid Data', 'Please correct form errors.')
                    }
                }
            }
        ]
    });

[Model Binding Example](guides/forms/examples/model_binding/index.html)

## Layouts

Layouts are used to handle sizing and positioning of components in an Ext JS application.  {@link Ext.form.Panel Form Panels} can use any {@link Ext.layout.container.Container Container Layout}. For more information on Layouts please refer to the [Layouts and Containers Guide](#/guide/layouts_and_containers).

For example, positioning fields in a form horizontally can easily be done using an {@link Ext.layout.container.HBox HBox} Layout:

    @example
    Ext.create('Ext.form.Panel', {
        renderTo: Ext.getBody(),
        title: 'User Form',
        height: 100,
        width: 515,
        defaults: {
            xtype: 'textfield',
            labelAlign: 'top',
            padding: 10
        },
        layout: {
            type: 'hbox'
        },
        items: [
            {
                fieldLabel: 'First Name',
                name: 'firstName'
            },
            {
                fieldLabel: 'Last Name',
                name: 'lastName'
            },
            {
                xtype: 'datefield',
                fieldLabel: 'Date of Birth',
                name: 'birthDate'
            }
        ]
    });

See the [Layout Example](guides/forms/examples/layout/index.html) for a live demo.