DxFormLayout Class
A Form Layout component.
Namespace: DevExpress.Blazor
Assembly: DevExpress.Blazor.v22.1.dll
NuGet Package: DevExpress.Blazor
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.
Add a Form Layout to a Project
Follow the steps below to add the Form Layout component to an application:
- 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.
- Add the
<DxFormLayout>
…</DxFormLayout>
markup to a.razor
file. - Add layout elements to the component’s markup.
- Bind the Form Layout component to data.
Layout Structure
The Form Layout component can contain only items, groups, and tabs. Place all custom content between the <DxFormLayoutItem>...</DxFormLayoutItem>
tags.
Note
Form Layout items should not contain layout hierarchy objects (groups, tabs, and other items). Otherwise, an exception occurs.
The Bootstrap grid system renders the <DxFormLayout>
. You can specify the number of virtual columns occupied by each layout element. This number is an integer between 1 and 12 that can be specified for five different screen resolutions:
- ColSpanXl
- Specifies the number of columns an item, group, or tab pages occupies on extra large screens (1200px or wider).
- ColSpanLg
- Specifies the number of columns an item, group, or tab pages occupies on a large screen (992px or wider).
- ColSpanMd
- Specifies the number of columns an item, group, or tab pages occupies on medium screens (768px or wider).
- ColSpanSm
- Specifies the number of columns an item, group, or tab pages occupies on small screens (576px or wider).
- ColSpanXs
- Specifies the number of columns an item, group, or tab pages occupies on extra small screens (less than 576px).
<DxFormLayout>
<DxFormLayoutItem Caption="Name" ColSpanLg="4" ColSpanMd="6" ColSpanSm="12">
<DxTextBox />
</DxFormLayoutItem>
</DxFormLayout>
All layout elements are rendered as .col
elements within a single .row
container. An element moves to the next row if the current row does not have enough virtual columns. To explicitly indicate that the element should occupy a new row, use the BeginRow property.
<DxFormLayout>
@* ... *@
<DxFormLayoutItem Caption="Postal/ZIP Code" BeginRow="true" />
</DxFormLayout>
The common settings for all layout elements are listed below:
- BeginRow
- Specifies whether a Form Layout group, tab pages, or item starts a new row.
- Caption
- Specifies a Form Layout group, tab, or item caption.
- CaptionPosition
- Specifies the caption position of a group, tab, or item.
- Visible
- Specifies whether a Form Layout item, group, tab page, or tab is visible.
- CssClass
- Specifies the name of the component’s CSS class.
- ReadOnly
- Specifies whether the Form Layout element (item, group, tab pages, or tab) activates read-only mode for nested auto-generated editors.
- Enabled
- Specifies whether the auto-generated editors in the Form Layout are enabled.
Items
A layout item (DxFormLayoutItem) is a container that arranges nested Blazor components. An item can include a Caption displayed next to the corresponding component.
<DxFormLayout>
<DxFormLayoutItem Caption="Contact Name:">
<DxTextBox @bind-Text="@Name" />
</DxFormLayoutItem>
<DxFormLayoutItem Caption="Birth Date:">
<DxDateEdit @bind-Date="@BirthDate" />
</DxFormLayoutItem>
<DxFormLayoutItem Caption="E-mail:">
<DxTextBox @bind-Text=@Email />
</DxFormLayoutItem>
</DxFormLayout>
@code {
string Name { get; set; } = "Nancy Davolio";
DateTime BirthDate { get; set; } = DateTime.Now.AddYears(-20);
}
The item-related settings are listed below:
- DxFormLayoutItem.Field
- Specifies a data source field assigned to the current layout item.
- DxFormLayout.ItemCaptionAlignment
- Specifies how caption paddings are calculated in the Form Layout component.
- DxFormLayoutItem.CaptionCssClass
- Specifies the name of the CSS class applied to the layout item’s caption.
Groups
A layout group (DxFormLayoutGroup) is a built-in container that allows you to combine layout items, tabs, and other layout groups into panels.
<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>
Tabs
All tabs of the Form Layout are stored in the DxFormLayoutTabPages component. The DxFormLayoutTabPage components implements a single layout tab that serves as a container for layout items and groups. You can customize individual tabs. Refer to the following class description for more information: DxFormLayoutTabPage.
To specify the active tab, use the ActiveTabIndex property:
<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>
Render Mode
Use the RenderMode property to specify how the DxFormLayoutTabPages component loads tab content. The following options are available:
- Default
- The component initially loads only content of an active tab. When a user selects another tab, its content replaces the content of the previously active tab in the DOM. Note the component does not keep the tab’s state.
- AllTabs
- The component renders the content of all tabs in the DOM and maintains the tab’s state. This mode speeds up navigation between tabs, but can increase memory consumption.
- OnDemand
- The component initially loads content of an active tab, then loads the content of other tabs when a user selects them. In this case, the component maintains the tab’s state. Use this mode to improve performance of your application.
The code below demonstrates the OnDemand
mode implementation:
<DxFormLayout CssClass="w-100">
<DxFormLayoutTabPages @bind-ActiveTabIndex="@ActiveTabIndex"
RenderMode="TabsRenderMode.OnDemand">
<DxFormLayoutTabPage Caption="Personal Information">
<DxFormLayoutItem Caption="First Name:" ColSpanMd="6">
<DxTextBox @bind-Text="@FirstName" />
</DxFormLayoutItem>
<DxFormLayoutItem Caption="Last Name:" ColSpanMd="6">
<DxTextBox @bind-Text="@LastName" />
</DxFormLayoutItem>
</DxFormLayoutTabPage>
<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>
</DxFormLayoutTabPage>
<DxFormLayoutTabPage Caption="Additional information">
<DxFormLayoutItem Caption="Birth Date:" ColSpanMd="6">
<DxDateEdit @bind-Date="@BirthDate" />
</DxFormLayoutItem>
<DxFormLayoutItem Caption="Notes:" ColSpanMd="6">
<DxTextBox @bind-Text="@Notes" />
</DxFormLayoutItem>
</DxFormLayoutTabPage>
</DxFormLayoutTabPages>
</DxFormLayout>
@code {
int ActiveTabIndex { get; set; } = 1;
string FirstName { get; set; } = "Nancy";
string LastName { get; set; } = "Davolio";
DateTime BirthDate { get; set; } = DateTime.Now.AddYears(-20);
string Position { get; set; } = "Sales Representative";
DateTime HireDate { get; set; } = DateTime.Now.AddYears(-20);
string Notes { get; set; } = "Education includes a BA in psychology.";
}
Scroll Mode
Specify the ScrollMode property to define how users navigate between tabs when they do not fit into the container by width.
The example below demonstrates how to switch to Auto
navigation mode:
<DxFormLayout CssClass="w-100">
<DxFormLayoutTabPages ScrollMode="TabsScrollMode.Auto">
<DxFormLayoutTabPage Caption="Personal Information">
<DxFormLayoutItem Caption="Contact Name:">
<DxTextBox Text="Name" />
</DxFormLayoutItem>
@* ... *@
</DxFormLayoutTabPage>
@* ... *@
</DxFormLayoutTabPages>
</DxFormLayout>
Bind to Data
<DxFormLayout>
allows you to display and edit data from data source fields. Use the Data to bind the control to a data source and specify target fields. To map a data source field to a layout item, use the item’s Field property.
Once a layout item is bound to a data source field, <DxFormLayout>
tries to determine the corresponding data field type. If the component can determine the type, the corresponding editor appears in the layout item.
Field Data Type | Editor |
---|---|
Boolean | |
Date | |
Numeric | |
String | |
Other |
When a user changes a layout item values, handle the ItemUpdating event to post all changes to the data source. When you use a custom editor in the Form Layout item, the component is not notified when a user changes data within an item’s custom editor. To inform the Form Layout about the change, call the OnChanged(Object) method when an editor value changes. To access a new editor value, use the Value property.
<DxFormLayout Data="@editFormData"
@* ... *@
ItemUpdating="@((pair) => OnItemUpdating(pair.Key, pair.Value))"
CssClass="w-100">
<DxFormLayoutItem Field="@nameof(FormDataItem.Name)"
Caption="Contact Name:"
ColSpanMd="6" />
<DxFormLayoutItem Field="@nameof(FormDataItem.BirthDate)"
Caption="Birth Date:"
ColSpanMd="6" />
<DxFormLayoutItem Field="@nameof(FormDataItem.YearsWorked)"
Caption="Years Worked:"
ColSpanMd="6" />
<DxFormLayoutItem Field="@nameof(FormDataItem.Position)"
Caption="Position:"
ColSpanMd="6">
<DxComboBox Data="@(new List<string>() {
"Sales Representative",
"Designer" })"
Value="@(((string)((ValueEditContext)context).Value))"
ValueChanged="@((string value) =>
((ValueEditContext)context).OnChanged(value))" />
</DxFormLayoutItem>
<DxFormLayoutItem Field="@nameof(FormDataItem.OnVacation)"
Caption="On Vacation:"
ColSpanMd="6" />
</DxFormLayout>
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.
<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();
}
Troubleshooting
If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.