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 precede by a formatter that do the logicial test (equal, greater than, ...). Here is the list of all logical operator.

Logicial 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, string, arrays or objects, it replaces ifEmpty
ifNEM () : Matches not empty values, string, arrays or objects
ifTE (value) : 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

data

{
  "val2" : 2,
  "val5" : 5
}

template

val2 = {d.val2:ifGT(3):show('high')}val2 = {d.val2:ifGT(3):show('high'):elseShow('low')}val5 = {d.val5:ifGT(3):show('high')}

result

val2 = 2val2 = lowval5 = high

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:

data

{
  "val2" : 2,
  "val5" : 5
}

template

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)}

result

and = KOor = OK

The 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, string, arrays or objects (null, undefined, [], {}, ...), it replaces ifEmpty.

Examples

null:ifEM():show('Result true'):elseShow('Result false') // "Result true"
[]:ifEM():show('Result true'):elseShow('Result false') // "Result true"
{}:ifEM():show('Result true'):elseShow('Result false') // "Result true"
'':ifEM():show('Result true'):elseShow('Result false') // "Result true"
0:ifEM():show('Result true'):elseShow('Result false') // "Result false"
'homer':ifEM():show('Result true'):elseShow('Result false') // "Result false"
[23]:ifEM():show('Result true'):elseShow('Result false') // "Result false"
{'id':3}:ifEM():show('Result true'):elseShow('Result false') // "Result false"

:ifNEM

v2.0.0+

Matches not empty values, string, arrays or objects.

Examples

0:ifNEM():show('Result true'):elseShow('Result false') // "Result true"
'homer':ifNEM():show('Result true'):elseShow('Result false') // "Result true"
[23]:ifNEM():show('Result true'):elseShow('Result false') // "Result true"
{'id':3}:ifNEM():show('Result true'):elseShow('Result false') // "Result true"
null:ifNEM():show('Result true'):elseShow('Result false') // "Result false"
[]:ifNEM():show('Result true'):elseShow('Result false') // "Result false"
{}:ifNEM():show('Result true'):elseShow('Result false') // "Result false"
'':ifNEM():show('Result true'):elseShow('Result false') // "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

100:ifEQ(100):show('Result true'):elseShow('Result false') // "Result true"
100:ifEQ(101):show('Result true'):elseShow('Result false') // "Result false"
'homer':ifEQ('homer'):show('Result true'):elseShow('Result false') // "Result true"
'homer':ifEQ('bart'):show('Result true'):elseShow('Result false') // "Result false"
'':ifEQ(''):show('Result true'):elseShow('Result false') // "Result true"
null:ifEQ(100):show('Result true'):elseShow('Result false') // "Result false"
null:ifEQ(null):show('Result true'):elseShow('Result false') // "Result true"
0:ifEQ(100):show('Result true'):elseShow('Result false') // "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

100:ifNE(100):show('Result true'):elseShow('Result false') // "Result false"
100:ifNE(101):show('Result true'):elseShow('Result false') // "Result true"
'homer':ifNE('homer'):show('Result true'):elseShow('Result false') // "Result false"
'homer':ifNE('bart'):show('Result true'):elseShow('Result false') // "Result true"
'':ifNE(''):show('Result true'):elseShow('Result false') // "Result false"
null:ifNE(100):show('Result true'):elseShow('Result false') // "Result true"
null:ifNE(null):show('Result true'):elseShow('Result false') // "Result false"
0:ifNE(100):show('Result true'):elseShow('Result false') // "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

1234:ifGT(1):show('Result true'):elseShow('Result false') // "Result true"
'50':ifGT('-29'):show('Result true'):elseShow('Result false') // "Result true"
'32q':ifGT('4q2'):show('Result true'):elseShow('Result false') // "Result true"
'1234Hello':ifGT('1'):show('Result true'):elseShow('Result false') // "Result true"
'10':ifGT('8Hello1234'):show('Result true'):elseShow('Result false') // "Result true"
-23:ifGT(19):show('Result true'):elseShow('Result false') // "Result false"
1:ifGT(768):show('Result true'):elseShow('Result false') // "Result false"
0:ifGT(0):show('Result true'):elseShow('Result false') // "Result false"
-2891:ifGT('33Hello'):show('Result true'):elseShow('Result false') // "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

50:ifGTE(-29):show('Result true'):elseShow('Result false') // "Result true"
1:ifGTE(1):show('Result true'):elseShow('Result false') // "Result true"
1290:ifGTE(768):show('Result true'):elseShow('Result false') // "Result true"
'1234':ifGTE('1'):show('Result true'):elseShow('Result false') // "Result true"
-23:ifGTE(19):show('Result true'):elseShow('Result false') // "Result false"
1:ifGTE(768):show('Result true'):elseShow('Result false') // "Result false"
'1':ifGTE('1234'):show('Result true'):elseShow('Result false') // "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

-23:ifLT(19):show('Result true'):elseShow('Result false') // "Result true"
1:ifLT(768):show('Result true'):elseShow('Result false') // "Result true"
'1':ifLT('1234'):show('Result true'):elseShow('Result false') // "Result true"
'123dsf':ifLT('103123'):show('Result true'):elseShow('Result false') // "Result true"
-1299283:ifLT('-2891feihuwf'):show('Result true'):elseShow('Result false') // "Result true"
50:ifLT(-29):show('Result true'):elseShow('Result false') // "Result false"
0:ifLT(0):show('Result true'):elseShow('Result false') // "Result false"
1290:ifLT(768):show('Result true'):elseShow('Result false') // "Result false"
'1234':ifLT('1'):show('Result true'):elseShow('Result false') // "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

-23:ifLTE(19):show('Result true'):elseShow('Result false') // "Result true"
1:ifLTE(768):show('Result true'):elseShow('Result false') // "Result true"
5:ifLTE(5):show('Result true'):elseShow('Result false') // "Result true"
'1':ifLTE('1234'):show('Result true'):elseShow('Result false') // "Result true"
1290:ifLTE(768):show('Result true'):elseShow('Result false') // "Result false"
'1234':ifLTE('1'):show('Result true'):elseShow('Result false') // "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

'car is broken':ifIN('is'):show('Result true'):elseShow('Result false') // "Result true"
[1,2,'toto']:ifIN(2):show('Result true'):elseShow('Result false') // "Result true"
'car is broken':ifIN('are'):show('Result true'):elseShow('Result false') // "Result false"
[1,2,'toto']:ifIN('titi'):show('Result true'):elseShow('Result false') // "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

'car is broken':ifNIN('are'):show('Result true'):elseShow('Result false') // "Result true"
[1,2,'toto']:ifNIN('titi'):show('Result true'):elseShow('Result false') // "Result true"
'car is broken':ifNIN('is'):show('Result true'):elseShow('Result false') // "Result false"
[1,2,'toto']:ifNIN(2):show('Result true'):elseShow('Result false') // "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

0:ifTE('string'):show('Result true'):elseShow('Result false') // "Result false"
[23]:ifTE('string'):show('Result true'):elseShow('Result false') // "Result false"
{'id':3}:ifTE('string'):show('Result true'):elseShow('Result false') // "Result false"
null:ifTE('string'):show('Result true'):elseShow('Result false') // "Result false"
[]:ifTE('string'):show('Result true'):elseShow('Result false') // "Result false"
{}:ifTE('string'):show('Result true'):elseShow('Result false') // "Result false"
'10':ifTE('string'):show('Result true'):elseShow('Result false') // "Result true"
'homer':ifTE('string'):show('Result true'):elseShow('Result false') // "Result true"
'':ifTE('string'):show('Result true'):elseShow('Result false') // "Result true"
true:ifTE('boolean'):show('Result true'):elseShow('Result false') // "Result true"
false:ifTE('boolean'):show('Result true'):elseShow('Result false') // "Result true"
'0':ifTE('boolean'):show('Result true'):elseShow('Result false') // "Result false"
'false':ifTE('boolean'):show('Result true'):elseShow('Result false') // "Result false"
'0':ifTE('binary'):show('Result true'):elseShow('Result false') // "Result true"
'1':ifTE('binary'):show('Result true'):elseShow('Result false') // "Result true"
false:ifTE('binary'):show('Result true'):elseShow('Result false') // "Result true"
'false':ifTE('binary'):show('Result true'):elseShow('Result false') // "Result true"
10.5:ifTE('number'):show('Result true'):elseShow('Result false') // "Result true"
'10.5':ifTE('number'):show('Result true'):elseShow('Result false') // "Result false"