Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Formatters can be chained with dynamic parameters to create complex operations, check out the example in Dynamic parameters.
converts from one currency to another
exchange rates are included by default
you can provide a new exchange rate for one report in options.currencyRates
of Carbone.render
or globally with Carbone.set
convCurr()
without parameters converts automatically from options.currencySource
to options.currencyTarget
rounds a number
same as toFixed()
but it rounds number correctly round(1.05, 1) = 1.1
formats number according to the locale
applying a number of decimals depends on the report type:
for ODS
/XLSX
, the number of decimals has to be formatted based on the text editor
for the other type of files, the number of decimals depends on the precision
parameter passed to the formatter
Adds 2 numbers.
Subtracts 2 numbers.
Multiplies 2 numbers.
Divides 2 numbers.
Converts a number to an INT.
Converts a number with English specifications (decimal separator is a dot .
).
Converts a number into string, keeping only decimals.
Converts a number with French specifications (decimal separator is a comma ,
).
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
target
[optional] convert to this currency ('EUR')
by default it equals options.currencyTarget
string
source
[optional] currency of source data ('USD')
by default it equals options.currencySource
string
precision
number of decimal
number
precision
[optional] number of decimals
number
precisionOrFormat
[optional] number of decimal, or specific format
integer : change default precision of the currency
M : print major currency name without the number
L : prints number with currency symbol (by default)
LL : prints number with major currency name
number
All existing formatters by input data type
Formatters translate raw data into human readable text.
To apply a formatter to data, use the separator :
. Multiple formatters can be used one after another. Each formatter input is the output of the previous one. Some formatters accept static or Dynamic parameters.
The example below shows how to write "John"
instead of "JOHN"
using 2 chained formatters, and how to translate a raw ISO date into a human readable date.
My name is {d.name:lowerCase:ucFirst}.
I was born on {d.birthday:convDate(YYYY-MM-DD, LL)}.
My name is John.
I was born on Monday 31th 2000.
Flattens an array of a string or a number.
counts and prints a row number of any array
usage example: d[i].id:count()
prints a counter of the current row no matter the value of id
internally replaced by :cumCount
Lower case all letters.
Upper case all letters.
Upper case first letter.
Upper case the first letter of all words.
"catch all formatter"
always returns the same message if called
converts user-defined enums to human readable values
user-defined enums must be passed in options
of carbone.render
Removes accents from text.
Renders carriage return \r
and line feed into documents instead of printing them as a string.
supported file formats: DOCX
, PDF
, ODT
, ODS
ODS
support is experimental
use the :convCRLF
formatter before :html
to convert to <br>
tags
example: {d.content:convCRLF:html}
Slices a string with a begin and an end.
Pads the string from the start with another string.
Pads the string from the end with another string.
Returns the length of a string or array.
Formatters accept dynamic variables if parameters start with a .
and are not surrounded by quotation marks.
The following dataset is used in the examples below.
To do mathematical operations:
To insert parent attributes, 2 dots ..
have to be used. To access to grandparents attributes, 3 dots ...
are necessary, etc.:
To read parent objects and their children attributes (no limit in depth):
It returns an error if the attribute does not exist:
It returns an error:
It returns an error if the sub-array is not indexed:
No formatters can be chained after hideBegin
, hideEnd
, showBegin
, showEnd
.
Hide and show a part of the document with the following formatters:
hideBegin
/ hideEnd
: hide text block between hideBegin
and hideEnd
if condition is true.
showBegin
/ showEnd
: show a text block between showBegin and showEnd if condition is true.
ifEQ (value)
: Matches values that are equal to a specified value.
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.
ifNIN (value)
: Matches none of the values specified in an array or string
ifEM ()
: Matches empty values, string, arrays or objects.
ifNEM ()
: Matches not empty values, string, arrays or objects.
and (value)
: AND
operator between two consecutive conditional formatters.
or (value)
: (default) OR
operator between 2 consecutive conditional formatters.
show (message)
: print a message if a condition is true.
elseShow (message)
: print a message if a condition is false.
Data
one = { d.status1:ifEQ(2):show(two):or(.status1):ifEQ(1):show(one):elseShow(unknown) }
two = { d.status2:ifEQ(2):show(two):or(.status2):ifEQ(1):show(one):elseShow(unknown) }
three = { d.status3:ifEQ(2):show(two):or(.status3):ifEQ(1):show(one):elseShow(unknown) }
one = "one"
two = "two"
three = "unknown"
Supported file formats: DOCX
, ODT
, and PDF
.
when you use the drop
formatter, the tag value is not printed and chained formatters are not executed
use the drop
formatter to delete elements from a document. The first argument passed to :drop(argument1)
is the element to drop
p
to drop paragraphs
usage: {d.text:ifEM:drop(p)}
row
to drop table rows
usage: {d.data:ifEM:drop(row)}
Optionally, use nbrRowsToHide
to set the number of rows to drop as a second argument {d.data:ifEM:drop(row, nbrRowsToHide)}
, such as {d.data:ifEM:drop(row, 3)}
, meaning the current and next two rows is removed if the condition is validated.
By default, the formatter :drop(row)
hides only the current row.
img
to drop pictures
usage: {d.img:ifEM:drop(img)}
chart
to drop charts
usage: {d.dataset:ifEM:drop(chart)}
shape
to drop shape (square, circle, arrows, etc.)
usage: {d.dataset:ifEM:drop(chart)}
Shows a text block between showBegin
and showEnd
if a condition is true.
Use only break lines (shift
+ Enter
) between showBegin
and showEnd
.
Data
Banana{d.toBuy:ifEQ(true):showBegin} Apple Pineapple {d.toBuy:showEnd}grapes
Banana Apple Pineapple grapes
Hides a text block between hideBegin
and hideEnd
if a condition is true.
Data
Banana{d.toBuy:ifEQ(true):hideBegin} Apple Pineapple {d.toBuy:hideEnd}grapes
Banana grapes
Changes the default operator between conditional formatters.
{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'
Changes the default operator between conditional formatters.
{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'
Matches empty values, string, arrays or objects (null, undefined, [], {}, ...).
Matches not empty values, string, arrays or objects.
matches all values that are equal to a specified value
can be combined with other formatters to create conditional content
returns the initial marker
the state of the condition is not returned
matches all values that are not equal to a specified value
can be combined with other formatters to create conditional content
returns the initial marker
the state of the condition is not returned
Matches values that are greater than a specified value.
Matches values that are greater than or equal to a specified value.
Matches values that are less than a specified value.
Matches values that are less than or equal to a specified value.
Matches any of the values specified in an array or string.
Matches none of the values specified in an array or string.
prints a message if the condition is true
use with other formatters to print conditional content
print a message if the condition is false
use with other formatters to print conditional content
To get the current date in UTC, use the marker {c.now}
in your template. The current date in UTC is returned only if the complement object option.complement
is not overwritten by custom data.
formats dates
takes an output date pattern as an argument
change the timezone
through the option options.timezone
and the lang
through options.lang
Formats intervals/duration.
human+
human
millisecond(s)
or ms
second(s)
or s
minute(s)
or m
hour(s)
or h
year(s)
or y
month(s)
or M
week(s)
or w
day(s)
or d
adds a time to a date
available units: day, week, month, quarter, year, hour, minute, second and millisecond
units are case insensitive, and support plural and short forms
subtracts a time to a date
available units: day, week, month, quarter, year, hour, minute, second and millisecond
units are case insensitive, and support plural and short forms
Creates a date and set it to the start of a unit of time.
Creates a date and set it to the end of a unit of time.
Because preferred formatting differs based on language, there are a few tokens that can be used to format a date based on report language.
There are upper and lower case variations on the same formats. The lowercase version is intended to be the shortened version of its uppercase counterpart.
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
Parameters | Description | Type |
---|---|---|
By default, condition formatters have a special behavior, the formatter's result is not propagated to the next formatter if the result of the condition is true. This enables test chaining with .
to drop a group of elements, use or
include the tag within a paragraph, and all the elements it comprises are also removed if the condition is validated ()
include the tag in a table row, and all the elements it comprises are also deleted if the condition is validated ()
include the tag within the image title, description, or alternative text ()
include the tag within the alternative text of the graphic ()
include the tag within the title, description or alternative text of the shape ()
Learn more about why .
Use only break lines (shift
+ Enter
) between hideBegin
and hideEnd
. Learn more about why .
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
date patterns are available in
(Wikipedia)
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
params | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Parameters | Description | Type |
---|
Format | Output | Description |
---|
Format | English locale | Sample output |
---|
separator
[optional] item separator (,
by default)
string
objSeparator
[optional] object separator
,
by default
string
attributeSeparator
[optional] attribute separator
:
by default
string
attributes
[optional] list of object's attributes to print
string
start
number to start with (default: 1)
string
message
text to print
string
type
enum name passed in options
of carbone.render(data, options)
string
begin
Zero-based index at which to begin extraction.
integer
end
Zero-based index before which to end extraction
integer
targetLength
The length of the resulting string once the string has been padded. If the value is less than string length, then string is returned as-is.
number
padString
The string to pad the current str with. If padString is too long to stay within the targetLength, it will be truncated from the end. The default value is " "
string
targetLength
The length of the resulting string once the string has been padded. If the value is less than string length, then string is returned as-is.
number
padString
The string to pad the current str with. If padString is too long to stay within the targetLength, it will be truncated from the end. The default value is " "
string
value | [optional] new value to test | mixed |
value | [optional] new value to test | mixed |
value | value to test | string, integer |
value | value to test | string, integer |
value | value to test | integer |
value | value to test | integer |
value | value to test | integer |
value | value to test | integer |
value | value to test | integer |
value | value to test | integer |
message | message to print |
message | message to print |
patternOut | output format | string |
patternIn |
| string |
patternOut | output format: human, human+, milliseconds, seconds,... | string |
patternIn | [optional] input unit: milliseconds, seconds,... | string |
amount | the amount | number |
unit | the unit | string |
patternIn |
| string |
amount | the amount | number |
unit | the unit | string |
patternIn |
| string |
unit | the unit | string |
patternIn |
| string |
unit | the unit | string |
patternIn |
| string |
patternIn | input format | string |
patternOut | output format | string |
| 1360013296 | Unix Timestamp |
| 1360013296123 | Unix Millisecond Timestamp |
| 18 | Two-digit year |
| 2018 | Four-digit year |
| 1-12 | The month, beginning at 1 |
| 01-12 | The month, 2-digits |
| Jan-Dec | The abbreviated month name |
| January-December | The full month name |
| 1-31 | The day of the month |
| 01-31 | The day of the month, 2-digits |
| 0-6 | The day of the week, with Sunday as 0 |
| Su-Sa | The min name of the day of the week |
| Sun-Sat | The short name of the day of the week |
| Sunday-Saturday | The name of the day of the week |
| 0-23 | The hour |
| 00-23 | The hour, 2-digits |
| 1-12 | The hour, 12-hour clock |
| 01-12 | The hour, 12-hour clock, 2-digits |
| 0-59 | The minute |
| 00-59 | The minute, 2-digits |
| 0-59 | The second |
| 00-59 | The second, 2-digits |
| 000-999 | The millisecond, 3-digits |
| +05:00 | The offset from UTC, ±HH:mm |
| +0500 | The offset from UTC, ±HHmm |
| AM PM |
| am pm |
| h:mm A | 8:02 PM |
| h:mm:ss A | 8:02:18 PM |
| MM/DD/YYYY | 08/16/2018 |
| MMMM D, YYYY | August 16, 2018 |
| MMMM D, YYYY h:mm A | August 16, 2018 8:02 PM |
| dddd, MMMM D, YYYY h:mm A | Thursday, August 16, 2018 8:02 PM |
| M/D/YYYY | 8/16/2018 |
| MMM D, YYYY | Aug 16, 2018 |
| MMM D, YYYY h:mm A | Aug 16, 2018 8:02 PM |
| ddd, MMM D, YYYY h:mm A | Thu, Aug 16, 2018 8:02 PM |