Declare Conditional Appearance Rules in Code

• Oct 18, 2023
• 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.2.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.

C# (EF Core)

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.

C# (XPO)

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 Product(Session session) : base(session) { }
    public string Name {
        //...
    }
    public decimal Price {
        //...
    }
    public ProductStatus Status {
        //...
    }
    public Category Category {
        //...
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.ConditionalAppearance
'...
<Appearance("RedPriceObject", AppearanceItemType := "ViewItem", TargetItems := "*", _
Criteria := "Price>50", Context := "ListView", BackColor := "Red", _
FontColor := "Maroon", Priority := 2)> _
Public Class Product
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Name() As String
        '...
    End Property
    Public ReadOnly Property Price() As Decimal
        '...
    End Property
    Public ReadOnly Property Status() As ProductStatus
        '...
    End Property
    Public ReadOnly Property Category() As Category
        '...
    End Property
End Class

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”.

C# (EF Core)

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.

C# (XPO)

using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("CategoryColoredInListView", AppearanceItemType = "ViewItem", TargetItems = "Category",
 Criteria = "Category = 'Seafood'", Context = "ListView", FontColor = "Blue", Priority = 1)]
public class Product : BaseObject {
    public Product(Session session) : base(session) { }
    public Category Category {
        //...
    }
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
    public Category(Session session) : base(session) {}
    public string Name {
        //...
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.ConditionalAppearance
'...
<Appearance("CategoryColoredInListView", AppearanceItemType := "ViewItem", TargetItems := "Category",
 Criteria := "Category = 'Seafood'", Context := "ListView", FontColor := "Blue", Priority := 1)> _
Public Class Product
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Category() As Category
        '...
    End Property
End Class
<DefaultProperty(NameOf(Name))> _
Public Class Category
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Name() As String
        '...
    End Property
End Class

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”.

C# (EF Core)

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.

C# (XPO)

using DevExpress.ExpressApp.ConditionalAppearance;
//...
public class Product : BaseObject {
    public Product(Session session) : base(session) { }
    [Appearance("CategoryColoredInDetailView", AppearanceItemType = "LayoutItem",
         TargetItems = "Category", Criteria = "Category = 'Seafood'", Context = "DetailView",
             FontColor = "Blue")]
    public Category Category {
        //...
    }
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
    public Category(Session session) : base(session) {}
    public string Name {
        //...
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.ConditionalAppearance
'...
Public Class Product
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    <Appearance("CategoryColoredInDetailView", AppearanceItemType := "LayoutItem", _
    TargetItems := "Category", Criteria := "Category = 'Seafood'", _
    Context := "DetailView", FontColor := "Blue")> _
    Public ReadOnly Property Category() As Category
        '...
    End Property
End Class
<DefaultProperty(NameOf(Name))> _
Public Class Category
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Name() As String
        '...
    End Property
End Class

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”.

C# (EF Core)

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.

C# (XPO)

using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("LayoutGroupColoredInDetailView", AppearanceItemType = "LayoutItem",
 TargetItems = "ProductParametersLayoutGroup", Criteria = "Category = 'Seafood'",
 Context = "Product_DetailView", FontColor = "Blue")]
public class Product : BaseObject {
    public Product(Session session) : base(session) { }
    public string Name {
        //...
    }
    public decimal Price {
        //...
    }
    public ProductStatus Status {
        //...
    }
    public Category Category {
        //...
    }
}
[DefaultProperty(nameof(Name))]
public class Category : BaseObject {
    public Category(Session session) : base(session) {}
    public string Name {
        //...
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.ConditionalAppearance
'...
<Appearance("LayoutGroupColoredInDetailView", AppearanceItemType := "LayoutItem",
 TargetItems := "ProductParametersLayoutGroup", Criteria := "Category = 'Seafood'",
 Context := "Product_DetailView", FontColor := "Blue")> _
Public Class Product
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Name() As String
        '...
    End Property
    Public ReadOnly Property Price() As Decimal
        '...
     End Property
    Public ReadOnly Property Status() As ProductStatus
        '...
    End Property
    Public ReadOnly Property Category() As Category
        '...
    End Property
End Class
<DefaultProperty(NameOf(Name))> _
Public Class Category
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Name() As String
        '...
    End Property
End Class

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”.

C# (EF Core)

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.

C# (XPO)

using DevExpress.ExpressApp.ConditionalAppearance;
//...
[Appearance("ActionState", AppearanceItemType = "Action",
    TargetItems = "Product.Deactivate",
        Criteria = "Status = 'Inactive'", Context = "Any", Enabled = false)]
public class Product : BaseObject {
    public Product(Session session) : base(session) { }
    public ProductStatus Status {
        //...
    }   
    [Action(PredefinedCategory.RecordEdit, Caption = "Deactivate Product...", AutoCommit = true,
     TargetObjectsCriteria = "Status = 'Active'",
      SelectionDependencyType = MethodActionSelectionDependencyType.RequireSingleObject)]
    public void Deactivate() {
        Status = ProductStatus.Inactive;
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.ConditionalAppearance
'...
<Appearance("ActionState", AppearanceItemType := "Action", _
TargetItems := "Product.Deactivate", _
Criteria := "Status = 'Inactive'", Context := "Any", Enabled := False)> _
Public Class Product
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Status() As ProductStatus
        '...
    End Property
    <Action(PredefinedCategory.RecordEdit, Caption := "Deactivate Product...", AutoCommit := True,
    TargetObjectsCriteria := "Status = 'Active'", _
    SelectionDependencyType := MethodActionSelectionDependencyType.RequireSingleObject)> _
    Public Sub Deactivate()
        Status = ProductStatus.Inactive
    End Sub
End Class

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.

C# (EF Core)

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.

C# (XPO)

using DevExpress.ExpressApp.ConditionalAppearance;
//...
public class Product : BaseObject {
    public Product(Session session) : base(session) { }
    public decimal Price {
        //...
    }
    public ProductStatus Status {
        //...
    }
    [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;
        }
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.ConditionalAppearance
'...
Public Class Product
        Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Public ReadOnly Property Price() As Decimal
        '...
    End Property
    Public ReadOnly Property Status() As ProductStatus
        '...
    End Property
    <Appearance("RuleMethod", AppearanceItemType := "ViewItem", TargetItems := "*",
     Context := "ListView", BackColor := "Green", FontColor := "Black")> _
    Public Function RuleMethod() As Boolean
        If Price < 10 AndAlso Status = ProductStatus.Active Then
            Return True
        Else
            Return False
        End If
    End Function
End Class

There are more examples demonstrated in the FeatureCenter demo installed with XAF. This demo is located in the %PUBLIC%\Documents\DevExpress Demos 24.2\Components\XAF\FeatureCenter.NETFramework.XPO folder by default.