View Variants (Switch Document Layouts)

• Dec 24, 2025
• 5 minutes to read

The XAF allows View customization at design time, in code, and by end-users. You may wish to provide several customized variants of the same View, and allow an end-user to choose the desired View Variant at runtime. For instance, end-users may need to use different List View column sets and Detail View layouts in different scenarios. They may also need to use two List View modes: a single List View and a List View with a Detail View (see IModelListView.MasterDetailMode). XAF offers built-in implementation of this feature in the ViewVariantsModule, which is declared in the DevExpress.ExpessApp.ViewVariantsModule.v25.2.dll assembly. This topic will show you how to use this module to provide multiple versions of the same View. The following steps explain how to apply this module’s capabilities.

To apply the View Variants module capabilities, add this module to your application project. For this purpose, use the Application Designer or Module Designer. Be sure to rebuild your solution after making changes in the Designer.

Note

• In XAF applications, you can call the AddViewVariants<TBuilder>(IModuleBuilder<TBuilder>, Action<ViewVariantsOptions>) method in your ASP.NET Core Blazor/WinForms application builder.

• You can add modules to your application when you use the Template Kit to create a new XAF solution. Select modules in the Additional Modules section.

• To add an extra module in code, add it to the XafApplication.Modules or ModuleBase.RequiredModuleTypes list (adding a reference to the module assembly is insufficient).

To see a demonstration of View Variants, you can run the Feature Center application that ships with XAF (the %PUBLIC%\Documents\DevExpress Demos 25.2\Components\XAF\FeatureCenter.NET.XPO folder), and navigate to the View Variants item, or refer to the Feature Center demo online.

Overview

The View Variants module provides the ChangeVariantController View Controller. It contains the ChangeVariant Action, which allows end-users to select a View Variant to be displayed within the current Window (Frame). This Action is of the SingleChoiceAction type and has the ChangeVariant ID. Its items are specified by the Views | <View> | Variants node of the Application Model. The action is visible if there are two or more Variants child nodes in the current View node.

In a Windows Forms application:

In an ASP.NET Core Blazor application:

To add View Variants, do the following:

• Define a new View for the required object type in the Application Model. To do this, add a new ListView or DetailView node to the Views node, and specify its ModelClass and Id properties. In the node’s context menu, choose Generate content and specify the required settings (column set, layout, etc.). Repeat this step to add as many Views as required.
• Define a new View that will represent the varied List View or Detail View for the required object type. Give it a meaningful ID to distinguish it from other Views of this object type (for instance, add the “_Varied” suffix). This View node will store view variants. Right-click it and select Add… | Variants. The Variants child node will be added.
• Invoke the context menu for the Variants node and select the Add ListView menu item. Specify the newly added node’s IModelVariant.Caption and IModelView.Id properties. Specify the IModelVariant.Id property by selecting View from the drop-down list. Note that the View will be present in this drop-down list if its IModelObjectView.ModelClass property has the same value as the current View. Additionally, you can specify the IModelNode.Index property to set a custom sort order for variants. Repeat this step to add all newly created Views and the default View.
• Specify the IModelVariants.Current property of the Variants node by selecting a variant ID from the drop-down list. This variant will be used by default.
• Set the required object’s IModelClass.DefaultListView (IModelClass.DefaultDetailView) property to the Id of the varied View. Alternatively, you can change the View property of a specific NavigationItem node or DetailView of a specific ListView node, to specify the varied view instead of the default view.
• Make sure you have selected the correct Data Access Mode for the root View and for each variant View. See IModelListView.DataAccessMode for details.

The following image illustrates how the varied View and its View Variants are organized in the Application Model.

The image below illustrates the ChangeVariant Action available in a WinForms application after following the steps above.

A variant can be chosen from the drop-down list. Variants are sorted according to their IModelNode.Index property values. Additionally, you can set the Current property of the Variants node to specify the default variant. The previously selected variant ID is stored with user customizations (in the Model.User.xafml file or in browser cookies).

Display View Variants in Navigation

View Variants can be also added to the Navigation. Set the IModelNavigationItemsVariantSettings.GenerateRelatedViewVariantsGroup property to true in the Model Editor.

The image below illustrates the result.

Customize the List of View Variants

You can create a custom IVariantsProvider object that loads View Variants in a custom manner. Assign your VariantsProvider to the ViewVariantsModule.VariantsProvider property to replace the default ModelVariantsProvider that loads View Variants from the Application Model.

See Also

ChangeVariantController

Best practices of creating reusable XAF modules by example of a View Variants module extension

XAF - How to save the currently opened View as a new View Variant at runtime

XAF - How to Save and Share Custom View Settings