Declare Conditional Appearance Rules in Code

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.

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

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 Product(Session session) : base(session) { }
    public Category Category {
        //...
    }
}
[DefaultProperty("Name")]
public class Category : BaseObject {
    public Category(Session session) : base(session) {}
    public string Name {
        //...
    }
}

According to the rule demonstrated in the example below, the Category layout item's caption in Product Detail Views will be displayed in Blue font color when the Category property value is "Seafood".

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("Name")]
public class Category : BaseObject {
    public Category(Session session) : base(session) {}
    public string Name {
        //...
    }
}

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

According to the rule demonstrated in the example below, a Product's Deactivate Action will be hidden 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("ActionVisibility", AppearanceItemType = "Action",
    TargetItems = "Product.Deactivate",
        Criteria = "Status = 'Inactive'", Context = "Any", Visibility = ViewItemVisibility.Hide)]
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;
    }
}

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 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;
        }
    }
}
Tip

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E3595.

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

See Also