public class DefaultTruncateBuiltinAlgorithm extends TruncateBuiltinAlgorithm
TruncateBuiltinAlgorithm
implementation; see
Configurable.setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm)
.
To know the properties of this TruncateBuiltinAlgorithm
implementation, see the
constructor. You can find more explanation and
examples in the documentation of the truncate
built-in in the FreeMarker Manual.Modifier and Type | Field and Description |
---|---|
static DefaultTruncateBuiltinAlgorithm |
ASCII_INSTANCE
Instance that uses
"[...]" as the defaultTerminator constructor argument, and thus is
safe to use for all output charsets. |
static double |
DEFAULT_WORD_BOUNDARY_MIN_LENGTH
The value used in the constructor of
ASCII_INSTANCE and UNICODE_INSTANCE as the
wordBoundaryMinLength argument. |
static java.lang.String |
STANDARD_ASCII_TERMINATOR
Used by
ASCII_INSTANCE as the terminator. |
static TemplateHTMLOutputModel |
STANDARD_M_TERMINATOR
Used by
ASCII_INSTANCE and UNICODE_INSTANCE as the markup terminator;
HTML <span class='truncateTerminator'>[…]</span> , where … is the ellipsis (…)
character. |
static java.lang.String |
STANDARD_UNICODE_TERMINATOR
Used by
UNICODE_INSTANCE as the terminator. |
static DefaultTruncateBuiltinAlgorithm |
UNICODE_INSTANCE
Instance that uses
"[…]" as the defaultTerminator constructor argument, which contains
ellipsis character ("…" , U+2026), and thus only works with UTF-8, and the cp125x charsets (like
cp1250), and with some other rarely used ones. |
Constructor and Description |
---|
DefaultTruncateBuiltinAlgorithm(java.lang.String defaultTerminator,
boolean addSpaceAtWordBoundary)
Creates an instance with string (plain text) terminator.
|
DefaultTruncateBuiltinAlgorithm(java.lang.String defaultTerminator,
java.lang.Integer defaultTerminatorLength,
java.lang.Boolean defaultTerminatorRemovesDots,
TemplateMarkupOutputModel<?> defaultMTerminator,
java.lang.Integer defaultMTerminatorLength,
java.lang.Boolean defaultMTerminatorRemovesDots,
boolean addSpaceAtWordBoundary,
java.lang.Double wordBoundaryMinLength)
Creates an instance with markup terminator.
|
DefaultTruncateBuiltinAlgorithm(java.lang.String defaultTerminator,
TemplateMarkupOutputModel<?> defaultMTerminator,
boolean addSpaceAtWordBoundary)
Creates an instance with a string (plain text) terminator and a markup terminator.
|
Modifier and Type | Method and Description |
---|---|
boolean |
getAddSpaceAtWordBoundary()
See similarly named parameter of
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double) the construction}. |
TemplateMarkupOutputModel<?> |
getDefaultMTerminator()
See similarly named parameter of
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double) the construction}. |
java.lang.Integer |
getDefaultMTerminatorLength()
See similarly named parameter of
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double) the construction}. |
boolean |
getDefaultMTerminatorRemovesDots() |
java.lang.String |
getDefaultTerminator() |
int |
getDefaultTerminatorLength()
See similarly named parameter of
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double) the construction}. |
boolean |
getDefaultTerminatorRemovesDots()
See similarly named parameter of
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double) the construction}. |
protected int |
getMTerminatorLength(TemplateMarkupOutputModel<?> mTerminator)
Returns the (estimated) length of the argument terminator.
|
protected boolean |
getMTerminatorRemovesDots(TemplateMarkupOutputModel terminator)
Same as
getTerminatorRemovesDots(String) , but invoked for a markup terminator. |
protected boolean |
getTerminatorRemovesDots(java.lang.String terminator)
Tells if the dots touched by the terminator text should be removed.
|
double |
getWordBoundaryMinLength()
See similarly named parameter of
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double) the construction}. |
TemplateScalarModel |
truncate(java.lang.String s,
int maxLength,
TemplateScalarModel terminator,
java.lang.Integer terminatorLength,
Environment env)
Corresponds to
?truncate(...) in templates. |
TemplateScalarModel |
truncateC(java.lang.String s,
int maxLength,
TemplateScalarModel terminator,
java.lang.Integer terminatorLength,
Environment env)
Corresponds to
?truncate_c_m(...) in templates. |
TemplateModel |
truncateCM(java.lang.String s,
int maxLength,
TemplateModel terminator,
java.lang.Integer terminatorLength,
Environment env)
Corresponds to
?truncate_c_m(...) in templates. |
TemplateModel |
truncateM(java.lang.String s,
int maxLength,
TemplateModel terminator,
java.lang.Integer terminatorLength,
Environment env)
Corresponds to
?truncate_m(...) in templates. |
TemplateScalarModel |
truncateW(java.lang.String s,
int maxLength,
TemplateScalarModel terminator,
java.lang.Integer terminatorLength,
Environment env)
Corresponds to
?truncate_w(...) in templates. |
TemplateModel |
truncateWM(java.lang.String s,
int maxLength,
TemplateModel terminator,
java.lang.Integer terminatorLength,
Environment env)
Corresponds to
?truncate_w_m(...) in templates. |
public static final java.lang.String STANDARD_ASCII_TERMINATOR
ASCII_INSTANCE
as the terminator.public static final java.lang.String STANDARD_UNICODE_TERMINATOR
UNICODE_INSTANCE
as the terminator.public static final TemplateHTMLOutputModel STANDARD_M_TERMINATOR
ASCII_INSTANCE
and UNICODE_INSTANCE
as the markup terminator;
HTML <span class='truncateTerminator'>[…]</span>
, where …
is the ellipsis (…)
character. Note that while the ellipsis character is not in US-ASCII, this still works safely regardless of
output charset, as …
itself only contains US-ASCII characters.public static final double DEFAULT_WORD_BOUNDARY_MIN_LENGTH
ASCII_INSTANCE
and UNICODE_INSTANCE
as the
wordBoundaryMinLength
argument.public static final DefaultTruncateBuiltinAlgorithm ASCII_INSTANCE
"[...]"
as the defaultTerminator
constructor argument, and thus is
safe to use for all output charsets. Because of that, this is the default of
Configurable.setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm)
. The
defaultMTerminator
(markup terminator) is STANDARD_M_TERMINATOR
, and the
wordBoundaryMinLength
is DEFAULT_WORD_BOUNDARY_MIN_LENGTH
, and addSpaceAtWordBoundary
is true
.public static final DefaultTruncateBuiltinAlgorithm UNICODE_INSTANCE
"[…]"
as the defaultTerminator
constructor argument, which contains
ellipsis character ("…"
, U+2026), and thus only works with UTF-8, and the cp125x charsets (like
cp1250), and with some other rarely used ones. It does not work (becomes to a question mark) with ISO-8859-x
charsets (like ISO-8859-1), which are probably the most often used charsets after UTF-8.
The defaultMTerminator
(markup terminator) is STANDARD_M_TERMINATOR
, and the
wordBoundaryMinLength
is DEFAULT_WORD_BOUNDARY_MIN_LENGTH
, and addSpaceAtWordBoundary
is true
.
public DefaultTruncateBuiltinAlgorithm(java.lang.String defaultTerminator, TemplateMarkupOutputModel<?> defaultMTerminator, boolean addSpaceAtWordBoundary)
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel,
Integer, Boolean, boolean, Double)
; the missing parameters will be null
.public DefaultTruncateBuiltinAlgorithm(java.lang.String defaultTerminator, boolean addSpaceAtWordBoundary)
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel,
Integer, Boolean, boolean, Double)
; the missing parameters will be null
.public DefaultTruncateBuiltinAlgorithm(java.lang.String defaultTerminator, java.lang.Integer defaultTerminatorLength, java.lang.Boolean defaultTerminatorRemovesDots, TemplateMarkupOutputModel<?> defaultMTerminator, java.lang.Integer defaultMTerminatorLength, java.lang.Boolean defaultMTerminatorRemovesDots, boolean addSpaceAtWordBoundary, java.lang.Double wordBoundaryMinLength)
defaultTerminator
- The terminator to use if the invocation (like s?truncate(20)
) doesn't specify it. The
terminator is the text appended after a truncated string, to indicate that it was truncated.
Typically it's "[...]"
or "..."
, or the same with UNICODE ellipsis character.defaultTerminatorLength
- The assumed length of defaultTerminator
, or null
if it should be get via
defaultTerminator.length()
.defaultTerminatorRemovesDots
- Whether dots and ellipsis characters that the defaultTerminator
touches should be removed. If
null
, this will be auto-detected based on if defaultTerminator
starts with dot or
ellipsis. The goal is to avoid outcomes where we have more dots next to each other than there are in
the terminator.defaultMTerminator
- Similar to defaultTerminator
, but is markup instead of plain text. This can be null
,
in which case defaultTerminator
will be used even if ?truncate_m
or similar built-in
is called.defaultMTerminatorLength
- The assumed length of the terminator, or null
if it should be get via
getMTerminatorLength(freemarker.core.TemplateMarkupOutputModel<?>)
.defaultMTerminatorRemovesDots
- Similar to defaultTerminatorRemovesDots
, but for defaultMTerminator
. If null
, and defaultMTerminator
is HTML/XML/XHTML, then it will be examined of the
first character of the terminator that's outside a HTML/XML tag or comment is dot or ellipsis
(after resolving numerical character references). For other kind of markup it defaults to true
, to be on the safe side.addSpaceAtWordBoundary,
- Whether to add a space before the terminator if the truncation happens directly after the end of a
word. For example, when "too long sentence" is truncated, it will be a like "too long [...]"
instead of "too long[...]". When the truncation happens inside a word, this has on effect, i.e., it
will be always like "too long se[...]" (no space before the terminator). Note that only whitespace is
considered to be a word separator, not punctuation, so if this is true
, you get results
like "Some sentence. [...]".wordBoundaryMinLength
- Used when truncate(java.lang.String, int, freemarker.template.TemplateScalarModel, java.lang.Integer, freemarker.core.Environment)
or truncateM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)
has to decide between
word boundary truncation and character boundary truncation; it's the minimum length, given as
proportion of maxLength
, that word boundary truncation has to produce. If the resulting
length is less, we do character boundary truncation instead. For example, if maxLength
is
30, and this parameter is 0.85, then: 30*0.85 = 25.5, rounded up that's 26, so the resulting length
must be at least 26. The result of character boundary truncation will be always accepted, even if its
still too short. If this parameter is null
, then DEFAULT_WORD_BOUNDARY_MIN_LENGTH
will be used. If this parameter is 0, then truncation always happens at word boundary. If this
parameter is 1.0, then truncation doesn't prefer word boundaries over other places.public TemplateScalarModel truncate(java.lang.String s, int maxLength, TemplateScalarModel terminator, java.lang.Integer terminatorLength, Environment env) throws TemplateException
TruncateBuiltinAlgorithm
?truncate(...)
in templates.
Similar to TruncateBuiltinAlgorithm.truncateM(String, int, TemplateModel, Integer, Environment)
, but only allows
an FTL string as terminator, and thence the return value is always an FTL string as well (not
TemplateMarkupOutputModel
).truncate
in class TruncateBuiltinAlgorithm
TemplateException
public TemplateScalarModel truncateW(java.lang.String s, int maxLength, TemplateScalarModel terminator, java.lang.Integer terminatorLength, Environment env) throws TemplateException
TruncateBuiltinAlgorithm
?truncate_w(...)
in templates.
Same as TruncateBuiltinAlgorithm.truncateWM(String, int, TemplateModel, Integer, Environment)
, but only allows
an FTL string as terminator, and thence the return value is always an FTL string as well (not
TemplateMarkupOutputModel
).truncateW
in class TruncateBuiltinAlgorithm
TemplateException
public TemplateScalarModel truncateC(java.lang.String s, int maxLength, TemplateScalarModel terminator, java.lang.Integer terminatorLength, Environment env) throws TemplateException
TruncateBuiltinAlgorithm
?truncate_c_m(...)
in templates.
Same as TruncateBuiltinAlgorithm.truncateCM(String, int, TemplateModel, Integer, Environment)
, but only allows
an FTL string as terminator, and thence the return value is always an FTL string as well (not markup).truncateC
in class TruncateBuiltinAlgorithm
TemplateException
public TemplateModel truncateM(java.lang.String s, int maxLength, TemplateModel terminator, java.lang.Integer terminatorLength, Environment env) throws TemplateException
TruncateBuiltinAlgorithm
?truncate_m(...)
in templates. This method decides automatically if it will truncate at
word boundary (see TruncateBuiltinAlgorithm.truncateWM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)
) or at character boundary (see TruncateBuiltinAlgorithm.truncateCM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)
). While it depends
on the implementation, the idea is that it should truncate at word boundary, unless that gives a too short
string, in which case it falls back to truncation at character duration.
The terminator and the return value can be TemplateMarkupOutputModel
(FTL markup output type), not
just String
(FTL string type), hence the "m" in the name.
truncateM
in class TruncateBuiltinAlgorithm
s
- The input string whose length need to be limited. The caller (the FreeMarker core normally) is
expected to guarantee that this won't be null
.maxLength
- The maximum length of the returned string, although the algorithm need not guarantee this strictly.
For example, if this is less than the length of the terminator
string, then most algorithms
should still return the terminator
string. Or, some sophisticated algorithm may counts in
letters differently depending on their visual width. The goal is usually to prevent unusually long
string values to ruin visual layout, while showing clearly to the user that the end of the string
was cut off. If the input string is not longer than the maximum length, then it should be returned
as is. The caller (the FreeMarker core normally) is expected to guarantee that this will be at
least 0.terminator
- The string or markup to show at the end of the returned string if the string was actually truncated.
This can be null
, in which case the default terminator of the algorithm will be used. It
can be an FTL string (a TemplateScalarModel
) of any length (including 0), or a
TemplateMarkupOutputModel
(typically HTML markup). If it's TemplateMarkupOutputModel
,
then the result is TemplateMarkupOutputModel
of the same output format as well, otherwise
it can remain TemplateScalarModel
. Note that the length of the terminator counts into the
result length that shouldn't be exceed (maxLength
) (or at least the algorithm should make
an effort to avoid that).terminatorLength
- The assumed length of the terminator. If this is null
(and typically it is), then the method
decides the length of the terminator. If this is not null
, then the method must pretend
that the terminator length is this. This can be used to specify the visual length of a terminator
explicitly, which can't always be decided well programmatically.env
- The runtime environment from which this algorithm was called. The caller (the FreeMarker core
normally) is expected to guarantee that this won't be null
.TemplateScalarModel
(FTL string), or a
TemplateMarkupOutputModel
.TemplateException
- If anything goes wrong during truncating. It's unlikely that an implementation will need this though.public TemplateModel truncateWM(java.lang.String s, int maxLength, TemplateModel terminator, java.lang.Integer terminatorLength, Environment env) throws TemplateException
TruncateBuiltinAlgorithm
?truncate_w_m(...)
in templates.
Similar to TruncateBuiltinAlgorithm.truncateM(String, int, TemplateModel, Integer, Environment)
, but the
truncation should happen at word boundary (hence the "w"). That is, the truncation isn't allowed to truncate a
word. What counts as a word, is up to the implementation, but at least in DefaultTruncateBuiltinAlgorithm
words are the sections that are separated by whitespace (so punctuation doesn't separate words).truncateWM
in class TruncateBuiltinAlgorithm
TemplateException
public TemplateModel truncateCM(java.lang.String s, int maxLength, TemplateModel terminator, java.lang.Integer terminatorLength, Environment env) throws TemplateException
TruncateBuiltinAlgorithm
?truncate_c_m(...)
in templates.
Similar to TruncateBuiltinAlgorithm.truncateM(String, int, TemplateModel, Integer, Environment)
, but the
truncation should not prefer truncating at word boundaries over the closer approximation of the desired maxLength
. Hence, we say that it truncates at character boundary (hence the "c").truncateCM
in class TruncateBuiltinAlgorithm
TemplateException
public java.lang.String getDefaultTerminator()
public int getDefaultTerminatorLength()
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)
the construction}.public boolean getDefaultTerminatorRemovesDots()
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)
the construction}.public TemplateMarkupOutputModel<?> getDefaultMTerminator()
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)
the construction}.public java.lang.Integer getDefaultMTerminatorLength()
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)
the construction}.public boolean getDefaultMTerminatorRemovesDots()
public double getWordBoundaryMinLength()
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)
the construction}.public boolean getAddSpaceAtWordBoundary()
DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean,
TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)
the construction}.protected int getMTerminatorLength(TemplateMarkupOutputModel<?> mTerminator) throws TemplateModelException
In the implementation in DefaultTruncateBuiltinAlgorithm
, if the markup is HTML/XML/XHTML, then this
counts the characters outside tags and comments, and inside CDATA sections (ignoring the CDATA section
delimiters). Furthermore then it counts character and entity references as having length of 1. If the markup
is not HTML/XML/XHTML (or subclasses of those MarkupOutputFormat
-s) then it doesn't know how to
measure it, and simply returns 3.
TemplateModelException
protected boolean getTerminatorRemovesDots(java.lang.String terminator) throws TemplateModelException
The implementation in DefaultTruncateBuiltinAlgorithm
return true
if the terminator starts
with dot (or ellipsis).
terminator
- A TemplateScalarModel
or TemplateMarkupOutputModel
. Not null
.TemplateModelException
protected boolean getMTerminatorRemovesDots(TemplateMarkupOutputModel terminator) throws TemplateModelException
getTerminatorRemovesDots(String)
, but invoked for a markup terminator.
The implementation in DefaultTruncateBuiltinAlgorithm
will skip HTML/XML tags and comments,
and resolves relevant character references to find out if the first character is dot or ellipsis. But it only
does this for HTML/XMl/XHTML (or subclasses of those MarkupOutputFormat
-s), otherwise it always
returns true
to be on the safe side.
TemplateModelException