Detail View Layout Customization
- 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
The LayoutGroup, TabbedGroup and LayoutItem nodes have the Index property. Use this property to set the order within specific levels, Layout Groups or Layout Items.
Modify a Caption
Specify whether a caption is displayed for a Layout Group, Tabbed Group or Layout Item using the ShowCaption property.
Specify a Caption for a group or item if you have made it visible. To do this, use the Caption property.
Specify the location of a group or item caption using the CaptionLocation property.
Specify the direction of nested Layout Groups or Layout Items
Specify whether the groups (or items) within one level are arranged consecutively from left to right or from top to bottom. To do that, use the Layout Group’s Direction property.
Move a Layout Item to another Layout Group
Use the drag-and-drop operation to move a Layout Item to the desired 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, Blazor, and ASP.NET Web Forms), 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 Web Forms, 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 Web Forms, ASP.NET Core Blazor or platform-independent project.
- LayoutGroup node’s IModelWinLayoutGroup.TextAlignMode property
- LayoutItem node’s IModelWinLayoutItem.TextAlignMode property
- LayoutItem node’s IModelLayoutItem.SizeConstraintsType property
Perform the customization of these properties at the WinForms project level. To learn more about the size constraints for WinForms controls, refer to the Size and Alignment topic.
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.
[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
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
In ASP.NET Web Forms applications, the View Items layout cannot be customized at runtime.
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 very beginning of this XAF application, the Detail View layout of the business class is programed to automatically regenerate. If this occurs, all your manually applied customizations to the Detail View layout will disappear. To prevent this from happening, set the IModelDetailView.FreezeLayout property to true. This will allow you to freeze the Detail View layout according to the very last saved changes, thus prohibiting regeneration. Make a note, however, that if you use this property, then you are responsible for manually adding new layout items to your Detail View layout.
If you set the IModelDetailView.FreezeLayout property to true, then the Model Editor copies the current state of the layout to the currently edited Application Model layer. Note that you can still remove a child node from the Items child node of the DetailView node. In this instance, however, it will be impossible to retain a frozen layout. Thus, the View Item corresponding to the removed node will be replaced by an empty space item in the Detail View. Setting the FreezeLayout property to false is analogous to executing the Model Editor‘s “Reset Differences” command, which will revert all customizations to their original default state.
Note
After manually customizing the layout of a business class View, you must set the FreezeLayout property to true if you plan to introduce additional properties to the business class later. If you do not set the property to true, the layout may become corrupted after introducing new business class properties. In this scenario, based on the layout rules, the layout generator may create a default layout that differs greatly from the original default layout. After applying your manual layout customizations stored in the Application Model differences file, the resulting layout will also be completely different from the original layout. The resulting layout may even become corrupted. To prevent this, always set the FreezeLayout property to true before introducing new business class properties if you have previously customized the default layout. Generally, any changes to the BO class may affect the layout generation - the FieldSizeAttribute attribute on string type properties, the Aggreagted attribute on reference type properties, the ExpandObjectMembersAttribute attribute, etc.
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.
Place Items in the same Group to keep them aligned.
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.
If you wish to keep equal spacing between Items, keep them in the same Group.
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.
All components within the same group have the same orientation, as shown by dual arrows. To arrange two groups horizontally, thus forming two columns of Items, you must put these two groups into another group. This process is called wrapping. Extra wrapping groups are created automatically when you drag items on the Layout design surface. Auto-generated wrapping groups usually have a random ID with the “Auto” prefix, except in ASP.NET Core Blazor apps where they are named “Group” with an optional number after.
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 “Notes” Group becomes empty. This empty Layout Group may interfere with your layout. So, you may need to remove the empty Layout Group. You can also use the IModelWinLayoutManagerOptions.InvisibleGroupVerticalDistance property to specify how the empty group affects the vertical space between visible items.
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.
Note
The LayoutManagerOptions node exposes several WinForms specific properties (see the IModelWinLayoutManagerOptions interface’s members list). Perform the customizations of these properties at the WinForms project level.
To learn more about the Layout Control and Layout Items, refer to Layout Manager documentation.