16.3.0 Switch, Case and EndSwitch Tag Reference
Switch, Case and EndSwitch Tags are used when you wish to test for multiple different conditions, and manipulate your output depending on which condition is met.
In theory the same thing can be done with If, ElseIf and EndIf Tags, but testing multiple conditions using those Tags can quickly become complicated and error prone. Switch, Case and EndSwitch Tags are a simpler alternative to use in this situation.
Switch Tags are used to begin a list of Case Tags, and EndSwitch Tags are used to end that list. Each Switch Tag must have a corresponding EndSwitch Tag.
Each Case Tag evaluates a different condition, and the Tags, text, etc., after the first condition that is met, and before the next Case Tag, are executed or displayed. If the last Case Tag's condition is met, then the Tags, text, etc., before the EndSwitch Tag are executed or displayed. If multiple Case Tag conditions are met, only the first Case Tag is executed (with the exception of the defaultCase property below).
In the rest of this article we'll cover the properties of these Tags:
Changes to Switch/Case Tags in Version 16.3.0
Switch/Case tags in version 16.3.0 have an added "var" property. The property has no value by default. The property can be set for use with the "Anchor" property: How Do I Use the Tag Anchor Property in 16.2?
Switch Tag Properties
Here we see the properties of a Switch Tag. Below, each property is described in detail. Unless otherwise noted, each property is required.
You can use these links to jump ahead to a Switch Tag properties section:
Tag Properties
nickname (optional)
The nickname will appear in the template rather than the generic "[switch:]" label. Square brackets ("[]") will surround any text you enter here when it appears in the template to identify it as a Tag. Descriptive nicknames can be very important in designing complex templates.
var (default: none)
This property allows a user to set a variable name for the Switch Tag. This variable name can be used to set the anchor property on a chart/bitmap.
Standard Properties
description (optional)
A brief description of this Tag.
enabled (default: on)
Controls whether a Tag is executed when generating output. This can be useful when debugging a template.
- on - this Tag will be executed when output is generated
- off - this Tag will not be executed when output is generated
- engine-only - this Tag will be executed only if output is generated using one of the Report Engines
- autotag-only - this Tag will be executed only if output is generated using the Report Designer
Advanced Properties
error-handling (optional)
Selects which types of errors produce warnings rather than exceptions, which allows output to be generated despite the error.
- Ignore type error - these errors occur when a Tag's defined data type is different than the data type of the data returned by the Tag's query
- Ignore formatting error - these errors occur when a Tag's specified format is not compatible with the format of the data returned by the Tag's query
- Ignore select error - these errors occur when a Tag's query fails to find valid data
- Node must exist - these errors occur when a row or node is queried which doesn't exist in the data source. These errors typically return an empty value that is output without warning.
- Node must not return NULL - these errors occur when a query returns an empty or NULL value. These errors typically return an empty value that is output without warning.
- Treat warning as error - forces all of the above error-handling warnings to appear as errors (not exceptions). This is useful when used with Report Designer's Verify feature.
Case Tag Properties
Here we see the properties of a Case Tag. Below, each property is described in detail. Unless otherwise noted, each property is required.
You can use these links to jump ahead to a Case Tag properties section:
Tag Properties
defaultCase (default: false)
- false - this Case Tag behaves as already documented.
- true - if no Case Tags before this Case Tag evaluated to true, this Case Tag will be executed, regardless of whether this Case Tag evaluates to true or not. This is useful to add a default action that will be executed if no other condition within the Switch/EndSwitch Tag is met.
nickname (optional)
The nickname will appear in the template rather than the generic "[case:]" label. Square brackets ("[]") will surround any text you enter here when it appears in the template to identify it as a Tag. Descriptive nicknames can be very important in designing complex templates.
notEmpty (default: false)
This property controls what happens if the Case Tag's SQL select statement returns NULL, or if its XML or JsonPath select statement returns an empty string:
- false - the Case Tag will evaluate to true because the node exists and you are not requiring it be non-empty
- true - the Case Tag will evaluate to false because the node must not be empty to evaluate to true
var (default: none)
This property allows a user to set a variable name for the Case Tag. This variable name can be used to set the anchor property on a chart/bitmap.
Standard Properties
description (optional)
A brief description of this Tag.
enabled (default: on)
Controls whether a Tag is executed when generating output. This can be useful when debugging a template.
- on - this Tag will be executed when output is generated
- off - this Tag will not be executed when output is generated
- engine-only - this Tag will be executed only if output is generated using one of the Report Engines
- autotag-only - this Tag will be executed only if output is generated using the Report Designer
Advanced Properties
error-handling (optional)
Selects which types of errors produce warnings rather than exceptions, which allows output to be generated despite the error.
- Ignore type error - these errors occur when a Tag's defined data type is different than the data type of the data returned by the Tag's query
- Ignore formatting error - these errors occur when a Tag's specified format is not compatible with the format of the data returned by the Tag's query
- Ignore select error - these errors occur when a Tag's query fails to find valid data
- Node must exist - these errors occur when a row or node is queried which doesn't exist in the data source. These errors typically return an empty value that is output without warning.
- Node must not return NULL - these errors occur when a query returns an empty or NULL value. These errors typically return an empty value that is output without warning.
- Treat warning as error - forces all of the above error-handling warnings to appear as errors (not exceptions). This is useful when used with Report Designer's Verify feature.
EndSwitch Tag Properties
Here we see the properties of an EndSwitch Tag. Below, each property is described in detail. Unless otherwise noted, each property is required.
You can use these links to jump ahead to an EndSwitch Tag properties section:
Tag Properties
nickname (optional)
The nickname will appear in the template rather than the generic "[:switch]" label. Square brackets ("[]") will surround any text you enter here when it appears in the template to identify it as a Tag. Descriptive nicknames can be very important in designing complex templates.
Standard Properties
description (optional)
A brief description of this Tag.
enabled (default: on)
Controls whether a Tag is executed when generating output. This can be useful when debugging a template.
- on - this Tag will be executed when output is generated
- off - this Tag will not be executed when output is generated
- engine-only - this Tag will be executed only if output is generated using one of the Report Engines
- autotag-only - this Tag will be executed only if output is generated using the Report Designer