Class TemplateLookupStrategy
- java.lang.Object
-
- freemarker.cache.TemplateLookupStrategy
-
public abstract class TemplateLookupStrategy extends java.lang.Object
Finds theTemplateLoader
-level (storage-level) template source for the template name with which the template was requested (as inConfiguration.getTemplate(String)
). This usually means trying variousTemplateLoader
-level template names (so called source names; see alsoTemplate.getSourceName()
) that were deduced from the requested name. Trying a name usually means callingTemplateLookupContext.lookupWithAcquisitionStrategy(String)
with it and checking the value ofTemplateLookupResult.isPositive()
.Before you write your own lookup strategy, know that:
- A template lookup strategy meant to operate solely with template names, not with
TemplateLoader
-s directly. Basically, it's a mapping between the template names that templates and API-s likeConfiguration.getTemplate(String)
see, and those that the underlyingTemplateLoader
sees. - A template lookup strategy doesn't influence the template's name (
Template.getName()
), which is the normalized form of the template name as it was requested (withConfiguration.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". - Understand the impact of the last point if your template lookup strategy fiddles not only with the file name part of the template name, but also with the directory part. For example, one may want to map "foo.ftl" to "en/foo.ftl", "fr/foo.ftl", etc. That's legal, but the result is kind of like if you had several root directories ("en/", "fr/", etc.) that are layered over each other to form a single merged directory. (This is what's desirable in typical applications, yet it can be confusing.)
- Since:
- 2.3.22
- See Also:
Configuration.setTemplateLookupStrategy(TemplateLookupStrategy)
- A template lookup strategy meant to operate solely with template names, not with
-
-
Field Summary
Fields Modifier and Type Field Description static TemplateLookupStrategy
DEFAULT_2_3_0
The default lookup strategy of FreeMarker.
-
Constructor Summary
Constructors Constructor Description TemplateLookupStrategy()
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description abstract TemplateLookupResult
lookup(TemplateLookupContext ctx)
Finds the template source that matches the template name, locale (if notnull
) and other parameters specified in theTemplateLookupContext
.
-
-
-
Field Detail
-
DEFAULT_2_3_0
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
andLocale("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 isfoo_bar.ftl
, it won't remove the"_bar"
).
-
-
Method Detail
-
lookup
public abstract TemplateLookupResult lookup(TemplateLookupContext ctx) throws java.io.IOException
Finds the template source that matches the template name, locale (if notnull
) and other parameters specified in theTemplateLookupContext
. See also the class-levelTemplateLookupStrategy
documentation to understand lookup strategies more.- Parameters:
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 areTemplateLookupContext.lookupWithAcquisitionStrategy(String)
andTemplateLookupContext.createNegativeLookupResult()
. (Note that you deliberately can't useTemplateLoader
-s directly to implement lookup.)- Returns:
- Usually the return value of
TemplateLookupContext.lookupWithAcquisitionStrategy(String)
, orTemplateLookupContext#createNegativeLookupResult()
if no matching template exists. Can't benull
. - Throws:
java.io.IOException
-
-