Package: groovy.text.markup

## [Java] Class BaseTemplate

- groovy.text.markup.BaseTemplate

- All Implemented Interfaces and Traits:
    Writable

      public abstract class BaseTemplate
      extends Object
      implements Writable

  All templates compiled through MarkupTemplateEngine extend this abstract class, which provides a number of utility methods to generate markup. An instance of this class can be obtained after calling Template.make or Template.make)} on a template generated by MarkupTemplateEngine.createTemplate.

  It is advised to use a distinct template instance for each thread (or more simply, each rendered document) for thread safety and avoiding mixing models.

  For the application needs, it is possible to provide more helper methods by extending this class and configuring the base template class using the TemplateConfiguration.setBaseTemplateClass method.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `BaseTemplate(MarkupTemplateEngine templateEngine, Map model, Map<String, String> modelTypes, TemplateConfiguration configuration)` Creates a template instance bound to a rendering engine, model, optional model types, and configuration.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public BaseTemplate` | `comment(Object cs)` Renders the supplied object using its Object.toString method inside a comment markup block (<!
    `` | `public Closure` | `contents(Closure cl)` Wraps a closure so that it can be used as a prototype for inclusion in layouts.
    `` | `public Object` | `fragment(Map model, String templateText)` Renders an embedded template as a fragment.
    `` | `public Map` | `getModel()` Returns the model currently exposed to the template.
    `` | `public Writer` | `getOut()` Convenience method to return the current writer instance.
    `` | `public void` | `includeEscaped(String templatePath)` Includes contents of another file, not as a template but as escaped text.
    `` | `public void` | `includeGroovy(String templatePath)` Includes another template inside this template.
    `` | `public void` | `includeUnescaped(String templatePath)` Includes contents of another file, not as a template but as unescaped text.
    `` | `public Object` | `layout(Map model, String templateName)` Imports a template and renders it using the specified model, allowing fine-grained composition of templates and layouting.
    `` | `public Object` | `layout(Map model, String templateName, boolean inheritModel)` Imports a template and renders it using the specified model, allowing fine-grained composition of templates and layouting.
    `` | `public Object` | `methodMissing(String tagName, Object args)` This is the main method responsible for writing a tag and its attributes.
    `` | `public void` | `newLine()` Adds a new line to the output.
    `` | `public BaseTemplate` | `pi(Map<?, ?> attrs)`
    `` | `public abstract Object` | `run()` Executes the compiled template body.
    `` | `public String` | `stringOf(Closure cl)` Renders the supplied closure into an in-memory buffer and returns the resulting text.
    `` | `public String` | `toString()` Renders this template to a string by writing it to an in-memory buffer.
    `` | `public Object` | `tryEscape(Object contents)` Escapes the string representation of the supplied object if it derives from CharSequence, otherwise returns the object itself.
    `` | `public Writer` | `writeTo(Writer out)` Main method used to render a template.
    `` | `public BaseTemplate` | `xmlDeclaration()` Renders an XML declaration header.
    `` | `public BaseTemplate` | `yield(Object obj)` Renders the object provided as parameter using its Object.toString method, The contents is rendered after being escaped for XML, enforcing valid XML output.
    `` | `public BaseTemplate` | `yieldUnescaped(Object obj)` Renders the object provided as parameter using its Object.toString method, The contents is rendered as is, unescaped.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public BaseTemplate(MarkupTemplateEngine templateEngine, Map model, Map<String, String> modelTypes, TemplateConfiguration configuration)

      Creates a template instance bound to a rendering engine, model, optional model types, and configuration.

      Parameters:
        `templateEngine` - engine that created this template instance
        `model` - model values visible to template code
        `modelTypes` - optional model type hints used for nested type-checked templates
        `configuration` - rendering configuration

  - ### Method Detail

    - #### public BaseTemplate comment(Object cs)

      Renders the supplied object using its Object.toString method inside a comment markup block (<!-- ... -->). The object is rendered as is, unescaped.

      throws:
        IOException
      Parameters:
        `cs` - the object to be rendered inside an XML comment block.
      Returns:
        this template instance.

    - #### public Closure contents(Closure cl)

      Wraps a closure so that it can be used as a prototype for inclusion in layouts. This is useful when you want to use a closure in a model, but that you don't want to render the result of the closure but instead call it as if it was a specification of a template fragment.

      Parameters:
        `cl` - the fragment to be wrapped
      Returns:
        a wrapped closure returning an empty string

    - #### public Object fragment(Map model, String templateText)

      Renders an embedded template as a fragment. Fragments are cached in a template, meaning that if you use the same fragment in a template, it will only be compiled once, but once per template instance. This is less performant than using layout(java.util.Map, String).

      throws:
        IOException
      throws:
        ClassNotFoundException
      Parameters:
        `model` - model to be passed to the template
        `templateText` - template body
      Returns:
        this template instance

    - #### public Map getModel()

      Returns the model currently exposed to the template.

      Returns:
        the model map, never `null`

    - #### public Writer getOut()

      Convenience method to return the current writer instance.

      Returns:
        the current writer

    - #### public void includeEscaped(String templatePath)

      Includes contents of another file, not as a template but as escaped text.

      throws:
        IOException
      Parameters:
        `templatePath` - the path to the other file

    - #### public void includeGroovy(String templatePath)

      Includes another template inside this template.

      throws:
        IOException
      throws:
        ClassNotFoundException
      Parameters:
        `templatePath` - the path to the included resource.

    - #### public void includeUnescaped(String templatePath)

      Includes contents of another file, not as a template but as unescaped text.

      throws:
        IOException
      Parameters:
        `templatePath` - the path to the other file

    - #### public Object layout(Map model, String templateName)

      Imports a template and renders it using the specified model, allowing fine-grained composition of templates and layouting. This works similarly to a template include but allows a distinct model to be used. This version doesn't inherit the model from the parent. If you need model inheritance, see layout(java.util.Map, String, boolean).

      throws:
        IOException
      throws:
        ClassNotFoundException
      Parameters:
        `model` - model to be passed to the template
        `templateName` - the name of the template to be used as a layout
      Returns:
        this template instance

    - #### public Object layout(Map model, String templateName, boolean inheritModel)

      Imports a template and renders it using the specified model, allowing fine-grained composition of templates and layouting. This works similarly to a template include but allows a distinct model to be used. If the layout inherits from the parent model, a new model is created, with the values from the parent model, eventually overridden with those provided specifically for this layout.

      throws:
        IOException
      throws:
        ClassNotFoundException
      Parameters:
        `model` - model to be passed to the template
        `templateName` - the name of the template to be used as a layout
        `inheritModel` - a boolean indicating if we should inherit the parent model
      Returns:
        this template instance

    - #### public Object methodMissing(String tagName, Object args)

      This is the main method responsible for writing a tag and its attributes. The arguments may be:

      - a closure
      in which case the closure is rendered inside the tag body
      - a string
      , in which case the string is rendered as the tag body
      - a map of attributes
      in which case the attributes are rendered inside the opening tag

      or a combination of (attributes,string), (attributes,closure)

      throws:
        IOException
      Parameters:
        `tagName` - the name of the tag
        `args` - tag generation arguments
      Returns:
        this template instance

    - #### public void newLine()

      Adds a new line to the output. The new line string can be configured by TemplateConfiguration.setNewLineString

      throws:
        IOException

    - #### public BaseTemplate pi(Map<?, ?> attrs)

      Renders processing instructions. The supplied map contains all elements to be rendered as processing instructions. The key is the name of the element, the value is either a map of attributes, or an object to be rendered directly. For example:

      `pi("xml-stylesheet":[href:"mystyle.css", type:"text/css"])`

      will be rendered as:

               <?xml-stylesheet href='mystyle.css' type='text/css'?>

      throws:
        IOException
      Parameters:
        `attrs` - the attributes to render
      Returns:
        this template instance

    - #### public abstract Object run()

      Executes the compiled template body.

      Returns:
        the script result produced by the compiled template

    - #### public String stringOf(Closure cl)

      Renders the supplied closure into an in-memory buffer and returns the resulting text.

      throws:
        IOException if writing the closure output fails
      Parameters:
        `cl` - closure to render
      Returns:
        the rendered closure output

    - #### public String toString()

      Renders this template to a string by writing it to an in-memory buffer.

      Returns:
        rendered template output

    - #### public Object tryEscape(Object contents)

      Escapes the string representation of the supplied object if it derives from CharSequence, otherwise returns the object itself.

      Parameters:
        `contents` - an object to be escaped for XML
      Returns:
        an escaped string, or the object itself

    - #### public Writer writeTo(Writer out)

      Main method used to render a template.

      throws:
        IOException
      Parameters:
        `out` - the Writer to which this Writable should output its data.
      Returns:
        a writer instance

    - #### public BaseTemplate xmlDeclaration()

      Renders an XML declaration header. If the declaration encoding is set in the template configuration, then the encoding is rendered into the declaration.

      throws:
        IOException
      Returns:
        this template instance

    - #### public BaseTemplate yield(Object obj)

      Renders the object provided as parameter using its Object.toString method, The contents is rendered after being escaped for XML, enforcing valid XML output.

      throws:
        IOException
      Parameters:
        `obj` - the object to be rendered
      Returns:
        this template instance

    - #### public BaseTemplate yieldUnescaped(Object obj)

      Renders the object provided as parameter using its Object.toString method, The contents is rendered as is, unescaped. This means that depending on what the Object.toString method call returns, you might create invalid markup.

      throws:
        IOException
      Parameters:
        `obj` - the object to be rendered unescaped
      Returns:
        this template instance