Class: ConditionalFormat

ConditionalFormat(oConditionalFormats, oOptions)

new ConditionalFormat(oConditionalFormats, oOptions)

The conditional formatting feature allows you to apply formats to a cell or range of cells, and have that formatting change depending on the value of the cell or the value of a formula. The ConditionalFormat(key) method gets the conditional format by index, key or reference.

Every option of the ConditionalFormatOptions type has associated a property of the ConditionalFormat object. For instance, the option:

expression {string}, specifies the condition of the conditional format
is associated with the property:
Expression {string}, specifies the condition of the conditional format
which means that the following statements are equivalent:
oConditionalFormat.Options = {expression: "%0 >= 0"}
oConditionalFormat.SetOptions({expression: "%0 >= 0"})
oConditionalFormat.Expression = "%0 >= 0"
oConditionalFormat.Setexpression("%0 >= 0")
where oConditionalFormat is an object of ConditionalFormat type
Parameters:
Name Type Description
oConditionalFormats ConditionalFormats Indicates an object of ConditionalFormats type that's the owner collection of this conditional format
oOptions object Specifies an object of ConditionalFormatOptions type that holds information about the conditional format, such as caption, image and so on. If the oOptions parameter is not-of object type it indicates the conditional format's caption instead

Methods

GetApplyTo() → {any}

The GetApplyTo() method indicates whether the format is applied to items or columns
Returns:
Specifies whether the format is applied to items or columns
Type
any

GetEnabled() → {boolean}

The GetEnabled() method determines whether the conditional format is enabled or disabled
Returns:
Returns true if the conditional format is enabled, or false if the conditional format is disabled
Type
boolean

GetExpression() → {any}

The GetExpression() method indicates the conditional format's expression
Returns:
Specifies the conditional format's expression The expression supports the following keywords:
value, gets the value of the cell being formatted/evaluated
The expression supports the following variables:
%0, %1, %2, ... specifies the value of the cell in the conditional format with the index 0, 1 2, ...
%C0, %C1, %C2, ... specifies the caption of the cell, or the string the cell displays in the conditional format with the index 0, 1 2, ...
%CD0, %CD1, %CD2, ... specifies the cell's user-date in the conditional format with the index 0, 1 2, ...
%CS0, %CS1, %CS2, ... specifies the cell's state in the conditional format with the index 0, 1 2, ...
The expression supports the following functions:
index, gets the index of the item
rindex, returns the recursive-index of the item
pos, returns the relative position of the item (the position within the parent's children collection)
rpos, returns the recursive relative-position of the item (the position within the parent's children collection)
opos, returns the relative old position of the item (the position within the parent's children collection)
ropos, returns the recursive relative-old-position of the item (the position within the parent's children collection)
apos, returns the absolute position of the item (the position from the first visible item)
rapos, returns the recursive absolute-position of the item (the position from the first visible item)
Type
any

GetKey() → {string}

The GetKey() method returns the conditional format's key.
Returns:
Returns the conditional format's exHTML key it displays
Type
string

GetOptions() → {object}

The GetOptions() method returns the conditional format's options at once
Returns:
Returns an object of ConditionalFormatOptions type
Type
object
Example
The following statements are equivalents:

 oConditionalFormat.GetOptions(), gets the conditional format's options
 oConditionalFormat.Options, gets the conditional format's options

where oConditionalFormat is an object of ConditionalFormat type

GetShape() → {any}

The GetShape() method defines the shape for the conditional format itself (conditional format's header)
Returns:
Returns the shape for the conditional format itself, as one of the following:
  • {null}, no custom-shape is applied
  • the shape's name within the exontrol.Shape.Tree or exontrol.Shape namespace
  • a CSS color
  • a JSON string-representation of an object of exontrol.Def.Shape type, for the column itself
  • an object of {normal,hover,click,disabled} type. The normal, hover, click and disabled are objects of exontrol.Def.Shape type
Type
any

GetValid() → {boolean}

The GetValid() method checks whether the expression is syntactically correct
Returns:
Returns true, if the expression is syntactically correct
Type
boolean

Remove()

The Remove() method removes the conditional format itself from its collection

SetApplyTo(value)

The SetApplyTo() method applies the format to items or columns
Parameters:
Name Type Description
value any Specifies whether the format is applied to items or columns
Example
null{null} or -1 {number}, the format is applied to items (negative-number)
 0 {number}, the format is applied to all cells of the conditional format with the index 0 that verify the condition
 "C1,C2" {string}, the format is applied to all cells of the columns "C1" and "C2" that verify the condition

SetEnabled(value)

The SetEnabled() method enables or disables the conditional format
Parameters:
Name Type Description
value boolean Indicates a boolean expression that specifies whether the conditional format is enabled or disabled
Example
false {boolean}, disables the condition (no format or shape is applied if the condition is invalid or disabled)
 true {boolean}, enables the condition

SetExpression(value)

The SetExpression() method sets the conditional format's expression
Parameters:
Name Type Description
value any Specifies the conditional format's expression The expression supports the following keywords:
value, gets the value of the cell being formatted/evaluated
The expression supports the following variables:
%0, %1, %2, ... specifies the value of the cell in the conditional format with the index 0, 1 2, ...
%C0, %C1, %C2, ... specifies the caption of the cell, or the string the cell displays in the conditional format with the index 0, 1 2, ...
%CD0, %CD1, %CD2, ... specifies the cell's user-date in the conditional format with the index 0, 1 2, ...
%CS0, %CS1, %CS2, ... specifies the cell's state in the conditional format with the index 0, 1 2, ...
The expression supports the following functions:
index, gets the index of the item
rindex, returns the recursive-index of the item
pos, returns the relative position of the item (the position within the parent's children collection)
rpos, returns the recursive relative-position of the item (the position within the parent's children collection)
opos, returns the relative old position of the item (the position within the parent's children collection)
ropos, returns the recursive relative-old-position of the item (the position within the parent's children collection)
apos, returns the absolute position of the item (the position from the first visible item)
rapos, returns the recursive absolute-position of the item (the position from the first visible item)
Example
"1" {string}, highlights all cells or items.
 "%0 >= 0" {string}, highlights the cells or items, when the cells in the first conditional format have the value greater or equal with zero
 "%0 startwith 'A'" {string}, highlights the cells or items, when the cells in the first column starts with A

SetKey(value)

The SetKey() method assigns a new key to the conditional format
Parameters:
Name Type Description
value string Specifies a new key to be assigned to the conditional format
Example
"cond" {string}, defines the conditional format with the giving key (cond). You can use the ConditionalFormats.Item("cond") method to request the conditional format giving its key.

SetOptions(oOptions)

The SetOptions() method changes the conditional format's options (visibility, caption, ...) at once
Parameters:
Name Type Description
oOptions object Specifies an object of ConditionalFormatOptions type that holds information about the conditional format, such as caption, image and so on. If the oOptions parameter is not-of object type it indicates the conditional format's caption instead

SetShape(value)

The SetShape() method changes the shape for the conditional format itself (conditional format's header)
Parameters:
Name Type Description
value any The value could be any of the following: The shape field can be any of the following:
  • {null}, no custom-shape is applied
  • the shape's name within the exontrol.Shape.Tree or exontrol.Shape namespace
  • a CSS color
  • a JSON string-representation of an object of exontrol.Def.Shape type, for the column itself
  • an object of {normal,hover,click,disabled} type. The normal, hover, click and disabled are objects of exontrol.Def.Shape type