View Variants (Switch Document Layouts)
- 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.v23.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 or module 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 .NET 6+ 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 Solution Wizard to create a new XAF solution. Select modules in the Choose Additional Modules step.
- 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 23.2\Components\XAF\FeatureCenter.NETFramework.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 Web 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.