Package groovy.text.markup

# Class BaseTemplate

java.lang.Object
groovy.text.markup.BaseTemplate

All Implemented Interfaces:
  `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(java.util.Map)`)} on a template generated by `MarkupTemplateEngine.createTemplate(java.io.Reader)`.

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(Class)` method.

- ## Constructor Summary

  Constructors
  Constructor
  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.

- ## Method Summary

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

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### BaseTemplate

    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 Details

  - ### getModel

    public Map getModel()
    Returns the model currently exposed to the template.
    Returns:
      the model map, never `null`

  - ### run

    public abstract Object run()
    Executes the compiled template body.
    Returns:
      the script result produced by the compiled template

  - ### yieldUnescaped

    public BaseTemplate yieldUnescaped(Object obj) throws IOException
    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.
    Parameters:
      `obj` - the object to be rendered unescaped
    Returns:
      this template instance
    Throws:
      `IOException`

  - ### yield

    public BaseTemplate yield(Object obj) throws IOException
    Renders the object provided as parameter using its `Object.toString()` method, The contents is rendered after being escaped for XML, enforcing valid XML output.
    Parameters:
      `obj` - the object to be rendered
    Returns:
      this template instance
    Throws:
      `IOException`

  - ### stringOf

    public String stringOf(Closure cl) throws IOException
    Renders the supplied closure into an in-memory buffer and returns the resulting text.
    Parameters:
      `cl` - closure to render
    Returns:
      the rendered closure output
    Throws:
      `IOException` - if writing the closure output fails

  - ### comment

    public BaseTemplate comment(Object cs) throws IOException
    Renders the supplied object using its `Object.toString()` method inside a comment markup block (<!-- ... -->). The object is rendered as is, unescaped.
    Parameters:
      `cs` - the object to be rendered inside an XML comment block.
    Returns:
      this template instance.
    Throws:
      `IOException`

  - ### xmlDeclaration

    public BaseTemplate xmlDeclaration() throws IOException
    Renders an XML declaration header. If the declaration encoding is set in the `template configuration`, then the encoding is rendered into the declaration.
    Returns:
      this template instance
    Throws:
      `IOException`

  - ### pi

    public BaseTemplate pi(Map<?,?> attrs) throws IOException

    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'?>

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

  - ### methodMissing

    public Object methodMissing(String tagName, Object args) throws IOException
    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)

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

  - ### includeGroovy

    public void includeGroovy(String templatePath) throws IOException, ClassNotFoundException
    Includes another template inside this template.
    Parameters:
      `templatePath` - the path to the included resource.
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### includeEscaped

    public void includeEscaped(String templatePath) throws IOException
    Includes contents of another file, not as a template but as escaped text.
    Parameters:
      `templatePath` - the path to the other file
    Throws:
      `IOException`

  - ### includeUnescaped

    public void includeUnescaped(String templatePath) throws IOException
    Includes contents of another file, not as a template but as unescaped text.
    Parameters:
      `templatePath` - the path to the other file
    Throws:
      `IOException`

  - ### tryEscape

    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

  - ### getOut

    public Writer getOut()
    Convenience method to return the current writer instance.
    Returns:
      the current writer

  - ### newLine

    public void newLine() throws IOException
    Adds a new line to the output. The new line string can be configured by `TemplateConfiguration.setNewLineString(String)`
    Throws:
      `IOException`

  - ### fragment

    public Object fragment(Map model, String templateText) throws IOException, ClassNotFoundException
    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)`.
    Parameters:
      `model` - model to be passed to the template
      `templateText` - template body
    Returns:
      this template instance
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### layout

    public Object layout(Map model, String templateName) throws IOException, ClassNotFoundException
    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)`.
    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
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### layout

    public Object layout(Map model, String templateName, boolean inheritModel) throws IOException, ClassNotFoundException
    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.
    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
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### contents

    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

  - ### writeTo

    public Writer writeTo(Writer out) throws IOException
    Main method used to render a template.
    Specified by:
      `writeTo` in interface `Writable`
    Parameters:
      `out` - the Writer to which this Writable should output its data.
    Returns:
      a writer instance
    Throws:
      `IOException`

  - ### toString

    public String toString()
    Renders this template to a string by writing it to an in-memory buffer.
    Overrides:
      `toString` in class `Object`
    Returns:
      rendered template output