Skip to main content

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:

  1. Your project contains the DevExpress.ExpressApp.ConditionalAppearance NuGet package.
  2. 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.

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:

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.

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.

See Also