DxFormLayout Class

A Form Layout component.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v21.2.dll

Declaration

public class DxFormLayout :
    DxComponentBase,
    IFormLayout,
    IFormLayoutLevel,
    ISizeModeAccessor,
    IRequireSelfCascading,
    IServiceProviderAccessor

Remarks

The DevExpress Form Layout for Blazor (<DxFormLayout>) consists of data editors and allows you to create responsive edit forms that are automatically arranged.

Blazor Form Layout

Run Demo Watch Video

Add a Form Layout to a Project

Follow the steps below to add the Form Layout component to an application:

  1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
  2. Add the <DxFormLayout></DxFormLayout> markup to a Razor page.
  3. Add layout items <DxFormLayoutItem></DxFormLayoutItem> into the component’s markup.
  4. Bind the Form Layout component to data.
  5. (Optional) Combine layout items into groups or tabs (see the sections below).

Layout Items

<DxFormLayout> consists of multiple layout items (DxFormLayoutItem) - containers that arrange nested Blazor components. An item can include a caption displayed against the corresponding component. To specify the item’s nested component, use the item’s Template property.

FormLayout Layout Items

<DxFormLayout>
    <DxFormLayoutItem Caption="Contact Name:" ColSpanMd="6">
        <DxTextBox @bind-Text="@Name" />
    </DxFormLayoutItem>
    <DxFormLayoutItem Caption="Birth Date:" ColSpanMd="6">
        <DxDateEdit @bind-Date="@BirthDate" />
    </DxFormLayoutItem>
</DxFormLayout>

Note

Item templates should not include layout hierarchy objects (groups, items). Otherwise, an exception occurs.

The Bootstrap grid system renders the <DxFormLayout>. You can specify the number of virtual columns each layout item occupies. This number is an integer between 1 and 12 that can be specified for five different screen resolutions:

  • ColSpanXl - Extra large screens (1200px or wider).
  • ColSpanLg - Large screens (992px or wider).
  • ColSpanMd - Medium screens (768px or wider).
  • ColSpanSm - Small screens (576px or wider).
  • ColSpanXs - Extra small screens (less than 576px).
<DxFormLayout>
    <DxFormLayoutItem Caption="Name" ColSpanLg="4" ColSpanMd="6" ColSpanSm="12">
        <DxTextBox @bind-Text="@Name"></DxTextBox>
    </DxFormLayoutItem>
</DxFormLayout>

All layout items are rendered as .col elements within a single .row container. An item moves to the next row if there are not enough virtual columns within the current row. To explicitly indicate that the item should be placed into a new row, use an item’s BeginRow property.

<DxFormLayout Data="@DataSource">
    <DxFormLayoutItem Caption="Postal/ZIP Code" BeginRow="true" />
</DxFormLayout>

Run Demo: Form Layout - Item Wrapping

The table below lists the main layout item settings.

Member

Description

CaptionPosition

Specifies the caption position.

Field

Specifies a data source field assigned to the current layout item.

Visible

Specifies whether a Form Layout item, group, tab page, or tab is visible.

ItemCaptionAlignment

Specifies how caption paddings are calculated in the Form Layout component.

CssClass

Specifies the name of a CSS class applied to a layout item.

CaptionCssClass

Specifies the name of the CSS class applied to the layout item’s caption.

ReadOnly

Specifies whether the Form Layout element (item, group, tap, or tab page) activates read-only mode for nested auto-generated editors.

Enabled

Specifies whether the auto-generated editors in the Form Layout are enabled.

View Example: How to change DxFormLayout's item and group visibility

Bind to Data

<DxFormLayout> allows you to display and edit data from the data source fields. You do not have to bind each layout item to a data source and specify proper label captions that correspond to field names. This is done automatically. Bind the control to a data source using the Data property and specify which fields are to be displayed. To set up correspondence between a data source field and a layout item, use the item’s Field property. Once a user changes a layout item’s value, post all changes to a data source. To do so, handle the ItemUpdating event.

FormLayout Data Binding

<DxFormLayout Data="@editFormData"
              ItemUpdating="@((pair) => OnItemUpdating(pair.Key, pair.Value))">
    <DxFormLayoutItem Field="@nameof(FormDataItem.Name)" Caption="Contact Name:" />
    <DxFormLayoutItem Field="@nameof(FormDataItem.BirthDate)" Caption="Birth Date:" />
    <DxFormLayoutItem Field="@nameof(FormDataItem.YearsWorked)" Caption="Years Worked:" />
    <DxFormLayoutItem Field="@nameof(FormDataItem.Position)" Caption="Position:" >
        <DxComboBox Data="@(new List<string>() { "Sales Representative", "Designer" })"
                    Value="@(((string)((ValueEditContext)context).Value))"
                    ValueChanged="@((string value) => ((ValueEditContext)context).OnChanged(value))">
        </DxComboBox>
    </DxFormLayoutItem>
    <DxFormLayoutItem Field="@nameof(FormDataItem.OnVacation)" Caption="On Vacation:" ColSpanMd="6" /> 
</DxFormLayout>

Run Demo: Form Layout - Bind to Data

Once a layout item is bound to a data source field, <DxFormLayout> tries to determine the corresponding data field’s type. If the component can determine the type, it displays the corresponding editor within the layout item.

Field Data Type

Editor

Boolean

CheckBox

Date

Date Edit

Numeric

Spin Edit

String

Text box

Other

Text box

To display a custom editor within a bound layout item, use the item’s Template property.

Groups

A layout group (DxFormLayoutGroup) is a built-in container that allows you to combine layout items and other layout groups into titled panels. You can use the ColSpanXX properties (see the section above) to specify the width of layout groups.

FormLayout Groups

<DxFormLayout>
    <DxFormLayoutGroup Caption="Personal Information" ColSpanMd="6">
        <DxFormLayoutItem Caption="First Name:" ColSpanMd="12">
            <DxTextBox @bind-Text="@FirstName" />
        </DxFormLayoutItem>
        <DxFormLayoutItem Caption="Last Name:" ColSpanMd="12">
            <DxTextBox @bind-Text="@LastName" />
        </DxFormLayoutItem>
        <DxFormLayoutItem Caption="Birth Date:" ColSpanMd="12">
            <DxDateEdit @bind-Date="@BirthDate" />
        </DxFormLayoutItem>
    </DxFormLayoutGroup>
    @* ... *@
</DxFormLayout>

Use the CaptionCssClass property to customize a group caption. The following code snippet applies a custom CSS class to the input’s text:

<style>
    .my-style {
        text-decoration: underline;
    }
</style>

<DxFormLayout>
    <DxFormLayoutGroup Caption="Personal Information" ColSpanMd="6" CaptionCssClass="my-style">
        <DxFormLayoutItem Caption="First Name:" ColSpanMd="12">
            <DxTextBox @bind-Text="@FirstName" />
        </DxFormLayoutItem>
        @* ... *@
    </DxFormLayoutGroup>
</DxFormLayout>

Group Caption CSS

Run Demo: Form Layout - Groups

View Example: How to change DxFormLayout's item and group visibility

Tabs

A layout tab (DxFormLayoutTabPage) is a built-in tabbed container for layout items and groups. All the Layout Form’s tabs are stored in the DxFormLayoutTabPages collection. To specify the active tab, use the zero-based ActiveTabIndex property.

FormLayout Tabs

<DxFormLayout>
    <DxFormLayoutTabPages ActiveTabIndex="1">
        @* ... *@
        <DxFormLayoutTabPage Caption="Work Information">
            <DxFormLayoutItem Caption="Position:" ColSpanMd="6">
                <DxTextBox @bind-Text="@Position" />
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Hire Date:" ColSpanMd="6">
                <DxDateEdit @bind-Date="@HireDate" />
            </DxFormLayoutItem>
            <DxFormLayoutItem Caption="Notes:" ColSpanMd="6">
                <DxTextBox @bind-Text="@Notes" />
            </DxFormLayoutItem>
        </DxFormLayoutTabPage>
    </DxFormLayoutTabPages>
</DxFormLayout>

Use the CaptionCssClass to specify the CSS class name applied to a tab’s caption. In the following example, the CSS rule changes the font weight:

<style>
    .my-style {
        font-weight: 900;
    }
</style>

<DxFormLayout>
    <DxFormLayoutTabPages ActiveTabIndex="1">
        @* ... *@
        <DxFormLayoutTabPage Caption="Work Information" CaptionCssClass="my-style">
            <DxFormLayoutItem Caption="Position:" ColSpanMd="6">
                <DxTextBox @bind-Text="@Position" />
            </DxFormLayoutItem>
            @* ... *@
        </DxFormLayoutTabPage>
    </DxFormLayoutTabPages>
</DxFormLayout>

Tab Caption CSS

Run Demo: Form Layout - Tabbed Groups

Input Validation

You can add the Form Layout component to the Blazor’s standard EditForm. This form validates user input based on data annotation attributes defined in a model and indicates errors.

For more information, refer to the following help topic: Validate Input.

FormLayout Validation

<EditForm Model="@starship" Context="EditFormContext">
    <DataAnnotationsValidator />
    <DxFormLayout>
        <DxFormLayoutItem Caption="Identifier:" ColSpanMd="6" >
            <DxTextBox @bind-Text="@starship.Identifier" />
        </DxFormLayoutItem >
        @*...*@
    </DxFormLayout>
</EditForm>

@code {
    private Starship starship=new Starship();
}

Run Demo: Form Validation - Form Layout

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Inheritance

Object
ComponentBase
DevExpress.Blazor.Base.DxAsyncDisposableComponent
DevExpress.Blazor.Base.DxDecoratedComponent
DxComponentBase
DxFormLayout
See Also