Using Conditional Formatting
Conditional formatting occurs when a formatting element appears only when a certain condition is met.
Note:
For information about using the Template Builder to insert conditional regions and conditional formatting, see Inserting and Editing Conditional Regions and Inserting Conditional Formatting.BI Publisher supports the usage of simple "if" statements, as well as more complex "choose" expressions.
The conditional formatting that you specify can be XSL or XSL:FO code, or you can specify actual RTF objects such as a table or data. For example, you can specify that if reported numbers reach a certain threshold, they are displayed shaded in red. Or, you can use this feature to hide table columns or rows depending on the incoming XML data.
This section covers the following topics of conditional formatting:
Using If Statements
Use an if statement to define a simple condition; for example, if a data field is a specific value.
To use an if statement:
For example, to set up the Payables Invoice Register to display invoices only when the Supplier name is "Company A", insert the syntax <?if:VENDOR_NAME='COMPANY A'?> before the Supplier field on the template.
Enter the <?end if?> tag after the invoices table.
This example is displayed in the following illustration. Note that you can insert the syntax in form fields, or directly into the template.
Using If Statements in Boilerplate Text
You can use “if” statements to change messages presented to users.
Assume that you want to incorporate an "if" statement into the following free-form text:
The program was (not) successful.
You want the "not" to display only if the value of an XML tag called <SUCCESS> equals "N".
To achieve this requirement, use the BI Publisher context command to place the if statement into the inline sequence rather than into the block (the default placement).
See Controlling the Placement of Instructions Using the Context Commands.
For example, if you construct the code as follows:
The program was <?if:SUCCESS='N'?>not<?end if?> successful.
The following undesirable result occurs:
The program was not successful.
Because BI Publisher applies the instructions to the block by default. To specify that the if statement should be inserted into the inline sequence, enter the following:
The program was <?if@inlines:SUCCESS='N'?>not<?end if?> successful.
This construction results in the following display:
The program was successful.
If SUCCESS does not equal 'N';
or
The program was not successful.
If SUCCESS equals 'N'.
Note:
If you use @inlines with if syntax, any other if syntax inside the statement must use the context command @inline.If you use @inlines with FOR-EACH syntax any other if or FOR-EACH syntax inside the statement must use the context command @inline.
Using If-Then-Else Statements
BI Publisher supports the common programming construct "if-then-else".
"if-then-else" is extremely useful when you must test a condition and conditionally show a result. For example:
IF X=0 THEN Y=2 ELSE Y=3 END IF
You can also nest these statements as follows:
IF X=0 THEN Y=2 ELSE IF X=1 THEN Y=10 ELSE Y=100 END IF
Use the following syntax to construct an if-then-else statement in the RTF template:
<?xdofx:if element_condition then result1 else result2 end if?>
For example, the following statement tests the AMOUNT element value. If the value is greater than 1000, show the word "Higher"; if it is less than 1000, show the word "Lower"; if it is equal to 1000, show "Equal":
<?xdofx:if AMOUNT > 1000 then 'Higher' else if AMOUNT < 1000 then 'Lower' else 'Equal' end if?>
Inserting Choose Statements
Use the choose, when, and otherwise elements to express multiple conditional tests. If certain conditions are met in the incoming XML data, then specific sections of the template are rendered. This is a very powerful feature of the RTF template. In regular XSL programming, if a condition is met in the choose command then further XSL code is executed. In the template, however, you can actually use visual widgets in the conditional flow (in the following example, a table).
Use the following syntax for these elements:
<?choose:?>
<?when:expression?>
<?otherwise?>
Conditional Formatting Example
This example shows a choose expression in which the display of a row of data depends on the value of the fields EXEMPT_FLAG and POSTED_FLAG. When the EXEMPT_FLAG equals "^", the row of data renders light gray. When POSTED_FLAG equals "*" the row of data renders shaded dark gray. Otherwise, the row of data renders with no shading.
In the following figure, the form field default text is displayed. The form field help text entries are shown in the following table:
| Default Text Entry in Example Form Field | Help Text Entry in Form Field |
|---|---|
|
<Grp:VAT |
<?for-each:G_VAT?> starts the G_VAT group |
|
<Choose |
<?choose:?> opens the choose statement |
|
<When EXEMPT_FLAG='^' |
<?when: EXEMPT_FLAG='^'?> tests the EXEMPT_FLAG element, if true, use the first table shown |
|
End When> |
<?end when?> ends the EXEMPT_FLAG test |
|
<When POSTED_FLAG='*' |
<?when:POSTED_FLAG='*'?> tests the POSTED_FLAG element, if true, use the table following |
|
End When> |
<?end when?> ends the POSTED_FLAG test |
|
Otherwise |
<?otherwise:?> If none of above are true then use the following table |
|
End Otherwise> |
<?end otherwise?> ends the otherwise statement |
|
End Choose> |
<?end choose?> ends the choose statement |
|
End Vat> |
<?end for-each?> ends the G_VAT group |
Formatting Columns
You can conditionally show and hide columns of data in the document output. This example demonstrates how to set up a table so that a column is only displayed based on the value of an element attribute.
This example shows a report of a price list, represented by the following XML:
<items type="PUBLIC"> <! - can be marked 'PRIVATE' - > <item> <name>Plasma TV</name> <quantity>10</quantity> <price>4000</price> </item> <item> <name>DVD Player</name> <quantity>3</quantity> <price>300</price> </item> <item> <name>VCR</name> <quantity>20</quantity> <price>200</price> </item> <item> <name>Receiver</name> <quantity>22</quantity> <price>350</price> </item> </items>
Notice the "type" attribute associated with the items element. In this XML it is marked as "PUBLIC" meaning the list is a public list rather than a PRIVATE list. For the public version of the list, the quantity column should not be shown in the output, but you want to develop only one template for both versions based on the list type.
The following figure contains a simple template that conditionally shows or hides the quantity column.
The following table shows the entries made in the template that is shown in the above figure:
| Default Text | Form Field Entry | Description |
|---|---|---|
|
grp:Item |
|
Holds the opening for-each loop for the item element. |
|
Plasma TV |
|
The placeholder for the name element from the XML file. |
|
IF |
|
The opening of the if statement to test for the attribute value PRIVATE in the column header. Note that this syntax uses an XPath expression to navigate back to the items level of the XML to test the attribute. For more information about using XPath in templates, see Using XPath Commands. |
|
Quantity |
N/A |
Boilerplate heading |
|
end-if |
|
Ends the if statement. |
|
IF |
|
The opening of the if statement to test for the attribute value PRIVATE in the column data. |
|
20 |
|
The placeholder for the quantity element. |
|
end-if |
|
Ends the if statement. |
|
1,000.00 |
|
The placeholder for the price element. |
|
end grp |
|
Closing tag of the for-each loop. |
The conditional column syntax is the "if" statement syntax with the addition of the @column clause. It is the @column clause that instructs BI Publisher to hide or show the column based on the outcome of the if statement.
If you did not include the @column the data would not display in the report as a result of the if statement, but the column still would because you had drawn it in the template.
Note:
The @column clause is an example of a context command. For more information, see Controlling the Placement of Instructions Using the Context Commands.
The example renders the output that is shown in the following figure:
If the same XML data contained the type attribute set to PRIVATE, then the output that is shown in the below figure is rendered from the same template.
Formatting Rows
BI Publisher allows you to specify formatting conditions as the row-level of a table.
Examples of row-level formatting are:
-
Highlighting a row when the data meets a certain threshold.
-
Alternating background colors of rows to ease readability of reports.
-
Showing only rows that meet a specific condition.
Conditionally Displaying a Row
To display only rows that meet a certain condition, insert the <?if:condition?> <?end if?> tags at the beginning and end of the row, within the for-each tags for the group. These tags are demonstrated in the sample template that is shown in the following figure:
The following table describes the fields from the template in the above figure:
| Default Text Entry | Form Field Help Text | Description |
|---|---|---|
|
for-each SALE |
|
Opens the for-each loop to repeat the data belonging to the SALE group. |
|
if big |
|
If statement to display the row only if the element SALES has a value greater than 5000. |
|
INDUSTRY |
|
Data field |
|
YEAR |
|
Data field |
|
MONTH |
|
Data field |
|
SALES end if |
|
Closes the if statement. |
|
end SALE |
|
Closes the SALE loop. |
Conditionally Highlighting a Row
This example demonstrates how to set a background color on every other row. The template to create this effect is shown in the following figure:
The following table shows values of the form fields from the template in the above figure:
| Default Text Entry | Form Field Help Text | Description |
|---|---|---|
|
for-each SALE |
|
Defines the opening of the for-each loop for the SALE group. |
|
format; |
|
For each alternate row, the background color attribute is set to gray for the row. |
|
INDUSTRY |
|
Data field |
|
YEAR |
|
Data field |
|
MONTH |
|
Data field |
|
SALES |
|
Data field |
|
end SALE |
|
Closes the SALE for-each loop. |
In the above table, note the format; field. It contains an if statement with a "row" context (@row). This sets the context of the if statement to apply to the current row. If the condition is true, then the <xsl:attribute> for the background color of the row is set to light gray. This setting results in the output that is shown in the following figure:
See Controlling the Placement of Instructions Using the Context Commands.
Highlighting Cells
This example demonstrates how to conditionally highlight a cell based on a value in the XML file.
This example uses the following XML code:
<accounts> <account> <number>1-100-3333</number> <debit>100</debit> <credit>300</credit> </account> <account> <number>1-101-3533</number> <debit>220</debit> <credit>30</credit> </account> <account> <number>1-130-3343</number> <debit>240</debit> <credit>1100</credit> </account> <account> <number>1-153-3033</number> <debit>3000</debit> <credit>300</credit> </account> </accounts>
The template lists the accounts and their credit and debit values. The final report will highlight in red any cell whose value is greater than 1000. The template for this is shown in the following figure:
The field definitions for the template are shown in the following table:
| Default Text Entry | Form Field Entry | Description |
|---|---|---|
|
FE:Account |
|
Opens the for each-loop for the element account. |
|
1-232-4444 |
|
The placeholder for the number element from the XML file. |
|
CH1 |
|
This field holds the code to highlight the cell red if the debit amount is greater than 1000. |
|
100.00 |
|
The placeholder for the debit element. Important The<?debit?> element must reside in its own field. |
|
CH2 |
|
This field holds the code to highlight the cell red if the credit amount is greater than 1000. |
|
100.00 |
|
The placeholder for the credit element. |
|
EFE |
|
Closes the for-each loop. |
The code to highlight the debit column as shown in the table is:
<?if:debit>1000?> <xsl:attribute xdofo:ctx="block" name="background-color">red </xsl:attribute> <?end if?>
The "if" statement is testing if the debit value is greater than 1000. If it is, then the next lines are invoked. Notice that the example embeds native XSL code inside the if statement.
The "attribute" element allows you to modify properties in the XSL.
The xdofo:ctx component is an BI Publisher feature that allows you to adjust XSL attributes at any level in the template. In this case, the background color attribute is changed to red.
To change the color attribute, you can use either the standard HTML names (for example, red, white, green) or you can use the hexadecimal color definition (for example, #FFFFF).
This template results in the output that is shown in the following figure:
