The Conditional Style Module enables cells and rows to be given a distinctive style / look and feel when they contain data that matches a specifed Rule.
Conditional Style Object
A Conditional Style object consists of 3 main elements:
- Scope where the Conditional Style is applied.
- Style: how the Conditional Style is applied.
- Rule: when the Conditional Style is applied.
Scope defines where the Conditional Style is applied. Options are:
one (or more) Columns
one (or more) DataTypes (e.g. String, Number, Date etc)
an entire Row (Scope of 'All')
IncludeGroupedRows property to true to ensure that grouped rows also have the style applied
Style is the group of colours and font properties used to render a cell (or row).
It contains fore, back and border colours and a selection of font-related properties.
Style object includes an option to select the name of a pre-existing CSS style instead of creating the style individually - if the css style has been referenced in User Interface Options.
Both Predicates and Expressions are evaluated using the same parser but Expressions are more powerful as they can contain multiple criteria and AND / OR logic
Conditional Styles will only be applied when the cell (or row) values satisfy the predicate (or if an Expression is being used match all the criteria set in the Query).
If there is no match, the default styles for the cell will be used instead.
This is the most common use case: Predicates are easy to use and ideal for when the evaluation required is a single column or operation (e.g. Positive, NonBlank, Greater Than a given value etc.).
If the Scope is Whole Row then only a Query can be used
Conditional Style includes the following UI Elements:
Popup - Shows a list of existing Conditional Styles with Edit and Delete buttons. Plus an Add button to start the Conditional Style Wizard which facilitates the creation and editing of Conditional Styles.
Conditional Style Entitlement Rules:
Full: Everything is available to the User
Hidden: Everything is hidden from the User
ReadOnly: User can see Conditional Styles created as a result of Rules defined in Predefined Config but not add, edit or delete them.
In Conditional Style Predefined Config it is possible to define multiple Conditional Styles.
Each Conditional Style object is defined as follows:
|IncludeGroupedRows||Whether to apply Style in Grouped Rows||false|
|Rule||Predicate-based Rule to use for deciding if a style needs to be applied.|
|Scope||Where Style is applied - can be whole Row, some Columns or all Columns of given DataType|
|Style||Adaptable Style (e.g. font properties and colurs) to apply.|
In this example we create 2 Conditional Styles:
- A ForeColor of 'Green' on all numeric columns with positive values
- A custom Style for the 'InvoicedCost' column in any row which matches the provided Expression
The Conditional Style API contains the following methods:
|addConditionalStyle(conditionalStyle)||Adds new Conditional Style to State|
|editConditionalStyle(conditionalStyle)||Replaces Conditional Style in State with given one|
|editConditionalStyles(conditionalStyles)||Replaces Conditional Styles in State with given ones|
|getAllConditionalStyle()||Gets all Conditional Styles in Adaptable State|
|getConditionalStylePredicateDefs()||Returns all Predicates usable in Conditional Styles|
|getConditionalStylesForColumn(column)||Gets all Conditional Styles that style a given Column|
|getConditionalStyleState()||Retrieves Conditional Style section from Adaptable State|
|getConditionalStylesWithExpression()||Retrieves all Conditional Styles which have an Expression|
|getCondStylePredicateDefsForScope(scope)||Returns all Predicates appropriate for the given Scope|
|getOrderedConditionalStyles()||Retrieves all Conditinal Styles ordered by Column then Row|
|getRowConditionalStyles()||Retrieves all Conditional Styles that style whole row|
|showConditionalStylePopup()||Opens Conditional Style popup screen|
Can we extend the styles screen to add our own additional style elements?
This is not possible unfortunately because each underlying grid needs then to implement that style separately (and not all are DOM based and won't use CSS).
If you would like to add extra properties to Conditional Styles that are not currently present please provide us with the details and we will try to add them in a future release.
Can we provide the name of a css style instead of building it?
Yes, you can do that. When you create a predefined Conditional Style there is a
StyleName property which you can use to provide the name of the css style. If you do that, then its your responsibility to ensure that style is available in your css.
Additionally, you can provide a list of Style Class Names in User Interface Options and then they will be available in a dropdown in the Conditional Styles wizard.
Can we add gradient style to a Conditional Style so the colour transparency changes depending on the value?
No, this is not possible. However, we do have the Percent Bar and Gradient styles in the Format Column Module that both do something similar but for all cells in a column.
Can we add a style that is always applied, i.e. is not based on a condition?
Yes - this is done through the Format Column Module. This uses the same style as a Style Condition but without an accompanying rule (e.g. if a user wants a particular column always to have a certain back colour).