Conditional Style

The Conditional Style Function 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 contains these main elements:

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

Use the ExcludeGroupedRows property to exclude grouped rows from having the style applied.

Style

The Style is the group of colours and font properties used to create the style required; fore and back colours and font elements can be selected.

note

The Style 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 Predefined Config.

Rule

The Conditional Style rule is based either on a Predicate or an Expression 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

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

Expression

For more complicated scenarios there is an option to use an Expression (either Shared or bespoke) which can reference multiple columns and contain AND and OR and more advanced 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 Expression).

If there is no match, the default styles for the cell will be used instead.

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 (and jumps to Step 2 setting the Scope to be that Column automatically).

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
ExcludeGroupedRowsWhether to apply Style in Grouped Rowsfalse
PredicatePredicate-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 Colunns 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',
},
Predicate: {
PredicateId: 'Positive',
},
},
{
Scope: {
ColumnIds: ['InvoicedCost'],
},
Style: {
BackColor: '#ffffcc',
FontStyle: 'Italic',
ForeColor: '#000000',
},
Expression: '[InvoicedCost] > 1000 AND [ItemCount] < 20',
ExcludeGroupedRows: 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
getAllConditionalStyle()Gets all Conditional Styles in Adaptable State
getConditionalStylePredicateDefs()Returns all Predicates that can be used 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 Predefined Config 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?

Not currently but we plan to add this in a future release. We do have the Percent Bar and Gradient Column functions 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 function. 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