docs/docs/en/template-print/syntax/formatters/text-formatting.md
This section provides various formatters for text data. The following subsections introduce each formatter's syntax, examples, and results.
Converts all letters to lower case.
'My Car':lowerCase() // Outputs "my car"
'my car':lowerCase() // Outputs "my car"
null:lowerCase() // Outputs null
1203:lowerCase() // Outputs 1203
Each example outputs as indicated in the comments.
Converts all letters to upper case.
'My Car':upperCase() // Outputs "MY CAR"
'my car':upperCase() // Outputs "MY CAR"
null:upperCase() // Outputs null
1203:upperCase() // Outputs 1203
Each example outputs as indicated in the comments.
Capitalizes only the first letter of the string while leaving the rest unchanged.
'My Car':ucFirst() // Outputs "My Car"
'my car':ucFirst() // Outputs "My car"
null:ucFirst() // Outputs null
undefined:ucFirst() // Outputs undefined
1203:ucFirst() // Outputs 1203
The output is as described in the comments.
Capitalizes the first letter of each word in the string.
'my car':ucWords() // Outputs "My Car"
'My cAR':ucWords() // Outputs "My CAR"
null:ucWords() // Outputs null
undefined:ucWords() // Outputs undefined
1203:ucWords() // Outputs 1203
The output is as shown in the examples.
Always returns the specified message regardless of the original data, making it useful as a fallback formatter.
Parameter:
'My Car':print('hello!') // Outputs "hello!"
'my car':print('hello!') // Outputs "hello!"
null:print('hello!') // Outputs "hello!"
1203:print('hello!') // Outputs "hello!"
Returns the specified string "hello!" in all cases.
Converts an object or array into a JSON-formatted string.
[{'id':2,'name':'homer'},{'id':3,'name':'bart'}]:printJSON()
// Outputs "[
{"id": 2, "name": "homer"},
{"id": 3, "name": "bart"}
]"
'my car':printJSON() // Outputs ""my car""
The output is the JSON-formatted string of the given data.
Removes diacritical marks from text, converting it to an unaccented format.
'crème brulée':unaccent() // Outputs "creme brulee"
'CRÈME BRULÉE':unaccent() // Outputs "CREME BRULEE"
'être':unaccent() // Outputs "etre"
'éùïêèà ':unaccent() // Outputs "euieea"
All examples output the text with accents removed.
Converts carriage return and newline characters (\r\n or \n) into document-specific line break tags. This is useful for formats such as DOCX, PPTX, ODT, ODP, and ODS.
Note: When using :html before :convCRLF, \r\n is converted to a tag.
// For ODT format:
'my blue
car':convCRLF() // Outputs "my blue <text:line-break/> car"
'my blue
car':convCRLF() // Outputs "my blue <text:line-break/> car"
// For DOCX format:
'my blue
car':convCRLF() // Outputs "my blue </w:t><w:br/><w:t> car"
'my blue
car':convCRLF() // Outputs "my blue </w:t><w:br/><w:t> car"
The output shows the line break markers appropriate for the target document format.
Performs substring operations on a string, starting at index begin (0-based) and ending just before index end.
An optional parameter wordMode (boolean or last) controls whether to avoid breaking a word in the middle.
'foobar':substr(0, 3) // Outputs "foo"
'foobar':substr(1) // Outputs "oobar"
'foobar':substr(-2) // Outputs "ar"
'foobar':substr(2, -1) // Outputs "oba"
'abcd efg hijklm':substr(0, 11, true) // Outputs "abcd efg "
'abcd efg hijklm':substr(1, 11, true) // Outputs "abcd efg "
The output is the substring extracted according to the parameters.
Splits a string into an array using the specified delimiter.
Parameter:
'abcdefc12':split('c') // Outputs ["ab", "def", "12"]
1222.1:split('.') // Outputs ["1222", "1"]
'ab/cd/ef':split('/') // Outputs ["ab", "cd", "ef"]
The example results in an array split by the given delimiter.
Pads the left side of a string with a specified character until the final string reaches targetLength.
If the target length is less than the original string length, the original string is returned.
Parameters:
'abc':padl(10) // Outputs " abc"
'abc':padl(10, 'foo') // Outputs "foofoofabc"
'abc':padl(6, '123465') // Outputs "123abc"
'abc':padl(8, '0') // Outputs "00000abc"
'abc':padl(1) // Outputs "abc"
Each example outputs the string padded on the left accordingly.
Pads the right side of a string with a specified character until the final string reaches targetLength.
Parameters are the same as for :padl.
'abc':padr(10) // Outputs "abc "
'abc':padr(10, 'foo') // Outputs "abcfoofoof"
'abc':padr(6, '123465') // Outputs "abc123"
'abc':padr(8, '0') // Outputs "abc00000"
'abc':padr(1) // Outputs "abc"
The output shows the string padded on the right.
If the text exceeds the specified number of characters, appends an ellipsis ("...") at the end.
Parameter:
'abcdef':ellipsis(3) // Outputs "abc..."
'abcdef':ellipsis(6) // Outputs "abcdef"
'abcdef':ellipsis(10) // Outputs "abcdef"
The examples show text truncated and appended with an ellipsis if needed.
Prepends the specified text to the beginning of the string.
Parameter:
'abcdef':prepend('123') // Outputs "123abcdef"
The output shows the text with the specified prefix added.
Appends the specified text to the end of the string.
Parameter:
'abcdef':append('123') // Outputs "abcdef123"
The output shows the text with the specified suffix added.
Replaces all occurrences of oldText in the text with newText.
Parameters:
newText is null, it indicates that the matching text should be removed.'abcdef abcde':replace('cd', 'OK') // Outputs "abOKef abOKe"
'abcdef abcde':replace('cd') // Outputs "abef abe"
'abcdef abcde':replace('cd', null) // Outputs "abef abe"
'abcdef abcde':replace('cd', 1000) // Outputs "ab1000ef ab1000e"
The output is the text after replacing the specified segments.
Returns the length of a string or an array.
'Hello World':len() // Outputs 11
'':len() // Outputs 0
[1,2,3,4,5]:len() // Outputs 5
[1,'Hello']:len() // Outputs 2
Outputs the corresponding length as a number.
Translates the text using a translation dictionary.
Examples and results depend on the actual translation dictionary configuration.
By default, certain illegal characters from XML (such as &, >, <, etc.) are removed. This formatter preserves character references (for example, § remains unchanged) and is suitable for specific XML generation scenarios.
Examples and results depend on the specific use case.