Conditionals
You might want your output text to say different things depending on the values in your data. For example, you might want to say one thing when total sales exceed your sales target and something else when they don't.
Studio allows you to add conditionals to cover these scenarios. There are two types:
Studio includes a Conditional Builder, a special dialog for building conditionals of either type. To open this, click the small fork-like icon on the menu bar in the script editor toolbar.
Important
You can also create conditionals by writing ATL directly into the script editor. This must be done in ATL View and requires knowledge of ATL and conditional syntax. See ATL Guide > Syntax for conditionals for guidance.
Simple conditionals
A conditional typically has one or more cases and a default. Each case has one or more conditions and a result. A simple conditional has only one condition per case.
A conditional returns the result for the first case it finds to be true. CASE 1 and CASE 2 may both be true, but the conditional returns the result for CASE 1 only. If no cases are true, the default result is returned.
If no cases are true and no default result is specified, the result is an empty string.
Example 1 — Simple conditional
Assume a "Describe Each Row" project with this data:
Code | Branch | Sales | SalesTarget | Profit | ProfitTarget | |
|---|---|---|---|---|---|---|
Row 1 | 1001 | New York | 302,234.11 | 300,000 | 20,939.24 | 22,000 |
Row 2 | 1002 | Baltimore | 297,659.38 | 300,000 | 18,618.73 | 22,000 |
Row 3 | 1003 | Philadelphia | 175,000.00 | 175,000 | 12,259.59 | 12,000 |
With this data, you might wish to output one sentence when the Sales value exceeds the SalesTarget value, and a different sentence when it does not. You can achieve this by writing a simple conditional.
Here's how that condition might look in the Conditional Builder:
The conditional has two cases:
CASE 1 compares two variables. It asks whether the Sales value is greater than the SalesTarget value. If true, the result is a short sentence stating that the branch performed well.
CASE 2 compares the same variables. It asks whether the Sales value is less than SalesTarget value. If true, the result is a short sentence stating that the branch performed poorly.
If neither CASE 1 nor CASE 2 are true, Sales and SalesTarget must be equal. You can account for this scenario by including a default result — e.g. a sentence stating that the branch performed adequately.
Tip
This is a common way to use a conditional — i.e. to output different text in response to variations in the data. However, you can specify any ATL expression in the RESULT field. You can also embed further conditionals within results.
In a simple conditional, a case typically compares two items, specified in PARAMETER A and PARAMETER B. In the example shown, these items are variables (Sales and SalesTarget), but they can be any ATL expression. You can also include function calls in the parameter fields.
To determine the comparison type, click in the CONDITION field and select an option.
Tip
Most of the comparison options only make sense when applied to numeric values. A common error is to use a numeric comparison (e.g. Is Greater Than) when one of the variables being compared is not a numeric value.
Three options — i.e. Is Empty, Is Not Empty, and Is Number — apply to only one parameter; select one of these and the PARAMETER B field disappears. These options correspond to the ATL functions isEmpty, isNotEmpty, and isNumber.
In Marked Up View, a conditional is underlined in purple:
In ATL View, the same conditional appears this way:
The output text from this conditional would describe New York performing well (Row 1), Baltimore performing poorly (Row 2), and Philadelphia performing adequately (Row 3).
Complex conditionals
Sometimes you need to insert a conditional in which the conditions being tested are more complex — that is, you might need to include a case that tests multiple conditions, not just one.
The Conditional Builder supports the creation of more complex conditionals, but this requires you to toggle the Use complex conditions switch at the top of the builder dialog:
This changes the dialog so that the first element becomes a field into which you can type an arbitrarily complex condition in raw ATL. To include multiple conditions for a single case, you must combine individual conditions by using one of these logical operators:
Logical Operator | Syntax |
|---|---|
AND |
|
OR |
|
Use AND when all conditions must be true. Use OR when any of the conditions must be true. You can use brackets when combining conditions to make it clear how they combine. For example, consider the following:
Sales > SalesTarget && Profit > ProfitTarget || Profit > 1000000
The intended purpose is unclear unless you group conditions using brackets. For example:
Sales > SalesTarget && (Profit > ProfitTarget || Profit > 1000000)(Sales > SalesTarget && Profit > ProfitTarget) || Profit > 1000000
Tip
See ATL Guide > Syntax for conditionals for more about operators in conditionals.
Example 2 — Complex conditional using AND and OR
Assume a "Describe Each Row" project with this data:
Code | Branch | Sales | SalesTarget | Profit | ProfitTarget | |
|---|---|---|---|---|---|---|
Row 1 | 1001 | New York | 302,234.11 | 300,000 | 20,939.24 | 22,000 |
Row 2 | 1002 | Baltimore | 297,659.38 | 300,000 | 18,618.73 | 22,000 |
Row 3 | 1003 | Philadelphia | 175,000.00 | 175,000 | 12,259.59 | 12,000 |
Let's build a conditional that will capture the following:
A branch has performed "well" if it meets (equals or exceeds) its sales target and its profit target.
A branch has performed "adequately" if it meets (equals or exceeds) its sales target or its profit target.
A branch has performed "poorly" if it fails to meet either its sales target or profit target.
The conditional would look like this in the builder:
Note that the builder no longer has PARAMETER A and PARAMETER B fields, and the CONDITION field no longer has a dropdown menu. The condition must be typed in the CONDITION field.
Tip
The examples above use comparison operators, but you might instead use any ATL function that returns a Boolean true or false (e.g. contains).
Note that CASE 1 uses the AND operator (&&). This ensures that the result for CASE 1 is returned only when both conditions in its CONDITION field are true. Similarly, CASE 2 uses the OR operator (||) This ensures that the result for CASE 2 is returned when either of the conditions in its CONDITION field is true. A default result for when neither CASE 1 nor CASE 2 is true is also included.
In Marked Up View, the conditional is underlined in purple:
The ATL for the conditional is:
[[if(Sales >= SalesTarget && Profit >= ProfitTarget){[[Branch]] performed well.}elseif(Sales >= SalesTarget || Profit >= ProfitTarget){[[Branch]] performed adequately.}else{[[Branch ]] performed poorly.}]]Note
Note how in ATL the conditional is expressed case by case and includes the default, like this:
[[if(condition){result}elseif(condition){result}else{default result}]]
The output text from this conditional would describe New York performing adequately (Row 1), Baltimore performing poorly (Row 2), and Philadelphia performing well (Row 3).
