dxForm

The dxForm widget is intended to visually represent and edit data stored in an object that has a specific structure. The widget enables you to bind each layout item to an appropriate field of an existing data object, as well as to generate a new data object according to current values of the form fields.

View Demo

Create a Simple Form

To create a simple form, just add the dxForm widget to your application and pass the required object to the formData option. To learn how to add a widget to an application, refer to the Add a Widget to a Page tutorial.

HTML
<div id="myForm"></div>
JavaScript
var employeeData = {
        FirstName: "John",
        LastName: "Heart",
        Position: "CEO",
        OfficeNo: "901",
        BirthDate: "1964/03/16",
        HireDate: "1995/01/15",
        City: "Los Angeles",
        Phone: "+1(213) 555-9392",
        Email: "jheart@dx-email.com"
    };
$("#myForm").dxForm({
    formData: employeeData
});
Angular Approach
HTML
<div ng-controller="demoController" style="height:100%;">
    <div dx-form="formData: employeeData"></div>
</div>
JavaScript
var myApp = angular.module('myApp', ['dx']);
myApp.controller("demoController", function ($scope) {
    $scope.employeeData = {
        FirstName: "John",
        LastName: "Heart",
        Position: "CEO",
        OfficeNo: "901",
        BirthDate: "1964/03/16",
        HireDate: "1995/01/15",
        City: "Los Angeles",
        Phone: "+1(213) 555-9392",
        Email: "jheart@dx-email.com"
    }
});
angular.element(document).ready(function () {
    angular.bootstrap(document, ['myApp']);
});
Knockout Approach
HTML
<div data-bind="dxForm: { formData: employeeData }"></div>
JavaScript
var myViewModel = {
    employeeData: {
        FirstName: "John",
        LastName: "Heart",
        Position: "CEO",
        OfficeNo: "901",
        BirthDate: "1964/03/16",
        HireDate: "1995/01/15",
        City: "Los Angeles",
        Phone: "+1(213) 555-9392",
        Email: "jheart@dx-email.com"
    }
}
ko.applyBindings(myViewModel);

When the dxForm widget generates a form item for a data field, it chooses the required editor type, depending on the data type and transforms the data field name to a label with elegant text. For instance, if a data field name is “firstName”, the item label is “First Name”.

Customize Layout

The dxForm widget enables you to specify a fixed number of columns in the layout, or force the widget to automatically choose the number of columns depending on the current form width.

To specify a fixed number of columns in the form layout, assign the required number to the colCount option.

JavaScript
var formOptions = {
    formData: employeeData,
    colCount: 3
}

For an automatic calculation of the column count, assign "auto" to the colCount option and specify the minimum column width using the minColWidth option. In this case, the layout contains the number of columns the form could fit if the column width equals minColWidth.

JavaScript
var formOptions = {
    formData: employeeData,
    colCount: "auto",
    minColWidth: 200
}

The dxForm widget layout is adaptive. It becomes a single-column on devices with small screens.

Customize Item Labels

Each form item consists of an editor and a label. You can specify the label position against the editor. The labelLocation option specifies whether the label is displayed to the left, right or top of the editor.

JavaScript
var formOptions = {
    formData: employeeData,
    labelLocation: "top"
}

By default, the widget adds a colon after each label. To disable this functionality, assign false to the showColonAfterLabel option.

JavaScript
var formOptions = {
    formData: employeeData,
    labelLocation: "top",
    showColonAfterLabel: false
}

Modify Form Items

If generated form items do not satisfy your requirements, you can define form items manually or modify options of each generated item before this item is rendered. Manual defining of custom form items is considered in the Define Items Manually section of this article.

To modify generated items, use the customizeItem option, which accepts a function called for each generated item before this item is rendered. The item configuration object is passed to this function as an argument. The configuration object of each generated item has a Simple Item structure. Thus, you can modify the editor options, or change the editor type, modify the item label, specify validation rules, etc. See the Simple Item reference article for the full list of simple item configuration options.

JavaScript
var formOptions = {
    formData: employeeData,
    colCount: 3,
    customizeItem: function(item) {
        item.label = {
            location: "top"
        };
        if (item.dataField === "Email" || item.dataField === "Phone")
            item.colSpan = 3;
        if (item.dataField === "Phone")
            item.helpText = "Example: +1 (111) 111-1111";
    }
}

You can also modify a form item option at runtime using the itemOption(field, option, value) or itemOption(field, options) methods.

See Also

Define Items Manually

If you need to create a form that has an advanced layout containing groups and tabbed pages, or you need to create items only for certain fields of the data object, you should define form items manually. For this purpose, assign an array of item configuration objects to the items option of the form.

The structure of an item configuration object depends on the item type. The dxForm widget supports the following item types.

  • Simple
    A standard item consisting of a label and an editor widget used to specify a value of the associated data field.

  • Empty
    An empty item used to add a space between neighboring items.

  • Group
    An item representing a container of another form items.

  • Tabbed
    An item representing a tabbed container of other form items.

The type of an item is defined by the type configuration option of this item. By default, the item type is Simple.

In addition to the itemType option, each form item supports the following configuration options regardless of the item type.

  • colSpan
    Specifies the number of columns spanned by the item.

  • cssClass
    Specifies a CSS class to be applied to the form item.

  • visible
    Specifies whether or not the item is displayed on a form.

  • visibleIndex
    Specifies the sequence number of the item in a form, group or tab.

View Demo

Create Simple Items

The main item type used in a form is Simple. An item of this type consists of a label and an editor. In addition, a help text can be displayed under the editor.

If you do not need to modify any options of a simple item, you may define this item implicitly using a string instead of a configuration object. The string should contain the name of the data object field associated with the item.

JavaScript
var formOptions = {
    formData: employeeData,
    items: ["FirstName", "LastName", "Position"]
}

If the default item configuration does not satisfy your requirements, you should define the required configuration options. The name of the data field associated with the form item is specified using the dataField option. You can also specify the type of the editor used to edit the field value, the number of columns spanned by the item, help text displayed under the editor, editor validation rules, etc.

JavaScript
var formOptions = {
    formData: employeeData,
    items: [
        . . .,
        {
            dataField: "Email",
            colSpan: 3,
            label: {
                text: "E-mail"
            }
        },
        {
            dataField: "Phone",
            colSpan: 3,
            helpText: "Example: +1 (111) 111-1111"
        },
        . . .
    ]
}

The dxForm widget enables you to customize the appearance of a simple item using an item template. Pass a template name, a template element, or a function rendering a template to the template option of the item. For more information on using templates, refer to the Customize Widget Element Appearance article.

See Also

For the complete list of simple item configuration options, refer to the Simple Item API reference.

Create Empty Items

If you need to add an empty space between neighboring items, use an Empty form item. To create an empty item, assign "empty" to the itemType option of an item.

JavaScript
var formOptions: {
    formData: employeeData,
    items: [
        'FirstName',
        'LastName',
        { 
            itemType: 'empty',
            colSpan: 2
        },
        'Position',
        {
            itemType: 'empty'
        },
        'BirthDate',
        'HireDate',
        'City',
        {
            itemType: 'empty'
        },
        'Phone',
        'Email'
    ]
}

Create Group Items

If you need to organize items into a groups, use Group form items. To create a Group item, assign "group" to the itemType option.

A group item has its own layout, which does not depend on the form layout. Thus, even if a group item spans three columns, its inner layout may consist of any number of columns. For example, two or five. The number of columns in a group layout is defined by the colCount option. A group caption is specified using the caption option.

A group can contain items of any type including group and tabbed items, which may also contain nested groups or tabbed pages. The child items of a group item are specified using the items option.

JavaScript
var formOptions: {
    formData: employeeData,
    colCount: 3,
    labelLocation: 'top',
    items: [
        {
            itemType: 'group',
            caption: 'Personal Data',
            colCount: 3,
            items: [
                'FirstName',
                'LastName',
                'Position',
                'BirthDate',
                'HireDate',
                'City'
            ]
        },
        {
            itemType: 'group',
            caption: 'Contacts',
            colCount: 2,
            items: [
                'Phone',
                'Email'
            ]
        }
    ]
}

As well as a simple item, a group item enables you to customize its appearance using a template. Pass a template name, template element, or a function rendering a template to the template option of the item. For more information on using templates, refer to the Customize Widget Element Appearance article.

See Also

For the complete list of group item configuration options, refer to the Group Item API reference.

Create Tabbed Items

If you need to organize items into tabbed pages, use Tabbed form items. To create a Tabbed item, assign "tabbed" to the itemType option.

You can specify configuration options of tabs using the tabs option. This option accepts an array of tab configuration objects.

Each tab of a tabbed form item can have its own layout, which does not depend on the form layout. Thus, even if a tabbed item spans three columns, the layout of each tab may consist of any number of columns. For example, two or five. The number of columns in a tab layout is defined by the colCount option of a tab. A tab title is specified using the title option.

A tab can contain items of any type including group and tabbed items, which may also contain nested groups or tabbed pages. The child items of a tab are specified using the items option.

JavaScript
var formOptions: {
    formData: employeeData,
    colCount: 3,
    items: [
        'FirstName',
        'LastName',
        {
            itemType: 'tabbed',
            tabs: [
                {
                    title: 'Info',
                    colCount: 2,
                    items: [
                        'Position',
                        'BirthDate',
                        'HireDate',
                        'City'
                    ]
                },
                {
                    title: 'Contacts',
                    items: [
                        'Phone',
                        'Email'
                    ]
                }
            ]
        }
    ]
}

The dxForm widget uses the dxTabPanel widget to display tabbed items. You can modify options of the tab panel using the tabPanelOptions option, which accepts the dxTabPanel configuration object.

For the complete list of tabbed item configuration options, refer to the Tabbed Item API reference.

Validate Form Items

The dxForm widget uses the DevExtreme validation engine to validate form item values. You can specify validation rules for each form item using the validationRules option of the item. You can specify validation rules when defining form items manually,

See Also
JavaScript
var formOptions = {
    formData: employeeData,
    items: [
        {
            dataField: "FirstName",
            validationRules: [
                {
                    type: "required",
                    message: "First Name is required"
                },
                {
                    type: "pattern",
                    pattern: "^[a-zA-Z]+$",
                    message: "The name should not contain digits"
                }
            ]
        },
        . . .
    ]
}

or when customizing automatically generated items.

JavaScript
var formOptions = {
    formData: employeeData,
    customizeItem: function(item){
        if(item.dataField === "FirstName" || item.dataField === "LastName"){
            item.validationRules = [
                {
                    type: "required",
                    message: "The value is required"
                },
                {
                    type: "pattern",
                    pattern: "^[a-zA-Z]+$",
                    message: "The value should not contain digits"
                }
            ]
        }
        . . .
    }
}

The RequiredRule validation rule is automatically applied to a form item, if the isRequired option of this item is set to true.

var formOptions = {
    formData: employeeData,
    items: [
        {
            dataField: "FirstName",
            isRequired: true
        },
        . . .
    ]
}

Each editor of the form is automatically validated when its value has been updated. However, you can validate the entire form using the validate() method. Once the form has been validated, validation information is displayed at each editor that does not satisfy validation rules. In addition, if you assign true to the showValidationSummary option, the widget displays validation summary at the bottom of the form.

JavaScript
// Get form instance
. . .
formInstance.validate();

Update Editor Values

If you need to update a formData field value at runtime, you can redefine the formData option value. In this case, form item values are automatically updated. However, the widget is completely rerendered.

JavaScript
$("#myForm").dxForm("instance").option("formData", {
    FirstName: "John",
    LastName: "Heart",
    Position: "CEO",
    OfficeNo: "1003",
    BirthDate: "1964/03/16",
    HireDate: "1995/01/15",
    City: "New York",
    Phone: "+1(555) 555-9244",
    Email: "jheart@dx-email.com"
});

The dxForm widget includes the updateData(data) and updateData(dataField, value) methods, which enable you to update values of certain formData object fields and the corresponding editors without widget rerendering.

The updateData(dataField, value) method enables you to update only a single field value.

JavaScript
$("#myForm").dxForm("instance").updateData("OfficeNo", "1003");

The updateData(data) method enables you to update several values at once.

JavaScript
$("#myForm").dxForm("instance").updateData({
    OfficeNo: "1003",
    City: "New York",
    Phone: "+1(555) 555-9244"
});

In MVVM approach, provide two-way binding for the required formData object field.

Angular Approach
JavaScript
var myApp = angular.module('myApp', ['dx']);
myApp.controller("demoController", function ($scope) {
    $scope.firstName = "John";
    $scope.lastName = "Heart";
    $scope.position = "CEO";
    $scope.officeNo = "1003";
    $scope.birthDate = "1964/03/16";
    $scope.hireDate = "1995/01/15";
    $scope.city = "New York";
    $scope.phone = "+1(555) 555-9244";
    $scope.email = "jheart@dx-email.com";
});
HTML
<div ng-controller="demoController">
    . . .
    <div dx-form="{
         . . .
         bindingOptions: {
            formData.FirstName: 'firstName',
            formData.LastName: 'lastName',
            formData.Position: 'position',
            formData.OfficeNo: 'officeNo',
            formData.BirthDate: 'birthDate',
            formData.HireDate: 'hireDate',
            formData.City: 'city',
            formData.Phone: 'phone',
            formData.Email: 'email'
         }
    }"></div>
    . . .
</div>
Knockout Approach
JavaScript
var viewModel = {
    firstName: ko.observable("John"),
    lastName: ko.observable("Heart"),
    position: ko.observable("CEO"),
    officeNo: ko.observable("1003"),
    birthDate: ko.observable("1964/03/16"),
    hireDate: ko.observable("1995/01/15"),
    city: ko.observable("New York"),
    phone: ko.observable("+1(555) 555-9244"),
    email: ko.observable("jheart@dx-email.com")
}
ko.applyBindings(viewModel);
HTML
    <div data-bind="dxForm: {
         . . .
         formData: {
            FirstName: firstName,
            LastName: lastName,
            Position: position,
            OfficeNo: officeNo,
            BirthDate: birthDate,
            HireDate: hireDate,
            City: city,
            Phone: phone,
            Email: email
         }
    }"></div>

Generate Form Data Object

If you create the dxForm widget with manually defined items, you can leave the formData option undefined. In this case, the widget generates a new data object, which can be accessed using the formData option. Each time a user specifies a value of a form field, the widget adds the corresponding field to the generated data object.