Design
Text Formatting
List of function 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
'My Car':lowerCase() // "my car"
'my car':lowerCase() // "my car"
null:lowerCase() // null
1203:lowerCase() // 1203
:upperCase
v0.12.5+
Upper case all letters
Examples
'My Car':upperCase() // "MY CAR"
'my car':upperCase() // "MY CAR"
null:upperCase() // null
1203:upperCase() // 1203
:ucFirst
v0.12.5+
Upper case first letter
Examples
'My Car':ucFirst() // "My Car"
'my car':ucFirst() // "My car"
null:ucFirst() // null
undefined:ucFirst() // undefined
1203:ucFirst() // 1203
:ucWords
v0.12.5+
Upper case the first letter of all words
Examples
'my car':ucWords() // "My Car"
'My cAR':ucWords() // "My CAR"
null:ucWords() // null
undefined:ucWords() // undefined
1203:ucWords() // 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
'My Car':print('hello!') // "hello!"
'my car':print('hello!') // "hello!"
null:print('hello!') // "hello!"
1203:print('hello!') // "hello!"
:printJSON
v4.23.0+
Stringify the object/array
Examples
[{'id':2,'name':'homer'},{'id':3,'name':'bart'}]:printJSON() // "[\n {\"id\": 2, \"name\": \"homer\"},\n {\"id\": 3, \"name\": \"bart\"}\n]"
'my car':printJSON() // "\"my car\""
:unaccent
v1.1.0+
Removes accents from text
Examples
'crème brulée':unaccent() // "creme brulee"
'CRÈME BRULÉE':unaccent() // "CREME BRULEE"
'être':unaccent() // "etre"
'éùïêèà':unaccent() // "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:convCRLF
formatter before:html
converts\n
to<br>
tags. Usage example:{d.content:convCRLF:html}
Examples
// With API options: {
// "extension": "odt"
// }
'my blue \n car':convCRLF() // "my blue <text:line-break/> car"
'my blue \r\n car':convCRLF() // "my blue <text:line-break/> car"
// With API options: {
// "extension": "docx"
// }
'my blue \n car':convCRLF() // "my blue </w:t><w:br/><w:t> car"
'my blue \r\n car':convCRLF() // "my blue </w:t><w:br/><w:t> 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
'foobar':substr(0, 3) // "foo"
'foobar':substr(1) // "oobar"
'foobar':substr(-2) // "ar"
'foobar':substr(2, -1) // "oba"
'abcd efg hijklm':substr(0, 11, true) // "abcd efg "
'abcd efg hijklm':substr(1, 11, true) // "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
'abcdefc12':split('c') // ["ab","def","12"]
1222.1:split('.') // ["1222","1"]
'ab/cd/ef':split('/') // ["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
'abc':padl(10) // " abc"
'abc':padl(10, 'foo') // "foofoofabc"
'abc':padl(6, '123465') // "123abc"
'abc':padl(8, '0') // "00000abc"
'abc':padl(1) // "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
'abc':padr(10) // "abc "
'abc':padr(10, 'foo') // "abcfoofoof"
'abc':padr(6, '123465') // "abc123"
'abc':padr(8, '0') // "abc00000"
'abc':padr(1) // "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
'abcdef':ellipsis(3) // "abc..."
'abcdef':ellipsis(6) // "abcdef"
'abcdef':ellipsis(10) // "abcdef"
:prepend(textToPrepend)
NEW v4.12.0+
add a prefix to a text
Params | Description | Type |
---|---|---|
textToPrepend | text to prepend | string |
Examples
'abcdef':prepend('123') // "123abcdef"
:append(textToAppend)
NEW v4.12.0+
Add a suffix to a text
Params | Description | Type |
---|---|---|
textToAppend | text to append | string |
Examples
'abcdef':append('123') // "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
'abcdef abcde':replace('cd', 'OK') // "abOKef abOKe"
'abcdef abcde':replace('cd') // "abef abe"
'abcdef abcde':replace('cd', null) // "abef abe"
'abcdef abcde':replace('cd', 1000) // "ab1000ef ab1000e"
:len
v2.0.0+
Returns the length of a string or array.
Examples
'Hello World':len() // 11
'':len() // 0
[1,2,3,4,5]:len() // 5
[1,'Hello']:len() // 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.