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

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:

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 &#xa7; ( = § ) would be transformed into &amp;#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., &#100;) and hexadecimal formats (e.g., &#xa10ef;), in either lower or upper case.