Conditional Style Module

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

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

As can be seen it consists of 4 properties:

  • Scope where the Conditional Style is applied
  • Style: how the Conditional Style is applied
  • Rule: when the Conditional Style is applied
  • GroupedRows: whether to apply the Conditional Style in Grouped Rows

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 AdapTableQL 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

Grouped Rows

Conditional Styles, by default, will not appear if the row is a Grouped Row.

This is becuase these typically either are empty or show aggregated values.

To change this behaviour set IncludeGroupedRows to true when defining the Conditional Style.

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

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that Conditional Styles will still be applied but Users are not permitted to manage or suspend them.

Conditional Style Predefined Config

The Predefined Configuration for the Conditional Style Module

Conditional Style State contains a collection of Conditional Style

PropertyDescription
ConditionalStylesArray of Conditional Styles to ship with Adaptable

Conditional Style Object

A Conditional Style 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.

Conditional Style Predicate

For most use cases the Predicate should be used which i defined as follows:

PropertyDescription
InputsOptional inputs - needed to evaluate some Predicates (e.g. 'GreaterThan')
PredicateIdId of Predicate (e.g. 'Equals', 'GreaterThan')

Conditional Style Query

However in more advanced cases,the Query should be used which is defined as follows:

In this example we create 2 Conditional Styles:

  • A ForeColor of 'Green' on all numeric columns with positive values (using a Predicate)
  • A custom Style for the 'InvoicedCost' column in any row which matches a provided Boolean 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;

Conditional Style API

This 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
getAllActiveConditionalStyle()Gets all Conditional Styles that are active (not-suspended) in Adaptable State
getAllConditionalStyle()Gets all Conditional Styles in Adaptable State
getAllSuspendedConditionalStyle()Gets all Conditional Styles that are suspended in Adaptable State
getConditionalStyleById(id)Get conditional style by id
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 Conditional Styles ordered by Column then Row
getRowConditionalStyles()Retrieves all Conditional Styles that style whole row
showConditionalStylePopup()Opens Conditional Style popup screen
suspendConditionalStyle(conditionalStyle)Suspends conditional style, a readonly object cannot be suspended
unSuspendConditionalStyle(conditionalStyle)Un-suspends or activates a suspended conditional style

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

note

If you would like to add extra properties which are not currently present in the Adaptable Style object that Conditional Style uses 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