Package: groovy.text

## [Java] Class XmlTemplateEngine

- groovy.text.XmlTemplateEngine

-     public class XmlTemplateEngine
      extends TemplateEngine

  Template engine for use in templating scenarios where both the template source and the expected output are intended to be XML.

  Templates may use the normal '${expression}' and '$variable' notations to insert an arbitrary expression into the template. In addition, support is also provided for special tags: <gsp:scriptlet> (for inserting code fragments) and <gsp:expression> (for code fragments which produce output).

  Comments and processing instructions will be removed as part of processing and special XML characters such as <, >, " and ' in the text of the template will be escaped using the respective XML notation. The output will also be indented using standard XML pretty printing.

  That escaping is applied to the template as it is read, and deliberately not to the `${expression}` and `$variable` insertions, which have to survive as Groovy for the value to be computed at all. Whatever such an insertion produces is written as it stands: a value carrying `<` or `&` reaches the output as markup rather than as text, and can leave it neither well-formed nor what the template intended. Escape a value that may contain either, with XmlUtil.escapeXml or otherwise, before binding it — always for a value that came from somewhere you do not control.

  The xmlns namespace definition for `gsp:` tags will be removed but other namespace definitions will be preserved (but may change to an equivalent position within the XML tree).

  Normally, the template source will be in a file but here is a simple example providing the XML template as a string:

       def binding = [firstname:"Jochen", lastname:"Theodorou",
                      nickname:"blackdrag", salutation:"Dear"]
       def engine = new groovy.text.XmlTemplateEngine()
       def text = '''\
       <?xml version="1.0" encoding="UTF-8"?>
       <document xmlns:gsp='http://groovy.codehaus.org/2005/gsp' xmlns:foo='baz' type='letter'>
         <gsp:scriptlet>def greeting = "${salutation}est"</gsp:scriptlet>
         <gsp:expression>greeting</gsp:expression>
         <foo:to>$firstname "$nickname" $lastname</foo:to>
         How are you today?
       </document>
       '''
       def template = engine.createTemplate(text).make(binding)
       println template.toString()

  This example will produce this output:

       <document type='letter'>
       Dearest
       <foo:to xmlns:foo='baz'>
         Jochen &quot;blackdrag&quot; Theodorou
       </foo:to>
       How are you today?
       </document>

  The XML template engine can also be used as the engine for `groovy.servlet.TemplateServlet` by placing the following in your web.xml file (plus a corresponding servlet-mapping element):

       <servlet>
         <servlet-name>XmlTemplate</servlet-name>
         <servlet-class>groovy.servlet.TemplateServlet</servlet-class>
         <init-param>
           <param-name>template.engine</param-name>
           <param-value>groovy.text.XmlTemplateEngine</param-value>
         </init-param>
       </servlet>

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static String` | `DEFAULT_INDENTATION` | Default indentation sequence used for pretty-printed XML output.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `XmlTemplateEngine()` Creates an XML template engine using the default indentation and with XML validation disabled.
    `XmlTemplateEngine(String indentation, boolean validating)` Creates an XML template engine with custom indentation and validation settings.
    `XmlTemplateEngine(XmlParser xmlParser, ClassLoader parentLoader)` Creates an XML template engine backed by the supplied parser and a GroovyShell built from the parent loader.
    `XmlTemplateEngine(XmlParser xmlParser, GroovyShell groovyShell)` Creates an XML template engine backed by the supplied parser and shell.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Template` | `createTemplate(Reader reader)` Parses XML template source from the supplied reader and compiles it into a template.
    `` | `public String` | `getIndentation()` Returns the indentation string used for pretty-printed XML output.
    `` | `public void` | `setConfigurePrinter(Closure configurePrinter)` Closure that can be used to configure the printer.
    `` | `public void` | `setIndentation(String indentation)` Sets the indentation string used for pretty-printed XML output.
    `` | `public String` | `toString()` Returns a concise engine name for diagnostics.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class TemplateEngine` | `createTemplate, createTemplate, createTemplate, createTemplate, createTemplate, createTemplate`

- - ### Field Detail

    - #### public static final String DEFAULT_INDENTATION

      Default indentation sequence used for pretty-printed XML output.

  - ### Constructor Detail

    - #### public XmlTemplateEngine()

      Creates an XML template engine using the default indentation and with XML validation disabled.

      throws:
        SAXException if the underlying parser cannot be configured
      throws:
        ParserConfigurationException if the XML parser cannot be created

    - #### public XmlTemplateEngine(String indentation, boolean validating)

      Creates an XML template engine with custom indentation and validation settings.

      throws:
        SAXException if the underlying parser cannot be configured
      throws:
        ParserConfigurationException if the XML parser cannot be created
      Parameters:
        `indentation` - indentation string used when rendering nested XML nodes
        `validating` - `true` to enable XML validation while parsing templates

    - #### public XmlTemplateEngine(XmlParser xmlParser, ClassLoader parentLoader)

      Creates an XML template engine backed by the supplied parser and a GroovyShell built from the parent loader.

      Parameters:
        `xmlParser` - parser used to read template XML
        `parentLoader` - class loader used to compile generated template scripts

    - #### public XmlTemplateEngine(XmlParser xmlParser, GroovyShell groovyShell)

      Creates an XML template engine backed by the supplied parser and shell.

      Parameters:
        `xmlParser` - parser used to read template XML
        `groovyShell` - shell used to compile generated template scripts

  - ### Method Detail

    - #### public Template createTemplate(Reader reader)

      Parses XML template source from the supplied reader and compiles it into a template.

      throws:
        CompilationFailedException if Groovy fails to compile the generated template script
      throws:
        ClassNotFoundException if the generated template class cannot be instantiated
      throws:
        IOException if reading the XML template fails
      Parameters:
        `reader` - XML template source
      Returns:
        a compiled XML template

    - #### public String getIndentation()

      Returns the indentation string used for pretty-printed XML output.

      Returns:
        the indentation sequence, never `null`

    - #### public void setConfigurePrinter(Closure configurePrinter)

      Closure that can be used to configure the printer. The printer is passed as a parameter to the closure.

           new XmlTemplateEngine(configurePrinter: { it.preserveWhitespace = true })

    - #### public void setIndentation(String indentation)

      Sets the indentation string used for pretty-printed XML output.

      Parameters:
        `indentation` - indentation sequence to use; `null` restores DEFAULT_INDENTATION

    - #### public String toString()

      Returns a concise engine name for diagnostics.

      Returns:
        the literal engine name