Detail View Layout Customization

Feb 17, 2026
10 minutes to read

XAF allows you to customize the generated application layout using one of the following methods.

Design-Time Customization

You can customize View layout in the Model Editor. The DashboardView and DetailView nodes have a Layout child node, which allows you to access to the layout settings.

When the Layout node is selected, the Model Designer displays a design surface that imitates the current View. This design surface allows you to see how the View will be displayed at runtime. The Layout node exposes a tree of nodes that comprises groups, tabbed groups, layout items, labels, separators, etc.

To modify a default View Items layout, right-click on an empty space and choose Customize Layout. This will invoke the Customization form allowing you to drag View Items where required. The graphical prompts will display the item’s target position.

In the Model Designer, you can remove and restore View Items by dragging the required items from the View to the Customization form, and vice versa.

To see the View Items layout tree, use the Layout Tree View tab on the Customization form. Invoke the context menu for additional customization options.

For more information about the Customization form, the Layout Tree View tab, and its context menu, refer to the following article: Default Runtime Customization.

In the Layout node’s child nodes, you can find the following customization options:

Reorder Layout Groups and Layout Items
Modify a Caption
Specify the direction of nested Layout Groups or Layout Items
Move a Layout Item to another Layout Group

You can add new items to a Detail View. Right-click the DetailView | Items node, navigate to the Add… group, choose the required View Item type and customize the newly added item as needed.

After the new item is added, put it on the Detail View as described above.

If you require layout customizations to affect all application platforms (WinForms and ASP.NET Core Blazor), adjust the layout at the Module Project level. To customize an application for a specific platform, adjust the layout at the corresponding project level. Refer to the Application Solution Structure article for additional information.

Note

Splitter , Separator , and Label items are specific to the DevExpress WinForms Layout Control. These items are not available in the Model Editor invoked for an ASP.NET Core Blazor or platform-independent project. They are also not available in the Customization form or in the LayoutGroup node’s Add… context menu. This behavior protects you from errors during layout customization. Add and customize these items (splitter, separator, label) in WinForms projects only.
Several WinForms-specific properties are not available in the Model Editor invoked for an ASP.NET Core Blazor or platform-independent project.

The changes that you perform in the Model Editor invoked for a module (application project) are saved to the Model.DesignedDiffs.xafml (Model.xafml) file located in this module project. These changes will rewrite previous values when you run the application. It is important for you to ensure that values from other *.xafml files will not rewrite your values. To do this, review the *.xafml files that are loaded after your *.xafml file, including the Model.User.xafml generated at runtime. For details on the layer structure of the Application Model, refer to the Application Model Basics topic.

General Layout Settings

A number of layout options that affect all Views are available in the Model Editor’s Options | LayoutManagerOptions node. For example, you can disable the colon sign that is added to item captions using the IModelLayoutManagerOptions.EnableCaptionColon property, or use a custom separator instead of a colon (see IModelLayoutManagerOptions.CaptionColon.)

DetailViewLayout Attribute

You can customize the Detail View’s default layout in a business class code using the DetailViewLayoutAttribute applied to required properties.

csharp

[DetailViewLayoutAttribute("NotesAndRemarks", LayoutGroupType.TabbedGroup, 100)]
public string Notes { get; set; }

Refer to this attribute description to see more examples.

Runtime Customization

In the Model Editor

This feature is available in XAF Windows Forms applications only. You can make changes to a Detail View’s layout as described in the Design Time Customization section above.

To invoke the Model Editor, use the EditModel Action in the root window’s Tools main menu. The EditModel Action is available when a user has permission to customize the Application Model. For additional information about permissions, refer to the following topic: Edit Model Permission.

In Customization Mode

This feature is available in XAF ASP.NET Core Blazor and Windows Forms applications.

To enter customization mode, right-click an empty space in the Detail View you want to edit and select the Customize Layout option in the context menu.

ASP.NET Core Blazor

Windows Forms

Tip

To enable or disable runtime layout customization for the entire application, use the IModelOptions.CustomizationFormEnabled property.
To enable or disable runtime layout customization for a specific View, use the IModelView.CustomizationFormEnabled) property.
You can also use the HideInUI attribute to control any property’s visibility in a UI View.

XAF uses the Application Model to save layout changes made at runtime. The next time you invoke a customized View, the View shows the most recent changes. If you need to roll back the changes, right-click an empty space in the View at runtime and select the Reset Layout option in the context menu. In Windows Forms applications, you can also use the ResetViewSettings Action.

For more information on how XAF stores Application Model changes in different applications, refer to the following topic: Application Model Differences: Storage Types.

Note

For more information about customization mode in Windows Forms applications, refer to the following topic: Default Runtime Customization.

For more information about customization mode in ASP.NET Core Blazor applications, refer to the following topic: Runtime Layout Customization in ASP.NET Core Blazor Applications.

Important Notes

The following are important notes concerning Layout Items.

When you add a new property and thus make a change to the business class structure you created at the start of this XAF application, the Detail View’s layout of the business class is programmed to automatically regenerate. If this occurs, all your layout customizations are discarded. To prevent this, set the IModelDetailView.FreezeLayout property to true. This allows you to retain the Detail View’s layout according to the last saved changes, and prohibit regeneration. However, you need to add new layout items to your Detail View layout if you use this property.
In Windows Forms application, the width of a Layout Item is not locked by default. XAF calculates the width based on the parent Layout Group’s dimensions. Thus, Layout Items from different Layout Groups may have different alignment.
In Windows Forms applications, if you move a Layout Item to a higher-level group, additional spacing between the Item moved and the next Item appears. See the image below.
Items and nested Groups inside each Group can be arranged either vertically or horizontally (see IModelLayoutGroup.Direction). The following image illustrates a layout fragment with complex nesting.
In Windows Forms applications, if you move or hide a Layout Item, its Layout Group stays on the form. In the image below, the “Notes” Item moves from the “Notes” to the “Photo” group.
The Application Model’s Options node contains the LayoutManagerOptions child node. As the name implies, this node’s properties allow you to customize certain settings concerning layout generation.

For more information about the Layout Control and Layout Items, refer to the following topic: Layout Manager.