Use 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 Insert and Edit Conditional Regions and Insert Conditional Formatting.

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're 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:

Use 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:

  1. Insert the following syntax to designate the beginning of the conditional area.

    <?if:condition?>

  2. Insert the following syntax at the end of the conditional area: <?end if?>.

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.

Use 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 Publisher context command to place the if statement into the inline sequence rather than into the block (the default placement).

See Control 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 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 doesn't 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.

Use If-Then-Else Statements

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's less than 1000, show the word "Lower"; if it's equal to 1000, show "Equal":

<?xdofx:if AMOUNT > 1000 then 'Higher'
  else
  if AMOUNT < 1000 then 'Lower'
   else
   'Equal'
end if?>

Insert 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

Format 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's 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 shouldn't 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

<?for-each:item?>

Holds the opening for-each loop for the item element.

Plasma TV

<?name?>

The placeholder for the name element from the XML file.

IF

<?if@column:/items/@type="PRIVATE"?>

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 Use XPath Commands.

Quantity

N/A

Boilerplate heading

end-if

<?end if?>

Ends the if statement.

IF

<?if@cell:/items/@type="PRIVATE"?>

The opening of the if statement to test for the attribute value PRIVATE in the column data.

20

<?quantity?>

The placeholder for the quantity element.

end-if

<?end if?>

Ends the if statement.

1,000.00

<?price?>

The placeholder for the price element.

end grp

<?end for-each?>

Closing tag of the for-each loop.

The conditional column syntax is the "if" statement syntax with the addition of the @column clause. It's the @column clause that instructs 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 Control 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.

Format Rows

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

<?for-each:SALE?>

Opens the for-each loop to repeat the data belonging to the SALE group.

if big

<?if:SALES>5000?>

If statement to display the row only if the element SALES has a value greater than 5000.

INDUSTRY

<?INDUSTRY?>

Data field

YEAR

<?YEAR?>

Data field

MONTH

<?MONTH?>

Data field

SALES end if

<?end if?>

Closes the if statement.

end SALE

<?end for-each?>

Closes the SALE loop.

Conditionally Highlight 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

<?for-each:SALE?>

Defines the opening of the for-each loop for the SALE group.

format;

<?if@row:position() mod 2=0?> <xsl:attribute name="background-color" xdofo:ctx="incontext">lightgray</xsl:attribute><?end if?>

For each alternate row, the background color attribute is set to gray for the row.

INDUSTRY

<?INDUSTRY?>

Data field

YEAR

<?YEAR?>

Data field

MONTH

<?MONTH?>

Data field

SALES

<?SALES?>

Data field

end SALE

<?end for-each?>

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 Control the Placement of Instructions Using the Context Commands.

Highlight 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

<?for-each:account?>

Opens the for each-loop for the element account.

1-232-4444

<?number?>

The placeholder for the number element from the XML file.

CH1

<?if:debit>1000?><xsl:attribute xdofo:ctx="block" name="background-color">red</xsl:attribute><?end if?>

This field holds the code to highlight the cell red if the debit amount is greater than 1000.

100.00

<?debit?>

The placeholder for the debit element.

Important:

The <?debit?> element must reside in its own field.

CH2

<?if:credit>1000?><xsl:attribute xdofo:ctx="block" name="background-color">red</xsl:attribute><?end if?>

This field holds the code to highlight the cell red if the credit amount is greater than 1000.

100.00

<?credit?>

The placeholder for the credit element.

EFE

<?end for-each?>

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 tests whether the debit value is greater than 1000, and if so 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 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: