Class TemplateLookupStrategy


public abstract class TemplateLookupStrategy extends Object
Finds the 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:

  • 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 like Configuration.getTemplate(String) see, and those that the underlying TemplateLoader 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 (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".
  • 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.)
See Also:
  • Field Details

    • 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 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").

  • Constructor Details

    • TemplateLookupStrategy

      public TemplateLookupStrategy()
  • Method Details