Built-ins for strings
Page Contents
- substring
- cap_first
- uncap_first
- capitalize
- chop_linebreak
- date, time, datetime
- ends_with
- html
- groups
- index_of
- j_string
- js_string
- json_string
- last_index_of
- length
- lower_case
- left_pad
- right_pad
- contains
- matches
- number
- replace
- rtf
- url
- split
- starts_with
- string (when used with a string value)
- trim
- upper_case
- word_list
- xhtml
- xml
- Common flags
substring
Note
This built-in exists since FreeMarker 2.3.7.
Synopsis: exp?substring(from, toExclusive), also callable as exp?substring(from)
A substring of the string. from is the index of the first character. It must be a number that is at least 0 and less than or equal with toExclusive, or else an error will abort the template processing. The toExclusive is the index of the character position after the last character of the substring, or with other words, it is one greater than the index of the last character. It must be a number that is at least 0 and less than or equal to the length of the string, or else an error will abort the template processing. If the toExclusive is omitted, then it defaults to the length of the string. If a parameter is a number that is not an integer, only the integer part of the number will be used.
Example:
|
|||
The output:
|
|||
cap_first
The string with the very first word of the string capitalized. For the precise meaning of ``word'' see the word_list built-in. Example:
|
|||
The output:
|
|||
In the case of "- green mouse", the first word is the -.
uncap_first
The opposite of cap_first. The string with the very first word of the string un-capitalized.
capitalize
The string with all words capitalized. For the precise meaning of ``word'' see the word_list built-in. Example:
|
|||
The output:
|
|||
chop_linebreak
The string without the line-break at its very end if there was a line-break, otherwise the unchanged string.
date, time, datetime
The string converted to a date value. It is recommended to specify a parameter that specifies the format. For example:
|
|||
will print something like (depends on the output locale (language) and on other settings):
|
|||
Note that the dates was converted back to string according to the date_format, time_format and datetime_format settings (for more information about converting dates to strings read: string built-in for dates, date interpolations). It does not mater what format did you use when you have converted the strings to dates.
You don't have to use the format parameter, if you know what the default date/time/datetime format will be when the template is processed:
|
|||
If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.
ends_with
Returns if this string ends with the specified substring. For example "redhead"?ends_with("head") returns boolean true. Also, "head"?ends_with("head") will return true.
html
The string as HTML markup. That is, the string with all:
- < replaced with <
- > replaced with >
- & replaced with &
- " replaced with "
Note that if you want to insert an attribute value securely, you must quote the attribute value in the HTML template with quotation mark (with ", not with '):
|
|||
Note that in HTML pages usually you want to use this built-in for all interpolations. So you can spare a lot of typing and lessen the chances of accidental mistakes by using the escape directive.
groups
This is used only with the result of the matches built-in. See there...
index_of
Returns the index within this string of the first occurrence of the specified substring. For example, "abcabc"?index_of("bc") will return 1 (don't forget that the index of the first character is 0). Also, you can specify the index to start the search from: "abcabc"?index_of("bc", 2) will return 4. There is no restriction on the numerical value of the second parameter: if it is negative, it has the same effect as if it were zero, and if it is greater than the length of this string, it has the same effect as if it were equal to the length of this string. Decimal values will be truncated to integers.
If the 1st parameter does not occur as a substring in this string (starting from the given index, if you use the second parameter), then it returns -1.
j_string
Escapes the string with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.
All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in the Java language (like \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).
Example:
|
|||
will output:
|
|||
js_string
Escapes the string with the escaping rules of JavaScript language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.
Both quotation mark (") and apostrophe-quoate (') are escaped. Starting from FreeMarker 2.3.1, it also escapes > as \> (to avoid </script>).
All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in JavaScript (like \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).
Example:
|
|||
will output:
|
|||
json_string
Escapes the string with the escaping rules of JSON language string literals, so it's safe to insert the value into a string literal. Note that it will not add quotation marks around the inserted value; you meant to use this inside the string literal.
This will not escape ' characters, since JSON strings must be quoted with ". It will, however escape the / (slash) characters as \/ where they occur directly after a <, to avoid </script> and such. It will also escape the > characters as \u003E where they occur directly after ]], to avoid exiting an XML CDATA section.
All characters under UCS code point 0x20 will be escaped. When they have no dedicated escape sequence in JSON (like \n, \t, etc.), they will be replaced with a UNICODE escape (\uXXXX).
last_index_of
Returns the index within this string of the last (rightmost) occurrence of the specified substring. It returns the index of the first (leftmost) character of the substring. For example: "abcabc"?last_index_of("ab") will return 3. Also, you can specify the index to start the search from. For example, "abcabc"?last_index_of("ab", 2) will return 0. Note that the second parameter indicates the maximum index of the start of the substring. There is no restriction on the numerical value of the second parameter: if it is negative, it has the same effect as if it were zero, and if it is greater than the length of this string, it has the same effect as if it were equal to the length of this string. Decimal values will be truncated to inegers.
If the 1st parameter does not occur as a substring in this string (before the given index, if you use the second parameter), then it returns -1.
length
The number of characters in the string.
lower_case
The lower case version of the string. For example "GrEeN MoUsE"?lower_case will be "green mouse".
left_pad
Note
This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.
If it's used with 1 parameter, then it inserts spaces on the beginning of the string until it reaches the length that is specified as the parameter. If the string is already as long or longer than the specified length, then it does nothing. For example, this:
|
|||
will output this:
|
|||
If it's used with 2 parameters, then the 1st parameter means the same as if you were using the built-in with only 1 parameter, and the second parameter specifies what to insert instead of space characters. For example:
|
|||
will output this:
|
|||
The 2nd parameter can be a string whose length is greater than 1. Then the string will be inserted periodically, for example:
|
|||
will output this:
|
|||
The 2nd parameter must be a string value, and it must be at least 1 character long.
right_pad
Note
This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.
This is the same as left_pad, but it inserts the characters at the end of the string instead of the beginning of the string.
Example:
|
|||
This will output this:
|
|||
contains
Note
This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.
Returns if the substring specified as the parameter to this built-in occurrs in the string. For example:
|
|||
This will output:
|
|||
matches
This is a ``power user'' built-in. Ignore it if you don't know regular expressions.
Note
This built-in will work only if you use Java2 platform 1.4 or later. Otherwise it will stop template processing with error.
This built-in determines if the string exactly matches the pattern. Also, it returns the list of matching sub-strings. The return value is a multi-type value:
-
Boolean: true, if it the string exactly matches the pattern, otherwise false. For example, "fooo"?matches('fo*') is true, but "fooo bar"?matches('fo*') is false.
-
Sequence: the list of matched substrings of the string. Possibly a 0 length sequence.
For example:
|
|||
will print:
|
|||
If the regular expression contains groups (parentheses), then you can access them with the groups built-in:
|
|||
This will print:
|
|||
matches accepts an optional 2nd parameter, the flags. Note that it does not support flag f, and ignores the r flag.
number
The string converted to numerical value. The number must be in the same format as you specify numerical values directly in FTL. That is, it must be in the locale independent form, where the decimal separator is dot. In additional the built-in recognizes scientific notation (e.g. "1.23E6", "1.5e-8").
If the string is not in the appropriate format, an error will abort template processing when you try to access this built-in.
Known problem: If you use earlier Java2 platform than v1.3, the built-ins will not recognize + prefix and scientific notation.
replace
It is used to replace all occurrences of a string in the original string with another string. It does not deal with word boundaries. For example:
|
|||
will print:
|
|||
The replacing occurs in left-to-right order. This means that this:
|
|||
will print:
|
|||
If the 1st parameter is an empty string, then all occurrences of the empty string will be replaced, like "foo"?replace("","|") will evaluate to "|f|o|o|".
replace accepts an optional flags parameter, as its 3rd parameter.
rtf
The string as Rich text (RTF text). That is, the string with all:
-
\ replaced with \\
-
{ replaced with \{
-
} replaced with \}
url
Note
This built-in is available since FreeMarker 2.3.1. It doesn't exist in 2.3.
The string after URL escaping. This means that all non-US-ASCII and reserved URL characters will be escaped with %XX. For example:
|
|||
The output will be (assuming that the charset used for the escaping is an US-ASCII compatible charset):
|
|||
Note that it escapes all reserved URL characters (/, =, &, ...etc), so this encoding can be used for encoding query parameter values, for example:
|
|||
Note
Above no HTML encoding (?htm) was needed, because URL escaping escapes all reserved HTML characters anyway. But watch: always quote the attribute value, and always with normal quotation mark ("), never with apostrophe quotation mark ('), because apostrophe quotation mark is not escaped by the URL escaping.
To do URL escaping a charset must be chosen that will be used for calculating the escaped parts (%XX). If you are HTML page author and you don't really understand this, don't worry: the programmers should configure FreeMarker so that it uses the proper charset by default (programmers: see more below...). If you are a more technical minded user, then you may want to know that the charset used is specified by the url_escaping_charset setting, that can be set in template execution time (or, preferably, earlier by the programmers). For example:
|
|||
Furthermore, you can explicitly specify a charset for a single URL escaping as the parameter to the built-in:
|
|||
If the url built-in has no parameter, then it will use the charset specified as the value of the url_escaping_charset setting. This setting should be set by the software that encloses FreeMarker (e.g. a Web application framework), because it is not set (null) by default. If it is not set, then FreeMarker falls back using the value of the output_encoding setting, which is also not set by default, so it is again the task of the enclosing software. If the output_encoding setting is not set either, then the parameterless url built-in can't be executed, and it will cause execution time error. Of course, the url built-in with parameter always works.
It's possible to set url_escaping_charset in the template with the setting directive, but it is bad practice, at least in true MVC applications. The output_encoding setting can't be set with the setting directive, so that's surely the task of the enclosing software. You may find more information regarding this here...
split
It is used to split a string into a sequence of strings along the occurrences of another string. For example:
|
|||
will print:
|
|||
Note that it is assumed that all occurrences of the separator is before a new item, thus:
|
|||
will print:
|
|||
split accepts an optional flags parameter, as its 2nd parameter.
starts_with
Returns if this string starts with the specified substring. For example "redhead"?starts_with("red") returns boolean true. Also, "red"?starts_with("red") will return true.
string (when used with a string value)
Does nothing, just returns the string as-is. The exception is that if the value is a multi-type value (e.g. it is both string and sequence at the same time), then the resulting value will be only a simple string, not a multi-type value. This can be utilized to prevent the artifacts of multi-typing.
trim
The string without leading and trailing white-space. Example:
|
|||
The output:
|
|||
upper_case
The upper case version of the string. For example "GrEeN MoUsE" will be "GREEN MOUSE".
word_list
A sequence that contains all words of the string in the order as they appear in the string. Words are continual character sequences that contain any character but white-space. Example:
|
|||
will output:
|
|||
xhtml
The string as XHTML text. That is, the string with all:
- < replaced with <
- > replaced with >
- & replaced with &
- " replaced with "
- ' replaced with '
The only difference between this built-in and the xml built-in is that the xhtml built-in escapes ' as ' instead of as ', because some older browsers don't interpret ' correctly.
xml
The string as XML text. That is, the string with all:
- < replaced with <
- > replaced with >
- & replaced with &
- " replaced with "
- ' replaced with '
Common flags
Many string built-ins accept an optional string parameter, the so called ``flags''. In this string, each letter influences a certain aspect of the behavior of the built-in. For example, letter i means that the built-in should not differentiate the lower and upper-case variation of the same letter. The order of the letters in the flags string is not significant.
This is the complete list of letters (flags):
-
i: Case insensitive: do not differentiate the lower and upper-case variation of the same letter.
-
f: First only. That is, replace/find/etc. only the first occurrence of something.
-
r: The substring to find is a regular expression. FreeMarker uses the variation of regular expressions described at http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html. This flag will work only if you use Java2 platform 1.4 or later. Otherwise it will cause template processing to stop with error.
-
m: Multi-line mode for regular expressions. In multi-line mode the expressions ^ and $ match just after or just before, respectively, a line terminator or the end of the string. By default these expressions only match at the beginning and the end of the entire string. Note that ^ and $ doesn't match the line-break character itself.
-
s: Enables dot-all mode for regular expressions (same as Perl singe-line mode). In dot-all mode, the expression . matches any character, including a line terminator. By default this expression does not match line terminators.
-
c: Permits whitespace and comments in regular expressions.
Example:
|
|||
This outputs this:
|
|||
This is the table of built-ins that use these common flags, and which supports which flags:
replace | Yes | Yes | Only with r | Only with r | Only with r | Yes |
split | Yes | Yes | Only with r | Only with r | Only with r | No |
match | Yes | Ignored | Yes | Yes | Yes | No |
相关推荐
赠送jar包:freemarker-2.3.31.jar; 赠送原API文档:freemarker-2.3.31-javadoc.jar; 赠送源代码:freemarker-2.3.31-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.31.pom; 包含翻译后的API文档:...
赠送jar包:freemarker-2.3.30.jar; 赠送原API文档:freemarker-2.3.30-javadoc.jar; 赠送源代码:freemarker-2.3.30-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.30.pom; 包含翻译后的API文档:...
赠送jar包:freemarker-2.3.30.jar; 赠送原API文档:freemarker-2.3.30-javadoc.jar; 赠送源代码:freemarker-2.3.30-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.30.pom; 包含翻译后的API文档:...
FreeMarkerIDE-1.0.0.GA.zip是一款专为FreeMarker设计的Eclipse插件,旨在提升开发人员构建和管理FreeMarker应用的效率。FreeMarker是一个强大的模板引擎,广泛应用于Java环境中,用于生成动态HTML或其他格式的文本...
camel-freemarker-1.6.4.jar, camel-freemarker-2.8.1.jar, com.springsource.freemarker-2.3.15.jar, com.springsource.freemarker-sources-2.3.15.jar, freemarker-1.4.1.jar, freemarker-2-3-18.jar, freemarker-...
JavaEE源代码 freemarker-2.3.8JavaEE源代码 freemarker-2.3.8JavaEE源代码 freemarker-2.3.8JavaEE源代码 freemarker-2.3.8JavaEE源代码 freemarker-2.3.8JavaEE源代码 freemarker-2.3.8JavaEE源代码 freemarker-...
赠送jar包:freemarker-2.3.23.jar; 赠送原API文档:freemarker-2.3.23-javadoc.jar; 赠送源代码:freemarker-2.3.23-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.23.pom; 包含翻译后的API文档:...
`freemarker-ide-0.9.14` 是一个针对Freemarker模板语言的集成开发环境插件,旨在提升在MyEclipse中的开发效率和体验。 这个插件版本为0.9.14,可能包含了对Freemarker语法的高亮显示、代码自动完成、错误检查、...
在这个"freemarker-2.3.22"的压缩包中,包含了Freemarker 2.3.22版本的相关资源,有助于我们深入了解和使用这个库。 首先,`README.txt`通常包含项目的基本信息、安装指南和快速入门等内容。在这个版本中,它可能...
赠送jar包:freemarker-2.3.20.jar; 赠送原API文档:freemarker-2.3.20-javadoc.jar; 赠送源代码:freemarker-2.3.20-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.20.pom; 包含翻译后的API文档:...
本压缩包"freemarker-ide-0.9.14.rar"提供的是一个针对IDE的Freemarker插件,特别适用于MyEclipse 6.5版本。 该插件名为"Hudson Freemarker IDE",版本为0.9.14,它增强了MyEclipse对Freemarker模板语言的支持。在...
这个"apache-freemarker-2.3.26-incubating-bin.tar.gz"文件是Apache FreeMarker的一个特定版本,即2.3.26,处于孵化器阶段(incubating)。它包含了FreeMarker库的二进制文件和相关的文档,为开发者提供了完整的...
赠送jar包:freemarker-2.3.20.jar; 赠送原API文档:freemarker-2.3.20-javadoc.jar; 赠送源代码:freemarker-2.3.20-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.20.pom; 包含翻译后的API文档:...
赠送jar包:freemarker-2.3.23.jar; 赠送原API文档:freemarker-2.3.23-javadoc.jar; 赠送源代码:freemarker-2.3.23-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.23.pom; 包含翻译后的API文档:...
在本Demo中,我们将深入探讨如何将FreeMarker模板引擎整合进SSM框架,以及PageHelper分页插件的使用。 首先,让我们来了解一下SSM框架的核心组件: 1. **Spring**:这是一个全面的Java应用框架,提供依赖注入(DI...
赠送jar包:freemarker-2.3.31.jar; 赠送原API文档:freemarker-2.3.31-javadoc.jar; 赠送源代码:freemarker-2.3.31-sources.jar; 赠送Maven依赖信息文件:freemarker-2.3.31.pom; 包含翻译后的API文档:...
这个“freemarker-2.3.23-中文手册.zip”包含了Freemarker 2.3.23版本的详尽中文文档,对于学习和掌握Freemarker的使用非常有帮助。 在Freemarker 2.3.23版中,我们首先会接触到它的核心概念,包括模板(Template)...
【标题】"FreeMarkerDemo-java.rar" 是一个与Spring Boot相关的示例项目,它演示了如何将Word文档(docx格式)转换为FreeMarker(ftl)模板。这个压缩包包含了一个Java应用,该应用利用Spring Boot的强大功能,以及...
这个"freemarker-2.3.28.jar"是Freemarker库的一个具体版本,版本号为2.3.28,它是Java的一个可执行的JAR(Java Archive)文件,用于在Eclipse集成开发环境中作为插件使用。 在Freemarker的2.3.28版本中,我们可以...