Module org.klojang.templates
Package org.klojang.templates

Class Template

java.lang.Object
org.klojang.templates.Template
public final class Template extends Object
The Template class is responsible for loading and parsing templates. It also functions as a factory for RenderSession objects. Template instances are unmodifiable, expensive-to-create and heavy-weight objects. Generally though you should not cache them as this is already done by Klojang Templates. You can disable template caching by means of a system property. See Setting.TMPL_CACHE_SIZE. This can be useful during development and/or debugging as the template file will be re-loaded and re-parsed every time you press the refresh button in the browser, allowing you to edit the template in between.
Author:
Ayco Holleman

  • Field Details

    • ROOT_TEMPLATE_NAME

      public static final String ROOT_TEMPLATE_NAME
      The name given to the root template: "{root}". Any Template that is explicitly instantiated by calling one of the fromXXX() methods gets this name.
      See Also:

  • Method Details

    • fromString

      public static Template fromString(String source) throws ParseException
      Parses the specified string into a Template. If the string contains any include tags (like ~%%include:/path/to/foo.html%%), the path will be interpreted as a file system resource. Templates created from a string are never cached.
      Parameters:
      source - the source code for the Template
      Returns:
      a new Template instance
      Throws:
      ParseException - if the template source contains a syntax error

    • fromString

      public static Template fromString(Class<?> clazz, String source) throws ParseException
      Parses the specified string into a Template. The specified class will be used to include other templates using Class.getResourceAsStream(). Templates created from a string are never cached.
      Parameters:
      clazz - a Class object that provides access to the included template file by calling getResourceAsStream on it
      source - the source code for the Template
      Returns:
      a Template instance
      Throws:
      ParseException - if the template source contains a syntax error

    • fromResource

      public static Template fromResource(Class<?> clazz, String path) throws ParseException
      Parses the specified resource into a Template. Templates created from a classpath resource are always cached. Thus, calling this method multiple times with the same clazz and path arguments will always return the same instance. Make sure the provided class is publicly accessible. Otherwise Klojang Templates cannot use it to open an InputStream to the resource.
      Parameters:
      clazz - a Class object that provides access to the template file by calling getResourceAsStream on it
      path - the location of the template file
      Returns:
      a Template instance
      Throws:
      ParseException - if the template source contains a syntax error

    • fromFile

      public static Template fromFile(String path) throws ParseException
      Parses the specified file into a Template. Templates created from file are always cached. Thus, calling this method multiple times with the same path argument will always return the same instance.
      Parameters:
      path - the path of the file to be parsed
      Returns:
      a Template instance
      Throws:
      ParseException - if the template source contains a syntax error

    • fromResolver

      public static Template fromResolver(PathResolver resolver, String path) throws ParseException
      Creates a Template from the source provided by the specified PathResolver. Templates created using a PathResolver are always cached. Thus, calling this method multiple times with the same PathResolver (as per its equals() method) and the same path will always return the same instance.
      Parameters:
      resolver - the PathResolver
      path - the path to be resolved by the PathResolver
      Returns:
      a Template instance
      Throws:
      ParseException - if the template source contains a syntax error

    • getName

      public String getName()
      Returns the name of this Template. It this Template was explicitly instantiated using one of the fromXXX() methods, its name will be "{root}"; otherwise it is a nested template and its name will be extracted from the source code (e.g. ~%%begin:foo%).
      Returns:
      the name of this Template

    • getParent

      public Template getParent()
      Returns the template inside which this Template is nested. If this Template is the root template (the template that was explicitly created by a call to one of the fromXXX() methods), this method returns null.
      Returns:
      the template inside which this Template is nested

    • getRootTemplate

      public Template getRootTemplate()
      Returns the root template of this (nested) Template. If this Template is the root template, then this method returns this. Only (and all) templates that were created using one of the fromXXX() methods are root templates.
      Returns:
      the root template of this Template

    • path

      public Optional<String> path()

      Returns an Optional containing the path to the source code of this template, or an empty Optional if the template was created from a string. In other words, for included templates this method (by definition) returns a non-empty Optional. For inline templates this method (by definition) returns an empty Optional. For templates that were explicitly created using one of the fromXXX() methods, the return value depends on whether it was fromString() or one of the other fromXXX() methods.

      Returns:
      the path to the source code for this Template

    • getVariables

      public Set<String> getVariables()
      Returns the names of the variables in this Template, in order of their first appearance in the template. The returned set only contains the names of variables that reside directly inside this Template. Variables inside nested templates are ignored. The returned Set is unmodifiable.
      Returns:
      the names of all variables in this Template
      See Also:

    • getVariableOccurrences

      public List<VariableOccurrence> getVariableOccurrences()
      Returns all occurrences of all variables within this Template. Note that a variable name may occur multiple times within the same template.
      Returns:
      all occurrences of all variables within this Template

    • countVariableOccurrences

      public int countVariableOccurrences()
      Returns the total number of variables in this Template. Note that a variable name may occur multiple times within the same template. This method does not count the number of unique variable names. To get that number, call getVariables().size().
      Returns:
      the total number of variables in this Template

    • hasVariable

      public boolean hasVariable(String name)
      Returns true if this Template directly contains a variable with the specified name. Variables inside nested templates are not considered.
      Parameters:
      name - the name of the variable
      Returns:
      true if this Template contains a variable with the specified name

    • getNestedTemplates

      public List<Template> getNestedTemplates()
      Returns all templates nested inside this Template (non-recursive). The returned List is unmodifiable.
      Returns:
      all templates nested inside this Template

    • getNestedTemplateNames

      public Set<String> getNestedTemplateNames()
      Returns the names of all templates nested inside this Template (non-recursive). The returned Set is unmodifiable.
      Returns:
      the names of all nested templates

    • hasNestedTemplate

      public boolean hasNestedTemplate(String name)
      Returns true if this Template contains a nested template with the specified name.
      Parameters:
      name - the name of the nested template
      Returns:
      true if this Template contains a nested template with the specified name

    • countNestedTemplates

      public int countNestedTemplates()
      Returns the number of templates nested inside this Template (non-recursive).
      Returns:
      the number of nested templates

    • getNestedTemplate

      public Template getNestedTemplate(String name)
      Returns the nested template identified by the specified name. This method throws an IllegalArgumentException if no nested template has the specified name.
      Parameters:
      name - the name of a nested template
      Returns:
      the Template with the specified name

    • getNames

      public List<String> getNames()
      Returns the names of all variables and nested templates within this Template (non-recursive). The returned List is unmodifiable.
      Returns:
      the names of all variables and nested templates in this Template

    • isTextOnly

      public boolean isTextOnly()
      Returns true if this is a text-only template. In other words, if this is a template without any variables or nested templates.
      Returns:
      whether this is a text-only template

    • hasVariables

      public boolean hasVariables()
      Returns true if there is at least one variable in this Template, or any Template descending from it. Contrast this with hasVariable(String), which only checks for variables directly contained in this Template.
      Returns:
      true if there are no variables in this Template, or any Template descending from it

    • newRenderSession

      public RenderSession newRenderSession()
      Returns a RenderSession that can be used to populate and render this Template. The RenderSession uses the predefined accessors to extract values from source data objects, and the predefined stringifiers to stringify those values.
      Returns:
      a RenderSession
      See Also:

    • newRenderSession

      public RenderSession newRenderSession(StringifierRegistry stringifiers)
      Returns a RenderSession that can be used to populate and render this Template. The RenderSession will use the predefined accessors to extract values from source data objects, and the specified StringifierRegistry to stringify those values.
      Parameters:
      stringifiers - the StringifierRegistry used to supply the RenderSession with stringifiers
      Returns:
      a new RenderSession

    • newRenderSession

      public RenderSession newRenderSession(AccessorRegistry accessors)
      Returns a RenderSession that can be used to populate and render this Template. The RenderSession will use the specified AccessorRegistry to extract values from source data, and the predefined stringifiers to stringify those values.
      Parameters:
      accessors - the AccessorRegistry used to supply the RenderSession with accessors
      Returns:
      a new RenderSession

    • newRenderSession

      public RenderSession newRenderSession(AccessorRegistry accessors, StringifierRegistry stringifiers)
      Returns a RenderSession that you can use to populate and render this Template. The RenderSession will use the specified AccessorRegistry to extract values from source data, and the specified StringifierRegistry to stringify those values.
      Parameters:
      accessors - the AccessorRegistry used to supply the RenderSession with accessors
      stringifiers - the StringifierRegistry used to supply the RenderSession with stringifiers
      Returns:
      a new RenderSession

    • equals

      public boolean equals(Object obj)
      Determines whether this template is equal to the specified object. Two templates are equals if they were created from the same path and PathResolver. Template instances that were created from a string are never equal to any other Template instance, even if the other instance was created from exactly the same String.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare this template with
      Returns:
      whether this template is equal to the specified object

    • hashCode

      public int hashCode()
      Returns the hash code of this Template.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this Template

    • toString

      public String toString()
      More or less re-assembles to source code from the constituent parts of the Template. Note, however, that ditch blocks are ditched early on in the parsing process and there is no trace of them left in the resulting Template instance.
      Overrides:
      toString in class Object