Package: groovy.text

## [Java] Class GStringTemplateEngine

- groovy.text.GStringTemplateEngine

-     public class GStringTemplateEngine
      extends TemplateEngine

  Processes template source files substituting variables and expressions into placeholders in a template source text to produce the desired output using a streaming approach. This engine has equivalent functionality to the SimpleTemplateEngine but creates the template using writable closures making it potentially more scalable for large templates or in streaming scenarios.

  The template engine uses JSP style <% %> script and <%= %> expression syntax or GString style expressions. The variable '`out`' is bound to the writer that the template is being written to.

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

       def binding = [
           firstname : "Grace",
           lastname  : "Hopper",
           accepted  : true,
           title     : 'Groovy for COBOL programmers'
       ]
       def engine = new groovy.text.GStringTemplateEngine()
       def text = '''\
       Dear <%= firstname %> $lastname,

       We <% if (accepted) print 'are pleased' else print 'regret' %> \
       to inform you that your paper entitled
       '$title' was ${ accepted ? 'accepted' : 'rejected' }.

       The conference committee.
       '''
       def template = engine.createTemplate(text).make(binding)
       println template.toString()

  This example uses a mix of the JSP style and GString style placeholders but you can typically use just one style if you wish. Running this example will produce this output:

       Dear Grace Hopper,

       We are pleased to inform you that your paper entitled
       'Groovy for COBOL programmers' was accepted.

       The conference committee.

  The 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>GStringTemplate</servlet-name>
         <servlet-class>groovy.servlet.TemplateServlet</servlet-class>
         <init-param>
           <param-name>template.engine</param-name>
           <param-value>groovy.text.GStringTemplateEngine</param-value>
         </init-param>
       </servlet>

  In this case, your template source file should be HTML with the appropriate embedded placeholders.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `GStringTemplateEngine()` Creates an engine that parses template scripts with the default template class loader.
    `GStringTemplateEngine(ClassLoader parentLoader)` Creates an engine that parses template scripts with the supplied parent loader.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Template` | `createTemplate(Reader reader)` Creates a template backed by writable closures generated from the supplied reader.

  - ### Inherited Methods Summary

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

- - ### Constructor Detail

    - #### public GStringTemplateEngine()

      Creates an engine that parses template scripts with the default template class loader.

    - #### public GStringTemplateEngine(ClassLoader parentLoader)

      Creates an engine that parses template scripts with the supplied parent loader.

      Parameters:
        `parentLoader` - class loader used to compile generated template scripts

  - ### Method Detail

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

      Creates a template backed by writable closures generated from the supplied reader.

      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 template source fails
      Parameters:
        `reader` - template source
      Returns:
        a compiled template instance