Conditional Style

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

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')

tip

Set the IncludeGroupedRows property to true to ensure that grouped rows also have the style applied

Style

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.

note

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

Rule

The Conditional Style rule uses either a Predicate or a Query depending on the complexity of the rule required.

note

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

caution

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.

Predicate

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

Query

For more complicated scenarios there is an option to use a Query (either Named or bespoke) which can reference multiple columns and can contain AND and OR and more advanced logic.

warning

If the Scope is Whole Row then only a Query can be used

UI Elements

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.

  • Column Menu - Add Conditional Style Menu Item opens the Conditional Style Wizard

Entitlements

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.

Predefined Config

In Conditional Style Predefined Config it is possible to define multiple Conditional Styles.

Each Conditional Style object is defined as follows:

PropertyDescriptionDefault
IncludeGroupedRowsWhether to apply Style in Grouped Rowsfalse
RulePredicate-based Rule to use for deciding if a style needs to be applied.
ScopeWhere Style is applied - can be whole Row, some Columns or all Columns of given DataType
StyleAdaptable 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
export default {
ConditionalStyle: {
ConditionalStyles: [
{
Scope: {
DataTypes: ['Number'],
},
Style: {
ForeColor: 'Green',
},
Rule: {
Predicate: {
PredicateId: 'GreaterThan',
Inputs: [2000000],
},
},
},
{
Scope: {
ColumnIds: ['InvoicedCost'],
},
Style: {
BackColor: '#ffffcc',
FontStyle: 'Italic',
ForeColor: '#000000',
},
Rule:{
BooleanExpression: '[InvoicedCost] > 1000 AND [ItemCount] < 20',
}
IncludeGroupedRows: true,
},
],
},
} as PredefinedConfig;

API

The Conditional Style API contains the following methods:

MethodDescription
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

FAQ

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

More Information