Design
Text Formatting
List of functions to manipulate and transform your JSON strings
COMMUNITY FEATURE
Available for:
Carbone Cloud
Carbone On-premise
Embedded Carbone JS
v2.0+
:lowerCase
v0.12.5+
Lower case all letters
Examples
{d.value:lowerCase()} // input: "My Car" → output: "my car"
{d.value:lowerCase()} // input: "my car" → output: "my car"
{d.value:lowerCase()} // input: null → output: null
{d.value:lowerCase()} // input: 1203 → output: 1203:upperCase
v0.12.5+
Upper case all letters
Examples
{d.value:upperCase()} // input: "My Car" → output: "MY CAR"
{d.value:upperCase()} // input: "my car" → output: "MY CAR"
{d.value:upperCase()} // input: null → output: null
{d.value:upperCase()} // input: 1203 → output: 1203:ucFirst
v0.12.5+
Upper case first letter
Examples
{d.value:ucFirst()} // input: "My Car" → output: "My Car"
{d.value:ucFirst()} // input: "my car" → output: "My car"
{d.value:ucFirst()} // input: null → output: null
{d.value:ucFirst()} // input: undefined → output: undefined
{d.value:ucFirst()} // input: 1203 → output: 1203:ucWords
v0.12.5+
Upper case the first letter of all words
Examples
{d.value:ucWords()} // input: "my car" → output: "My Car"
{d.value:ucWords()} // input: "My cAR" → output: "My CAR"
{d.value:ucWords()} // input: null → output: null
{d.value:ucWords()} // input: undefined → output: undefined
{d.value:ucWords()} // input: 1203 → output: 1203:print(message)
v0.13.0+
Always return the same message if called (sort of "catch all" formatter)
| Params | Description | Type |
|---|---|---|
| message | text to print | String |
Examples
{d.value:print('hello!')} // input: "My Car" → output: "hello!"
{d.value:print('hello!')} // input: "my car" → output: "hello!"
{d.value:print('hello!')} // input: null → output: "hello!"
{d.value:print('hello!')} // input: 1203 → output: "hello!":printJSON
v4.23.0+
Stringify the object/array
Examples
{d.value:printJSON()} // input: [{"id":2,"name":"homer"},{"id":3,"name":"bart"}] → output: "[\n {\"id\": 2, \"name\": \"homer\"},\n {\"id\": 3, \"name\": \"bart\"}\n]"
{d.value:printJSON()} // input: "my car" → output: "\"my car\"":unaccent
v1.1.0+
Removes accents from text
Examples
{d.value:unaccent()} // input: "crème brulée" → output: "creme brulee"
{d.value:unaccent()} // input: "CRÈME BRULÉE" → output: "CREME BRULEE"
{d.value:unaccent()} // input: "être" → output: "etre"
{d.value:unaccent()} // input: "éùïêèà" → output: "euieea":convCRLF
v4.1.0+
It renders carriage return \r\n and line feed \n into documents instead of printing them as a string.
Importante notes:
- Feature supported for DOCX, PPTX, ODT, ODP, and ODS files.
- ODS supports is experimental for now, contact the support if you find issues.
- Since
v3.5.3, using the:convCRLFformatter before:htmlconverts\nto<br>tags. Usage example:{d.content:convCRLF:html}
Examples
// With API options: {
// "extension": "odt"
// }
{d.value:convCRLF()} // input: "my blue \n car" → output: "my blue <text:line-break/> car"
{d.value:convCRLF()} // input: "my blue \r\n car" → output: "my blue <text:line-break/> car"
// With API options: {
// "extension": "docx"
// }
{d.value:convCRLF()} // input: "my blue \n car" → output: "my blue </w:t><w:br/><w:t xml:space=\"preserve\"> car"
{d.value:convCRLF()} // input: "my blue \r\n car" → output: "my blue </w:t><w:br/><w:t xml:space=\"preserve\"> car":substr(begin, end, wordMode)
NEW v4.18.0+
Slice a string with a begin and an end.
| Params | Description | Type |
|---|---|---|
| begin | Zero-based Index at which to begin extraction. | Integer |
| end | [optional] Zero-based index before which to end extraction | Integer |
| wordMode | [optional] If true, it never cuts words. In such a case:- end must be greater than begin and negative values cannot be used. end - begin = maximum number of characters per line of text- A word can only be truncated only if it does not fit in the line. In this case, the word always starts at the beginning of a new line, just like in Word or LibreOffice - The same line width (end - begin) must be used between successive calls of substr to print all the words of the text (no gaps). Ex:{d.text(0 , 50 , true)} -> line 1 of 50 characters{d.text(50 , 100, true)} -> line 2 of 50 characters{d.text(100, 150, true)} -> line 3 of 50 characters{d.text(150, 200, last)} -> line 4 of infinite characters- last can be used instead of true to print the rest of the text, even if it is longer than the defined line width |
Mixed |
Examples
{d.value:substr(0, 3)} // input: "foobar" → output: "foo"
{d.value:substr(1)} // input: "foobar" → output: "oobar"
{d.value:substr(-2)} // input: "foobar" → output: "ar"
{d.value:substr(2, -1)} // input: "foobar" → output: "oba"
{d.value:substr(0, 11, true)} // input: "abcd efg hijklm" → output: "abcd efg "
{d.value:substr(1, 11, true)} // input: "abcd efg hijklm" → output: "abcd efg ":split(delimiter)
NEW v4.12.0+
Split a string using a delimiter
It can be used with arrayJoin('', 1, 2) to select one specific item of the generated array
| Params | Description | Type |
|---|---|---|
| delimiter | The delimiter | String |
Examples
{d.value:split('c')} // input: "abcdefc12" → output: ["ab","def","12"]
{d.value:split('.')} // input: 1222.1 → output: ["1222","1"]
{d.value:split('/')} // input: "ab/cd/ef" → output: ["ab","cd","ef"]:padl(targetLength, padString)
NEW v3.0.0+
Pad the string from the start with another string
| Params | Description | Type |
|---|---|---|
| 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 |
Examples
{d.value:padl(10)} // input: "abc" → output: " abc"
{d.value:padl(10, 'foo')} // input: "abc" → output: "foofoofabc"
{d.value:padl(6, '123465')} // input: "abc" → output: "123abc"
{d.value:padl(8, '0')} // input: "abc" → output: "00000abc"
{d.value:padl(1)} // input: "abc" → output: "abc":padr(targetLength, padString)
NEW v3.0.0+
Pad the string from the end with another string
| Params | Description | Type |
|---|---|---|
| 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 |
Examples
{d.value:padr(10)} // input: "abc" → output: "abc "
{d.value:padr(10, 'foo')} // input: "abc" → output: "abcfoofoof"
{d.value:padr(6, '123465')} // input: "abc" → output: "abc123"
{d.value:padr(8, '0')} // input: "abc" → output: "abc00000"
{d.value:padr(1)} // input: "abc" → output: "abc":ellipsis(maximum)
NEW v4.12.0+
Add "..." if the text is too long
| Params | Description | Type |
|---|---|---|
| maximum | number of characters to print. | Integer |
Examples
{d.value:ellipsis(3)} // input: "abcdef" → output: "abc..."
{d.value:ellipsis(6)} // input: "abcdef" → output: "abcdef"
{d.value:ellipsis(10)} // input: "abcdef" → output: "abcdef":prepend(textToPrepend)
NEW v4.12.0+
add a prefix to a text
| Params | Description | Type |
|---|---|---|
| textToPrepend | text to prepend | string |
Examples
{d.value:prepend('123')} // input: "abcdef" → output: "123abcdef":append(textToAppend)
NEW v4.12.0+
Add a suffix to a text
| Params | Description | Type |
|---|---|---|
| textToAppend | text to append | string |
Examples
{d.value:append('123')} // input: "abcdef" → output: "abcdef123":replace(oldText, newText)
NEW v4.12.0+
Replace a text based on a pattern
All matches of the pattern (first argument: oldText) is replaced by the replacement string (second argument: newText).
The pattern can only be a string.
| Params | Description | Type |
|---|---|---|
| oldText | old text to replace | string |
| newText | new text | string |
Examples
{d.value:replace('cd', 'OK')} // input: "abcdef abcde" → output: "abOKef abOKe"
{d.value:replace('cd')} // input: "abcdef abcde" → output: "abef abe"
{d.value:replace('cd', null)} // input: "abcdef abcde" → output: "abef abe"
{d.value:replace('cd', 1000)} // input: "abcdef abcde" → output: "ab1000ef ab1000e":len
v2.0.0+
Returns the length of a string or array.
Examples
{d.value:len()} // input: "Hello World" → output: 11
{d.value:len()} // input: "" → output: 0
{d.value:len()} // input: [1,2,3,4,5] → output: 5
{d.value:len()} // input: [1,"Hello"] → output: 2:t
v4.23.2+
Translate the text using the translation dictionnary
:preserveCharRef
v4.23.8+
Preserve character reference
By default, Carbone removes all forbidden characters before injecting data into XML (e.g., &, >, <, �, ...).
As a result, an injected character reference such as § ( = § ) would be transformed into &#xa7; in XML.
This formatter prevents that transformation, preserving the character reference.
This function is useful for specific XML generation scenarios where the direct character cannot be used (e.g., non-UTF-8 charset),
and the character reference must be retained.
It accepts numeric (e.g., d) and hexadecimal formats (e.g., 򡃯), in either lower or upper case.
:formatR
Format a country/region code to a human readable region name
Examples
// With API options: {
// "lang": "en-us"
// }
{d.value:formatR()} // input: "US" → output: "United States of America"
{d.value:formatR()} // input: "DE" → output: "Germany"
{d.value:formatR()} // input: "FRA" → output: "France"
{d.value:formatR()} // input: "250" → output: "France"
{d.value:formatR()} // input: "276" → output: "Germany"
// With API options: {
// "lang": "fr-fr"
// }
{d.value:formatR()} // input: "US" → output: "États-Unis d'Amérique"
{d.value:formatR()} // input: "DE" → output: "Allemagne"
{d.value:formatR()} // input: "FRA" → output: "France"
{d.value:formatR()} // input: "250" → output: "France"
{d.value:formatR()} // input: "276" → output: "Allemagne"Get inspired by one of our real-life examples: Summary, Mission Report, Grid Layout or Planning with subtotals