Design
Conditions
How to add conditions to your templates?
COMMUNITY FEATURE
Available for:
Carbone Cloud
Carbone On-premise
Embedded Carbone JS
v3.0+
Overview
There are 3 methods to write conditions:
- Inline conditions: to print a word or a small sentence according to your data
- Conditional blocks: to hide or show a part of your document, including multiple Carbone tags, paragraph, tables
- Smart conditional blocks: simplified method to show or hide a row, table, paragraph, image
Each condition is preceded by a formatter that does the logical test (equal, greater than, ...). Here is the list of all logical operators.
Logical operators:
- ifEQ (value) : Matches values that are equal to a specified value, it replaces
ifEqual - ifNE (value) : Matches all values that are not equal to a specified value
- ifGT (value) : Matches values that are greater than a specified value.
- ifGTE (value) : Matches values that are greater than or equal to a specified value.
- ifLT (value) : Matches values that are less than a specified value.
- ifLTE (value) : Matches values that are less than or equal to a specified value.
- ifIN (value) : Matches any of the values specified in an array or string, it replaces
ifContain - ifNIN (value) : Matches none of the values specified in an array or string
- ifEM () : Matches empty values, strings, arrays or objects, it replaces
ifEmpty - ifNEM () : Matches not empty values, strings, arrays or objects
- ifTE (type) : Matches values where the type equals a specified value
- and (value) : AND operator between two consecutive conditional formatters
- or (value) : (default) OR operator between two consecutive conditional formatters
Followed by one of these formatters:
- drop (element) / keep (element) : drop or keep some elements automatically if condition is true.
- hideBegin / hideEnd : hide any part of the document between hideBegin and hideEnd if condition is true
- showBegin / showEnd : show any part of the document between showBegin and showEnd if condition is true
- show (message) : print a message if a condition is true
- elseShow (message) : print a message if a condition is false
No formatters can be chained after drop, keep, hideBegin, hideEnd, showBegin, showEnd.
Basic example
{
"val2" : 2,
"val5" : 5
}val2 = {d.val2:ifGT(3):show('high')}val2 = {d.val2:ifGT(3):show('high'):elseShow('low')}val5 = {d.val5:ifGT(3):show('high')}
val2 = 2val2 = lowval5 = highChain of conditions
If a condition is true, the result isn't passed on to the next conditional formatter (ifEQ, show, elseShow, etc.).
The value of show or elseShow is passed directly to the next non-conditional formatter (formatN, formatD, etc.)
To clearly see how this works, let's explore how to write a switch-case condition.
Multiple variables
It is possible to test multiple variables with logical operators and and or:
{
"val2" : 2,
"val5" : 5
}and = {d.val2:ifEQ(1):and(.val5):ifEQ(5):show(OK):elseShow(KO)}or = {d.val2:ifEQ(1):or(.val5):ifEQ(5):show(OK):elseShow(KO)}and = KOor = OKThe parentheses/priority between logical operators are based on the position of the formatter. Here is the internal representation of the condition for a given Carbone tag:
{d.A:ifEQ(1):and(.B):ifEQ(2):or(.C):ifEQ(3):and(.D):ifEQ(4)}
is equivalent to this:
(((A = 1) AND (B = 2)) OR (C = 3)) AND (D = 4)
:and(value)
v2.0.0+
Change the default operator between conditional formatters.
For example: {d.car:ifEQ('delorean'):and(.speed):ifGT(80):show('TravelInTime'):elseShow('StayHere')}
means "if ( (d.car equals 'delorean') AND d.speed is greater than 80 ), then it prints 'TravelInTime', otherwise
it prints 'StayHere'
| Params | Description | Type |
|---|---|---|
| value | [optional] new value to test | Mixed |
:or(value)
v2.0.0+
OR is the default operator between conditional formatters.
For example: {d.car:ifEQ('delorean'):or(.speed):ifGT(80):show('TravelInTime'):elseShow('StayHere')}
means "if ( (d.car equals 'delorean') OR d.speed is greater than 80), then it prints 'TravelInTime', otherwise
it prints 'StayHere'
| Params | Description | Type |
|---|---|---|
| value | [optional] new value to test | Mixed |
:ifEM
v2.0.0+
Matches empty values, strings, arrays or objects (null, undefined, [], {}, ...), it replaces ifEmpty.
Examples
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: null → output: "Result true"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: [] → output: "Result true"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: {} → output: "Result true"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: "" → output: "Result true"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: 0 → output: "Result false"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result false"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: [23] → output: "Result false"
{d.value:ifEM():show('Result true'):elseShow('Result false')} // input: {"id":3} → output: "Result false":ifNEM
v2.0.0+
Matches not empty values, strings, arrays or objects.
Examples
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: 0 → output: "Result true"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result true"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: [23] → output: "Result true"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: {"id":3} → output: "Result true"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: null → output: "Result false"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: [] → output: "Result false"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: {} → output: "Result false"
{d.value:ifNEM():show('Result true'):elseShow('Result false')} // input: "" → output: "Result false":ifEQ(value)
v2.0.0+
Matches all values that are equal to a specified value. It can be combined with other formatters to create conditional content. It returns the initial marker. The state of the condition is not returned.
| Params | Description | Type |
|---|---|---|
| value | value to test | String, Integer |
Examples
{d.value:ifEQ(100):show('Result true'):elseShow('Result false')} // input: 100 → output: "Result true"
{d.value:ifEQ(101):show('Result true'):elseShow('Result false')} // input: 100 → output: "Result false"
{d.value:ifEQ('homer'):show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result true"
{d.value:ifEQ('bart'):show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result false"
{d.value:ifEQ(''):show('Result true'):elseShow('Result false')} // input: "" → output: "Result true"
{d.value:ifEQ(100):show('Result true'):elseShow('Result false')} // input: null → output: "Result false"
{d.value:ifEQ(null):show('Result true'):elseShow('Result false')} // input: null → output: "Result true"
{d.value:ifEQ(100):show('Result true'):elseShow('Result false')} // input: 0 → output: "Result false":ifNE(value)
v2.0.0+
Matches all values that are not equal to a specified value. It can be combined with other formatters to create conditional content. It returns the initial marker. The state of the condition is not returned.
| Params | Description | Type |
|---|---|---|
| value | value to test | String, Integer |
Examples
{d.value:ifNE(100):show('Result true'):elseShow('Result false')} // input: 100 → output: "Result false"
{d.value:ifNE(101):show('Result true'):elseShow('Result false')} // input: 100 → output: "Result true"
{d.value:ifNE('homer'):show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result false"
{d.value:ifNE('bart'):show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result true"
{d.value:ifNE(''):show('Result true'):elseShow('Result false')} // input: "" → output: "Result false"
{d.value:ifNE(100):show('Result true'):elseShow('Result false')} // input: null → output: "Result true"
{d.value:ifNE(null):show('Result true'):elseShow('Result false')} // input: null → output: "Result false"
{d.value:ifNE(100):show('Result true'):elseShow('Result false')} // input: 0 → output: "Result true":ifGT(value)
v2.0.0+
Matches values that are greater than a specified value.
| Params | Description | Type |
|---|---|---|
| value | value to test | Integer |
Examples
{d.value:ifGT(1):show('Result true'):elseShow('Result false')} // input: 1234 → output: "Result true"
{d.value:ifGT('-29'):show('Result true'):elseShow('Result false')} // input: "50" → output: "Result true"
{d.value:ifGT('4q2'):show('Result true'):elseShow('Result false')} // input: "32q" → output: "Result true"
{d.value:ifGT('1'):show('Result true'):elseShow('Result false')} // input: "1234Hello" → output: "Result true"
{d.value:ifGT('8Hello1234'):show('Result true'):elseShow('Result false')} // input: "10" → output: "Result true"
{d.value:ifGT(19):show('Result true'):elseShow('Result false')} // input: -23 → output: "Result false"
{d.value:ifGT(768):show('Result true'):elseShow('Result false')} // input: 1 → output: "Result false"
{d.value:ifGT(0):show('Result true'):elseShow('Result false')} // input: 0 → output: "Result false"
{d.value:ifGT('33Hello'):show('Result true'):elseShow('Result false')} // input: -2891 → output: "Result false":ifGTE(value)
v2.0.0+
Matches values that are greater than or equal to a specified value.
| Params | Description | Type |
|---|---|---|
| value | value to test | Integer |
Examples
{d.value:ifGTE(-29):show('Result true'):elseShow('Result false')} // input: 50 → output: "Result true"
{d.value:ifGTE(1):show('Result true'):elseShow('Result false')} // input: 1 → output: "Result true"
{d.value:ifGTE(768):show('Result true'):elseShow('Result false')} // input: 1290 → output: "Result true"
{d.value:ifGTE('1'):show('Result true'):elseShow('Result false')} // input: "1234" → output: "Result true"
{d.value:ifGTE(19):show('Result true'):elseShow('Result false')} // input: -23 → output: "Result false"
{d.value:ifGTE(768):show('Result true'):elseShow('Result false')} // input: 1 → output: "Result false"
{d.value:ifGTE('1234'):show('Result true'):elseShow('Result false')} // input: "1" → output: "Result false":ifLT(value)
v2.0.0+
Matches values that are less than a specified value.
| Params | Description | Type |
|---|---|---|
| value | value to test | Integer |
Examples
{d.value:ifLT(19):show('Result true'):elseShow('Result false')} // input: -23 → output: "Result true"
{d.value:ifLT(768):show('Result true'):elseShow('Result false')} // input: 1 → output: "Result true"
{d.value:ifLT('1234'):show('Result true'):elseShow('Result false')} // input: "1" → output: "Result true"
{d.value:ifLT('103123'):show('Result true'):elseShow('Result false')} // input: "123dsf" → output: "Result true"
{d.value:ifLT('-2891feihuwf'):show('Result true'):elseShow('Result false')} // input: -1299283 → output: "Result true"
{d.value:ifLT(-29):show('Result true'):elseShow('Result false')} // input: 50 → output: "Result false"
{d.value:ifLT(0):show('Result true'):elseShow('Result false')} // input: 0 → output: "Result false"
{d.value:ifLT(768):show('Result true'):elseShow('Result false')} // input: 1290 → output: "Result false"
{d.value:ifLT('1'):show('Result true'):elseShow('Result false')} // input: "1234" → output: "Result false":ifLTE(value)
v2.0.0+
Matches values that are less than or equal to a specified value.
| Params | Description | Type |
|---|---|---|
| value | value to test | Integer |
Examples
{d.value:ifLTE(19):show('Result true'):elseShow('Result false')} // input: -23 → output: "Result true"
{d.value:ifLTE(768):show('Result true'):elseShow('Result false')} // input: 1 → output: "Result true"
{d.value:ifLTE(5):show('Result true'):elseShow('Result false')} // input: 5 → output: "Result true"
{d.value:ifLTE('1234'):show('Result true'):elseShow('Result false')} // input: "1" → output: "Result true"
{d.value:ifLTE(768):show('Result true'):elseShow('Result false')} // input: 1290 → output: "Result false"
{d.value:ifLTE('1'):show('Result true'):elseShow('Result false')} // input: "1234" → output: "Result false":ifIN(value)
v2.0.0+
Matches any of the values specified in an array or string, it replaces ifContain.
| Params | Description | Type |
|---|---|---|
| value | value to test | Integer |
Examples
{d.value:ifIN('is'):show('Result true'):elseShow('Result false')} // input: "car is broken" → output: "Result true"
{d.value:ifIN(2):show('Result true'):elseShow('Result false')} // input: [1,2,"toto"] → output: "Result true"
{d.value:ifIN('are'):show('Result true'):elseShow('Result false')} // input: "car is broken" → output: "Result false"
{d.value:ifIN('titi'):show('Result true'):elseShow('Result false')} // input: [1,2,"toto"] → output: "Result false":ifNIN(value)
v2.0.0+
Matches none of the values specified in an array or string.
| Params | Description | Type |
|---|---|---|
| value | value to test | Integer |
Examples
{d.value:ifNIN('are'):show('Result true'):elseShow('Result false')} // input: "car is broken" → output: "Result true"
{d.value:ifNIN('titi'):show('Result true'):elseShow('Result false')} // input: [1,2,"toto"] → output: "Result true"
{d.value:ifNIN('is'):show('Result true'):elseShow('Result false')} // input: "car is broken" → output: "Result false"
{d.value:ifNIN(2):show('Result true'):elseShow('Result false')} // input: [1,2,"toto"] → output: "Result false":ifTE(type)
NEW v4.4.0+
Tests the type of the operand's value.
| Params | Description | Type |
|---|---|---|
| type | can be "string", "number", "integer", "boolean", "binary", "object", "array" | String |
Examples
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: 0 → output: "Result false"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: [23] → output: "Result false"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: {"id":3} → output: "Result false"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: null → output: "Result false"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: [] → output: "Result false"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: {} → output: "Result false"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: "10" → output: "Result true"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: "homer" → output: "Result true"
{d.value:ifTE('string'):show('Result true'):elseShow('Result false')} // input: "" → output: "Result true"
{d.value:ifTE('boolean'):show('Result true'):elseShow('Result false')} // input: true → output: "Result true"
{d.value:ifTE('boolean'):show('Result true'):elseShow('Result false')} // input: false → output: "Result true"
{d.value:ifTE('boolean'):show('Result true'):elseShow('Result false')} // input: "0" → output: "Result false"
{d.value:ifTE('boolean'):show('Result true'):elseShow('Result false')} // input: "false" → output: "Result false"
{d.value:ifTE('binary'):show('Result true'):elseShow('Result false')} // input: "0" → output: "Result true"
{d.value:ifTE('binary'):show('Result true'):elseShow('Result false')} // input: "1" → output: "Result true"
{d.value:ifTE('binary'):show('Result true'):elseShow('Result false')} // input: false → output: "Result true"
{d.value:ifTE('binary'):show('Result true'):elseShow('Result false')} // input: "false" → output: "Result true"
{d.value:ifTE('number'):show('Result true'):elseShow('Result false')} // input: 10.5 → output: "Result true"
{d.value:ifTE('number'):show('Result true'):elseShow('Result false')} // input: "10.5" → output: "Result false"Get inspired by one of our real-life examples: Mission Report, or Sensor Readings, or Property advertisement, or Bank Statement, or Product Comparison Table, or EditorJS JSON output from HTML WYSIWYG Tool to PDF document or Vehicle Inspection Report