public abstract class TemplateLookupStrategy
extends java.lang.Object
TemplateLoader
-level (storage-level) template source for the template name with which the template
was requested (as in Configuration.getTemplate(String)
). This usually means trying various
TemplateLoader
-level template names (so called source names; see also Template.getSourceName()
) that
were deduced from the requested name. Trying a name usually means calling
TemplateLookupContext.lookupWithAcquisitionStrategy(String)
with it and checking the value of
TemplateLookupResult.isPositive()
.
Before you write your own lookup strategy, know that:
TemplateLoader
-s
directly. Basically, it's a mapping between the template names that templates and API-s like
Configuration.getTemplate(String)
see, and those that the underlying TemplateLoader
sees.
Template.getName()
), which is the
normalized form of the template name as it was requested (with Configuration.getTemplate(String)
, etc.). It
only influences the so called source name of the template (Template.getSourceName()
). The template's name is
used as the basis for resolving relative inclusions/imports in the template. The source name is pretty much only used
in error messages as error location, and of course, to actually load the template "file".
Configuration.setTemplateLookupStrategy(TemplateLookupStrategy)
Modifier and Type | Field and Description |
---|---|
static TemplateLookupStrategy |
DEFAULT_2_3_0
The default lookup strategy of FreeMarker.
|
Constructor and Description |
---|
TemplateLookupStrategy() |
Modifier and Type | Method and Description |
---|---|
abstract TemplateLookupResult |
lookup(TemplateLookupContext ctx)
Finds the template source that matches the template name, locale (if not
null ) and other parameters
specified in the TemplateLookupContext . |
public static final TemplateLookupStrategy DEFAULT_2_3_0
The default lookup strategy of FreeMarker.
Through an example: Assuming localized lookup is enabled and that a template is requested for the name
example.ftl
and Locale("es", "ES", "Traditional_WIN")
, it will try the following template names,
in this order: "foo_en_AU_Traditional_WIN.ftl"
, "foo_en_AU_Traditional.ftl"
,
"foo_en_AU.ftl"
, "foo_en.ftl"
, "foo.ftl"
. It stops at the first variation where it finds
a template. (If the template name contains "*" steps, finding the template for the attempted localized variation
happens with the template acquisition mechanism.) If localized lookup is disabled, it won't try to add any locale
strings, so it just looks for "foo.ftl"
.
The generation of the localized name variation with the default lookup strategy, happens like this: It removes
the file extension (the part starting with the last dot), then appends Locale.toString()
after
it, and puts back the extension. Then it starts to remove the parts from the end of the locale, considering
"_"
as the separator between the parts. It won't remove parts that are not part of the locale string
(like if the requested template name is foo_bar.ftl
, it won't remove the "_bar"
).
public abstract TemplateLookupResult lookup(TemplateLookupContext ctx) throws java.io.IOException
null
) and other parameters
specified in the TemplateLookupContext
. See also the class-level TemplateLookupStrategy
documentation to understand lookup strategies more.ctx
- Contains the parameters for which the matching template need to be found, and operations that
are needed to implement the strategy. Some of the important input parameters are:
TemplateLookupContext.getTemplateName()
, TemplateLookupContext.getTemplateLocale()
.
The most important operations are TemplateLookupContext.lookupWithAcquisitionStrategy(String)
and TemplateLookupContext.createNegativeLookupResult()
. (Note that you deliberately can't
use TemplateLoader
-s directly to implement lookup.)TemplateLookupContext.lookupWithAcquisitionStrategy(String)
, or
TemplateLookupContext#createNegativeLookupResult()
if no matching template exists. Can't be
null
.java.io.IOException