cellAlert

Specifies a rule for highlighting values in numeric data cells.

Syntax

<blox:cellAlert
      index="cellAlertNumber"
      apply="row|column|cell"
      background="background"
      condition="condition"
      description="description"
      enabled="enabled"
      font="font"
      foreground="foreground"
      format="formatMask"
      group="groupName"
      Image="Image"
      Image_align="left|right|center"
      link="link"
      scope="scope"
      value="value1"
      value2="value2"
/>

where:

Attribute	Required?	Description
`apply`	No	The area of the grid subject to highlighting. Possible values: `ROW`: Highlight the entire row if any cell within the row meets the condition. The first row-applied alert takes precedence over other row-applied alerts. `COLUMN`: Highlight the entire column if any cell within the column meets the condition. The first column-applied alert takes precedence over other column-applied alerts. `CELL`: Highlight only the specific cells that meet the condition (the default). A cell-applied alert will override a row- or column-applied alert.
`background`	No	The cell’s background color. Use a color name or hexadecimal value.
`condition`	Yes	A condition to apply to the cell value. Cells that meet the condition activate the alert. Possible values: `ANY`: Accept cells of any value. `MISSING`: Accept only cells with missing values. `NA`: Accept only cells where the value is not available. The following possible values work together with the `value` and `value2` attributes: `LT` or `<` `GT` or `>` `EQ` or `=` `LTEQ` or `<=` `GTEQ` or `>=` `BETWEEN (`value`,` value2`)`: The value is greater than or equal to value and less than or equal to value2.
`description`	No	A description of the cell alert. This description appears as a tool tip when the user hovers the mouse pointer over the cell.
`enabled`	No	Specifies whether the cell alert is active. Set to `false` to disable a cell alert. The default is `true`.
`font`	No	The font name:style:point use for the cell’s text. font name: Acceptable font name values vary widely by browser and client machine. The following font names are generally accepted: Arial, Courier, Helvetica, TimesRoman, SansSerif, Serif, Monospace. style: Valid font styles are: `plain, italic, bold,` and `bolditalic` point: An integer for point size (usually 8-36). If any of the three attributes is not specified, the default or the currently inherited font value is applied. However, the colons separating the attributes should be included. For examples: font="Arial:bolditalic:12" font=":Bold:12"
`foreground`	No	The cell’s text color. Use a color name or hexadecimal value.
`format`	No	Format mask to apply to cell data.
`group`	No	The name of a group of cell alerts to be treated as a traffic lighting group. Cell alerts with the same group name will show up as one set of traffic lights in the traffic lights creation and management user interface.
`Image`	No	A custom Image that points to the defined link. If you define a link but do not specify a custom Image, a default Image information Image is displayed. The URL to the Image can be either absolute or relative: For absolute URLs, the string should begin with “`http://`”. For relative URLs: Starting the string with a slash (/) indicates that the URL is relative to the server root. Note that the application context needs to be included in the URL. Starting the string without a slash indicates that the URL is relative to the current document.
`Image_align`	No	Sets the position of the custom Image specified by the `Image` attribute. Valid values are: `LEFT`: Place Image before the cell contents (default) `RIGHT`: Place Image after the cell contents
`link`	No	A hyperlink for HTML rendering or a call to a JavaScript™ method. When the link is to a URL, it always opens in a new window. The following entities in the link value are replaced by the indicated values when the link is generated. Entities must start with an ampersand (`&`) and end with a semicolon (`;`). `&Description;` — the cell alert description `&Value;` — the cell value `&ColHeader;` — ampersand-separated dimension/member value pairs `&RowHeader;` — ampersand-separated dimension/member value pairs `&ColIndex;` — the display index (0-based) of the column in the grid `&RowIndex;` — the display index (0-based) of the row in the grid In the following example, the link for the cell alert is set to: link="decoderequest.JSP?row=&RowHeader;&column= &ColHeader;&value=&Value;&rowIndex=&RowIndex;&col Index=&ColIndex;" If the cell with the value of 1234.55 on the third row of the Time dimension and the fourth column of the Product dimension is clicked on, the URL passed through will be: decoderequest.JSP?row=Time=Q3&column=Product=Chocolate%20 Nuts&value=1234.55&rowIndex=2&colIndex=3
`scope`	No	The cells to which the alert should be applied, specified as a series of dimension and member sets enclosed in braces. Use unique names to ensure the right member is found. In Essbase, using display names will not work if DataBlox’s `useAliases` is set to `false` (users can set this through the user interface). For MSAS and Alphablox Cube Server data sources, use unique names starting with the cube name to ensure the correct member at the correct level is found. For SAP BW, always use unique names starting with the query name. Using display names will result in data exception or random data. The scope applies to all axes of the result set, not just the row and column axes. Specify the scope as follows: scope="{d0:m00[,m01,... m0n]} {d1:m10[,m11,...m1n]}..." where `d0` denotes a dimension and `m00` denotes a member within that dimension. For example, for Essbase: scope={Product:Coke} {Scenario: Actual, Budget} For MSAS, Alphablox Cube Server, and SAP BW data sources: scope="{[My Cube].[Product]:[Code]} {[My Cube].[Scenario]: [Actual], [Budget]}" For relational data sources, use "`{columns: columnName [,columnName2,...]}"`. The following member search functions are available for specifying the level of members the cell alert should be applied to: `Leaf()`: the leaf-level descendants of the specified member. Only one member can be specified in the function. Example: `scope="{Market:leaf(East)}"` (Essbase) `Child()`: the children of the specified member. Only one member can be specified in the function. Example: `scope="{Market:child(East)}"` (Essbase) `Descendants()`: all descendants of the specified member. Only one member can be specified in the function. Example: `scope="{[My Cube].[Market]:descendants([East])}"` (MSAS, Alphablox Cube, SAP BW) `Gen()`: all members of the specified generation. Example: `scope="{Market:gen(2)}"` (Essbase) `Not()`: members to which the cell alert should not be applied. You can specify multiple members, separated by a comma. Example: `scope="{[My Cube].[Market]:not([East], [West])}"` (MSAS, Alphablox Cube, SAP BW) The function names are case-insensitive. You can combine the functions in the `scope` statement.
`value`	No	The value to compare when `condition` is `LT`, `GT`, `EQ`, `LTEQ`, `GTEQ`, or the lesser value when `condition` is `BETWEEN`.
`value2`	No	The greater value when `condition` is `BETWEEN`.
`index`	No	The number of the cellAlert to define. If you do not specify this attribute, the next available cellAlert number is used. For instance, if cellAlerts 1-4 are already defined, cellAlert 5 is used.

Usage

Cell alert formatting applies only to numerical content. The number of the cell alert dictates the order in which it is evaluated. Each data cell value is evaluated against all defined alerts, starting with the first cellAlert (index="1"), to the highest defined alert number. The first cell alert that matches the data cell's value and scope is the only alert applied to that cell. Be sure to define cell alerts in the appropriate order if there are overlaps.

If you do not specify a given attribute, its default value applies to the cell. For example, if the default cell background is white and you do not specify a background attribute, the cell background remains white.
For editable cells, cell alert formatting takes precedence over cell editor formatting when a grid first appears. Once a cell is edited, cell editor color settings take precedence over those specified by cell alerts.
Use unique names (base name in Hyperion Essbase) or display names for the dimension and member name string specified in the scope. Using unique names allows you to differentiate between different members or dimensions with the same display names. In Hyperion Essbase, you can specify a member, regardless of the alias table in use, by using the base name.
For MSAS and Alphablox Cube Server data sources, when specifying the scope:
- Enclose dimension and member names in brackets, starting with the cube name. For example, "[My cube].[Market].[West].[California]".
- If a member name is not enclosed in brackets, it will be treated as a member whose name is all uppercase.

Examples

Divide a value by 1000 before displaying it:

<blox:cellAlert index="1" 
                condition="any"
                format="#,###/1000;[red](#,###/1000)"
                background="#3333FF"
                scope="{Scenario: Budget}" />

For MSAS, Alphablox Cube, and SAP BW, the scope should be scope="{[My Cube].[Scenario]: [Budget]}.

Use a symbol (in this case, the percent sign) as a literal character:

<blox:cellAlert index="3" 
                condition="any"
                format="#'[red](#'%')"
                background="#9999FF"
                scope="{Scenario: Variance

For MSAS, Alphablox Cube, and SAP BW, the scope should be scope="{[My Cube].[Scenario]: [Variance %]}.

Multiply a value by 100 before it is displayed and use Times New Roman, boldface, size 14 for font:

<blox:cellAlert index="4" 
                condition="any"
                format="#.##*100%;[red](#.##*100%)"
                background="#CCCCFF" 
                scope="{Scenario: Variance %}"
                font="Times New Roman:bold:14" />

The following example sets cell alert 2 on a grid displayed in a PresentBlox. The alert tests the Central member of the Market dimension for values greater than 1000. When a data value meets this criterion:
- The foreground (font) color becomes green.
- The background color becomes white.
- Values are aligned on the right.
```
PresentBlox.getGridBlox().setcellAlert(2, "condition=GT, value=1000,
scope={Market:Central}, foreground=green, background=white, align=right"); 
```
For MSAS and SAP BW, the scope should be scope="{[My Cube].[Market]: [Central]}.

The following example highlights all numerical content with a cyan background:
```
<blox:cellAlert index="1" 
                condition="any" 
                background="cyan" /> 
```
This will apply a cyan background to all cells that contain numerical data. If a cell contains no data, this background color will not be applied.

A series of related cell alerts paints increasing cell amounts in different colors:

<blox:cellAlert index="1" 
                 condition="Between" value="1000" value2="3000"
                 format="00.00"
                 foreground="Orange"
                 scope="{[My Cube].[Market]:[East],[West],[South],[Central]}" /> 

<blox:cellAlert index="2" 
                 condition="Between" value="3001" value2="5000"
                 scope="{[My Cube].[Year]:[Qtr1],[Qtr2]}"
                 format="00.00"
                 foreground="Blue" />

<blox:cellAlert index="3" 
                 condition="GT"
                 value="5000"
                 format="00.00"
                 foreground="Magenta" />

<blox:cellAlert index="4" 
                condition="LT"
                value="1000"
                format="(00.00)"
                foreground="Red" />

and results in the following grid:

The output is a grid rendered in a table format with data cells displayed in different colors based on the four cell alerts rules specified. Negative values appear in parentheses with two decimal points in the color specified in rule number four. Data values that are over five thousands are displayed in two decimal points in a different color as specified in rule number 3. Values for quarter 1 and quarter 2 in the year dimension that are between three and five thousands are displayed in two decimal points in another color as specified in rule number 2. Values for East, West, South, and Central in the market dimension that are between one and three thousands are displayed in two decimal points with yet another color as specified in rule number 1.

Scope Examples

The examples in the following table assume background=red and condition=any, and show the result using different scopes.

Note: The scope attribute applies to all axes of the result set, not just the row and column axes. For example, if the grid is filtered on the profit member of the accounts dimension (that is, the accounts dimension is placed on the page filter with the profit member selected), the grid appears as shown in the first example below.

The following scope applies only to the profit member of the accounts dimension:

scope="{Accounts: Profit}"

Highlights the data for profit in the Accounts dimension for all regions.

The following scope applies to the profit and sales members of the accounts dimension:

scope="{Accounts: Profit, Sales}"

Note: This means profit OR sales. You can also specify the scope as follows:

scope="{Accounts: not(COGS)}"

Highlights the profit and sales for all regions. The only one column that is not highlighted is the COGS.

The following scope applies where the profit and sales members of the accounts dimension intersect with the east and west members of the market dimension. This is an AND operation.

scope="{Accounts: Profit, Sales}, {Market:
East, West}"

scope="{Accounts: not(COGS)}, {Market:
not(South)}"

Highlights the profit and sales for the East region in the market dimension.