JavaScript/jQuery Form - Getting Started
The Form component creates a data entry UI for the underlying data object. The interface consists of automatically-arranged label-editor pairs that correspond to data fields. You can change data values, validate user input, and send the resulting data to the server.
This tutorial shows basic Form component configuration.
Refer to the following sections for more information about each configuration step. The full code is available in the following GitHub repository: getting-started-with-form.
Create a Form
Add DevExtreme to your jQuery application and use the following code to create a Form:
- $(function() {
- $("#form").dxForm({
- // Configuration goes here
- });
- });
- <html>
- <head>
- <!-- ... -->
- <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
- <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/21.1.11/css/dx.common.css">
- <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/21.1.11/css/dx.light.css">
- <link rel="stylesheet" href="index.css">
- <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/21.1.11/js/dx.all.js"></script>
- <script type="text/javascript" src="index.js"></script>
- </head>
- <body class="dx-viewport">
- <div id="form"></div>
- </body>
- </html>
- #form {
- height: 400px;
- }
Populate the Form Fields
To create a data entry UI, assign an object to the formData property. The Form creates a simple item (a label-editor pair) for each field in the formData object.
The Form chooses default editors based on value types: TextBox for string values, NumberBox for numbers, DateBox for dates. You can use the editorType property to specify an editor explicitly. In the following example, the Form uses the default editors:
- $(function() {
- $("#form").dxForm({
- formData: {
- name: "John Heart",
- officeNumber: 901,
- hireDate: new Date(2012, 4, 13)
- }
- });
- });
When you implement this code, the Form is created with the following simple items: TextBox for name
, NumberBox for officeNumber
, and DateBox for the hireDate
data field.
Configure Simple Items
Use the items[] array to configure all form items. This array can contain strings (formData field names) and objects (item configurations). Use a string to create a label-editor pair (a simple item) with default configuration. To change the default settings, declare an item configuration object: specify the dataField and other properties. The example below configures the HireDate
item:
- $(function() {
- $("#form").dxForm({
- formData: {
- name: "John Heart",
- officeNumber: 901,
- hireDate: new Date(2012, 4, 13)
- },
- items: ["name", "officeNumber", {
- dataField: "hireDate",
- editorOptions: {
- disabled: true
- }
- }]
- });
- });
In Columns
The Form can organize items into a fixed number of columns or automatically adjust the layout based on the screen width. To keep the fixed number of columns, initialize the colCount property as done in the code below. To create an adaptive layout, configure the screenByWidth and colCountByScreen properties.
An item can span multiple columns. The example below sets the colSpan property for the Notes
item to 2
so that it spans two columns.
- $(function() {
- $("#form").dxForm({
- formData: {
- name: "John Heart",
- position: "CEO",
- hireDate: new Date(2012, 4, 13),
- officeNumber: 901,
- notes: "John has been in the Audio/Video industry since 1990."
- },
- colCount: 2,
- items: ["name", "position", "hireDate", "officeNumber", {
- dataField: "notes",
- colSpan: 2
- }]
- });
- });
In Groups
You can use groups to organize the data entry form. To add a group, create a group item and nest other items in it as shown in the code below. Items of any type can be nested, including other group items. You can configure each group's layout separately.
The following code creates two groups, each occupies a separate column. The resulting layout looks as follows:
- $(function() {
- $("#form").dxForm({
- formData: {
- name: "John Heart",
- position: "CEO",
- hireDate: new Date(2012, 4, 13),
- officeNumber: 901,
- phone: "+1(213) 555-9392",
- skype: "jheart_DX_skype",
- email: "jheart@dx-email.com"
- },
- colCount: 2,
- items: [{
- itemType: "group",
- caption: "Personal Information",
- items: ["name", "position", "hireDate", "officeNumber"]
- }, {
- itemType: "group",
- caption: "Contacts",
- items: ["phone", "skype", "email"]
- }]
- });
- });
In Tabs
The Form uses the TabPanel component to display tabs. You can specify the tab panel's settings in the tabPanelOptions object. A tab can contain any item type.
The following example shows a tabbed item nested in the Personal Information
group. The resulting Form looks like this:
The code also shows how to configure the tab panel's height property in the tabPanelOptions object.
- $(function() {
- $("#form").dxForm({
- formData: {
- name: 'John Heart',
- position: 'CEO',
- hireDate: new Date(2012, 4, 13),
- officeNumber: 901,
- phone: '+1(213) 555-9392',
- skype: 'jheart_DX_skype',
- email: 'jheart@dx-email.com',
- notes: 'John has been in the Audio/Video industry since 1990.'
- },
- items: [{
- itemType: "group",
- colCount: 2,
- items: [{
- itemType: "group",
- caption: "Employee",
- items: ["name", "position", "hireDate", "officeNumber"]
- }, {
- itemType: "group",
- caption: "Personal Information",
- items: [{
- itemType: "tabbed",
- tabPanelOptions: {
- height: 260
- },
- tabs: [{
- title: "Contacts",
- items: ["skype", "phone", "email"]
- }, {
- title: "Note",
- items: ["notes"]
- }]
- }]
- }]
- }]
- });
- });
Add an Empty Space
If you need to add an empty space between neighboring items, use an empty item. To create an empty item, assign "empty" to the itemType property. To define how many columns the empty item should span, specify the colSpan option. For a list of available properties, refer to the Empty Item section.
In the following example, the empty item spans two columns. The resulting layout looks as follows:
- $(function() {
- $("#form").dxForm({
- formData: {
- // ...
- },
- colCount: 2,
- items: ["name", "position", "hireDate", "officeNumber", {
- itemType: "empty",
- colSpan: 2
- }, "phone", "skype", "email"]
- });
- });
Configure Item Labels
You can configure individual labels in the label object. This object's section lists all available properties.
The following properties apply to all labels in the Form:
The following code shows how to configure the labelLocation property to place labels on top of editors. The example sets the label.alignment property to align the Notes
item label's text to the center:
- $(function() {
- $("#form").dxForm({
- formData: {
- // ...
- },
- labelLocation: "top",
- colCount: 2,
- items: ["name", "position", "hireDate", "officeNumber", {
- dataField: "notes",
- colSpan: 2,
- label: {
- alignment: "center"
- }
- }]
- });
- });
Modify the Form at Runtime
You can change any properties of the form, its items or editors at runtime. Use the option(optionName, optionValue) method to update a Form property, and the itemOption(id, option, value) to update the value of an item property. The code below modifies the readOnly property's value:
- $(function() {
- const form = $("#form").dxForm({
- formData: {
- // ...
- },
- items: [
- // ...
- ]
- }).dxForm("instance");
- $("#checkBox").dxCheckBox({
- text: "Enable read-only mode",
- value: false,
- onValueChanged: function (e) {
- form.option("readOnly", e.value);
- }
- });
- });
Validate the Form Data
DevExtreme includes a validation engine that checks edited values before they are saved. This engine supports different validation rule types.
To apply validation rules to a simple item, specify them in the validationRules[] array. You can specify an item's isRequired property to implicitly apply the RequiredRule.
The following example sets the isRequired property for the Name
item. It also adds the NumericRule for officeNumber
and EmailRule for Email
.
- $(function() {
- $("#form").dxForm({
- formData: {
- // ...
- },
- colCount: 2,
- items: [{
- dataField: "name",
- isRequired: true
- }, {
- dataField: "officeNumber",
- validationRules: [{
- type: "numeric"
- }]
- }, {
- dataField: "email",
- validationRules: [{
- type: "email"
- }]
- }]
- });
- });
You can also call the validate() Form's method to validate all editors simultaneously.
Submit the Form
To submit a form, add a Button Item and set its useSubmitBehavior property to true. The Form can be submitted to a server only if input validation is successful.
The useSubmitBehavior property requires that you wrap the dxForm in the HTML form element. You should also set the preventDefault property to true to override the HTML form submit event as shown in the code example.
The code below shows how to add a submit button, but does not show how to implement the backend. The example displays a confirmation message after the timeout:
- $(function() {
- $("#form").dxForm({
- formData: {
- // ...
- },
- colCount: 2,
- items: [{
- itemType: "group",
- caption: "Personal Information",
- colCount: 2,
- items: [{
- dataField: "name",
- isRequired: "true"
- }, {
- dataField: "officeNumber",
- validationRules: [{
- type: "numeric"
- }]
- }, {
- dataField: "email",
- validationRules: [{
- type: "email"
- }]
- }]
- }, {
- itemType: "button",
- buttonOptions: {
- text: "Submit the Form",
- useSubmitBehavior: true
- }
- }]
- });
- $("#form-container").on("submit", function(e) {
- setTimeout(function () {
- alert("Submitted");
- }, 1000);
- e.preventDefault();
- });
- });
- <form action="/employee-page" id="form-container">
- <div id="form"></div>
- </form>
For further information on the Form UI component, refer to the following resources: