Declare Conditional Appearance Rules in Code
- 11 minutes to read
The Conditional Appearance module allows you to change the appearance and visibility of different UI elements, as well as make them disabled/enabled. These elements include properties in List Views, built-in Property Editors and Static Text in Detail Views. In addition, you can make Actions visible/invisible or enabled/disabled. The required appearance can be applied under the specified conditions. To apply a particular appearance to the target UI element, define a rule in code or in the Application Model. In this topic, you will learn how to define an appearance rule in code. To learn the general information on the Conditional Appearance module and appearance rules, refer to the Conditional Appearance Module Overview topic. To learn how to define appearance rules in the Application Model, refer to the Declare Conditional Appearance Rules in the Application Model topic.
Prerequisites
Make sure that the following conditions are met:
- Your project contains the DevExpress.ExpressApp.ConditionalAppearance NuGet package.
The MySolution.Blazor.Server\Startup.cs or MySolution.Win\Startup.cs files contain the following line:
builder.Modules // ... .AddConditionalAppearance() // ...
For more information on how to add the Conditional Appearance Module, see: Conditional Appearance (Manage UI State).
General Information
To define an appearance rule in code, use the AppearanceAttribute. This attribute is declared in the DevExpress.ExpressApp.ConditionalAppearance namespace of the DevExpress.ExpressApp.ConditionalAppearance.v24.1.dll assembly. So to use the attribute, you will need to add the corresponding using (Imports in VB) directive.
When applying the Appearance attribute, set the rule’s Id using the AppearanceAttribute.Id parameter. The remaining rule properties are specified using the attribute’s named parameters.
- AppearanceAttribute.AppearanceItemType
- AppearanceAttribute.TargetItems
- AppearanceAttribute.Context
- AppearanceAttribute.Criteria
- AppearanceAttribute.BackColor
- AppearanceAttribute.FontColor
- AppearanceAttribute.FontStyle
- AppearanceAttribute.Enabled
- AppearanceAttribute.Visibility
- AppearanceAttribute.Method
- AppearanceAttribute.Priority
When using the Appearance attribute, first specify which UI elements you are going to affect via the appearance rule: apply the Appearance attribute to either a business class or a business class property, and set its AppearanceItemType and TargetItems parameters. The following table illustrates several use cases.
Element to be affected | Attribute Target | AppearanceItemType parameter | TargetItems parameter |
---|---|---|---|
Business class property - Approach 1 | Property | ViewItem | |
Business class property - Approach 2 | Class | ViewItem | The required property’s name |
All business class properties | Class | ViewItem | “*” |
Several properties - Approach 1 | Class | ViewItem | A semicolon-separated list of property names |
Several properties - Approach 2 | Class | ViewItem | The “*” wildcard, followed by a semicolon-separated list of excluded properties. |
Actions | Class | Action | A semicolon-separated list of Action identifiers |
Property’s Layout Item | Property | LayoutItem | |
Layout Group(simple or tabbed group) | Class | LayoutItem | The Layout Group’s Id specified in the Application Model |
Then, specify the rule’s activity scope. For this purpose, use the following Appearance attribute parameters:
- AppearanceAttribute.Context - specify in which Views to activate the rule;
- AppearanceAttribute.Criteria - specify which criteria must be satisfied by the target object;
- AppearanceAttribute.Method - specify the method that returns true for the rule’s activation (you can apply the Appearance attribute to this method and miss the Method parameter in the attribute’s definition);
- AppearanceAttribute.Priority - specify the current rule’s volume when several rules affect the same UI element.
For details on these attribute parameters refer to their description in the Reference help section.
The last step in the appearance rule definition is specifying required appearance customizations. For this purpose, use the following attribute parameters.
- AppearanceAttribute.BackColor
- AppearanceAttribute.FontColor
- AppearanceAttribute.FontStyle
- AppearanceAttribute.Enabled
- AppearanceAttribute.Visibility
Rules declared via the Appearance attribute are reflected in the Application Model. They are collected in the corresponding Application | BOModel | <Class> |AppearanceRules node. For details on this node, refer to the Declare Conditional Appearance Rules in the Application Model topic.
Examples
According to the rule demonstrated in the example below, the Product objects whose Price is more than 50 will be displayed in Red background using Maroon font color in List Views.
using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("RedPriceObject", AppearanceItemType = "ViewItem", TargetItems = "*",
Criteria = "Price>50", Context = "ListView", BackColor = "Red",
FontColor = "Maroon", Priority = 2)]
public class Product : BaseObject {
public virtual string Name { get; set; }
public virtual decimal Price { get; set; }
public virtual ProductStatus Status { get; set; }
public virtual Category Category { get; set; }
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
According to the rule demonstrated in the example below, the Category property in List Views will be displayed in Blue font color when its value is “Seafood”.
using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("CategoryColoredInListView", AppearanceItemType = "ViewItem", TargetItems = "Category",
Criteria = "Category = 'Seafood'", Context = "ListView", FontColor = "Blue", Priority = 1)]
public class Product : BaseObject {
public virtual Category Category { get; set; }
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public virtual string Name { get; set; }
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
According to the rule demonstrated in the example below, the Category
layout item’s caption in Product Detail Views is displayed in blue when the product’s category is “Seafood”.
using DevExpress.ExpressApp.ConditionalAppearance;
//...
public class Product : BaseObject {
[Appearance("CategoryColoredInDetailView", AppearanceItemType = "LayoutItem",
TargetItems = "Category", Criteria = "Category = 'Seafood'", Context = "DetailView",
FontColor = "Blue")]
public virtual Category Category { get; set; }
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public virtual string Name { get; set; }
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
According to the rule demonstrated in the example below, the “ProductParameters” layout group caption in the Product Detail View will be displayed in Blue font color when the Category property is set to “Seafood”.
using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("LayoutGroupColoredInDetailView", AppearanceItemType = "LayoutItem",
TargetItems = "ProductParametersLayoutGroup", Criteria = "Category = 'Seafood'",
Context = "Product_DetailView", FontColor = "Blue")]
public class Product : BaseObject {
public virtual string Name { get; set; }
public virtual decimal Price { get; set; }
public virtual ProductStatus Status { get; set; }
public virtual Category Category { get; set; }
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
public virtual string Name { get; set; }
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
According to the rule demonstrated in the example below, a Product’s Deactivate Action will be disabled when the Status property is set to “Inactive” in all Product Views. Note that the Action ID specified in this rule contains the class name (“Product.Deactivate”), because the Deactivate Action is declared using the ActionAttribute. If an Action is declared in a Controller, specify its ID without the class name, e.g., “Delete” or “Unlink”.
using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("ActionState", AppearanceItemType = "Action",
TargetItems = "Product.Deactivate",
Criteria = "Status = 'Inactive'", Context = "Any", Enabled = false)]
public class Product : BaseObject {
public virtual ProductStatus Status { get; set; }
[Action(PredefinedCategory.RecordEdit, Caption = "Deactivate Product...", AutoCommit = true,
TargetObjectsCriteria = "Status = 'Active'",
SelectionDependencyType = MethodActionSelectionDependencyType.RequireSingleObject)]
public void Deactivate() {
Status = ProductStatus.Inactive;
}
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
According to the rule demonstrated in the example below, the Product objects in List Views will be displayed in Green background using Black font color when the RuleMethod returns true.
using DevExpress.ExpressApp.ConditionalAppearance;
//...
public class Product : BaseObject {
public virtual decimal Price { get; set; }
public virtual ProductStatus Status { get; set; }
[Appearance("RuleMethod", AppearanceItemType = "ViewItem", TargetItems = "*", Context = "ListView",
BackColor = "Green", FontColor = "Black")]
public bool RuleMethod() {
if (Price < 10 && Status == ProductStatus.Active) {
return true;
}
else {
return false;
}
}
}
// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.
There are more examples demonstrated in the FeatureCenter demo installed with XAF. This demo is located in the %PUBLIC%\Documents\DevExpress Demos 24.1\Components\XAF\FeatureCenter.NETFramework.XPO folder by default.