0
# Groovy Templates
1

2
Groovy Templates provides a comprehensive set of template engines for generating dynamic content from templates using various approaches. The library supports JSP-style scripting syntax with `<% %>` blocks and `<%= %>` expressions, GString-style variable interpolation, XML template processing with DOM manipulation, markup builders for generating structured content, and high-performance streaming templates for large-scale content generation.
3

4
## Package Information
5

6
- **Package Name**: groovy-templates
7
- **Package Type**: Maven
8
- **Language**: Java/Groovy
9
- **Installation**: Add to your Gradle build: `implementation 'org.codehaus.groovy:groovy-templates:3.0.25'`
10
- **Maven**: 
11
  ```xml
12
  <dependency>
13
    <groupId>org.codehaus.groovy</groupId>
14
    <artifactId>groovy-templates</artifactId>
15
    <version>3.0.25</version>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import groovy.text.*;
23
import groovy.text.markup.*;
24
```
25

26
## Basic Usage
27

28
```java
29
import groovy.text.SimpleTemplateEngine;
30
import groovy.text.Template;
31
import java.util.HashMap;
32
import java.util.Map;
33

34
// Create template engine
35
SimpleTemplateEngine engine = new SimpleTemplateEngine();
36

37
// Create template from string
38
String templateText = """
39
Dear <%= firstname %> ${lastname},
40

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

45
The conference committee.
46
""";
47

48
Template template = engine.createTemplate(templateText);
49

50
// Create binding data
51
Map<String, Object> binding = new HashMap<>();
52
binding.put("firstname", "Grace");
53
binding.put("lastname", "Hopper");
54
binding.put("accepted", true);
55
binding.put("title", "Groovy for COBOL programmers");
56

57
// Generate output
58
String result = template.make(binding).toString();
59
```
60

61
## Architecture
62

63
Groovy Templates follows a template engine pattern where:
64

65
1. **TemplateEngine** - Factory for creating Template instances from various sources
66
2. **Template** - Compiled template that can be bound with data and executed
67
3. **Writable** - Result that can be written to any Writer or converted to String
68

69
The library provides multiple template engine implementations optimized for different use cases, from simple text templating to complex XML/HTML generation with type safety.
70

71
## Capabilities
72

73
### Basic Template Engines
74

75
Core template engines supporting JSP-style and GString syntax for simple to moderate templating needs.
76

77
```java { .api }
78
class SimpleTemplateEngine extends TemplateEngine {
79
    SimpleTemplateEngine();
80
    SimpleTemplateEngine(boolean verbose);
81
    SimpleTemplateEngine(ClassLoader parentLoader);
82
    SimpleTemplateEngine(GroovyShell groovyShell);
83
    
84
    Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
85
    void setVerbose(boolean verbose);
86
    boolean isVerbose();
87
    void setEscapeBackslash(boolean escapeBackslash);
88
    boolean isEscapeBackslash();
89
}
90
```
91

92
```java { .api }
93
class GStringTemplateEngine extends TemplateEngine {
94
    GStringTemplateEngine();
95
    GStringTemplateEngine(ClassLoader parentLoader);
96
    
97
    Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
98
}
99
```
100

101
[Basic Template Engines](./basic-template-engines.md)
102

103
### XML Template Engine
104

105
Specialized template engine for XML document generation with support for GSP tags and automatic XML formatting.
106

107
```java { .api }
108
class XmlTemplateEngine extends TemplateEngine {
109
    XmlTemplateEngine() throws SAXException, ParserConfigurationException;
110
    XmlTemplateEngine(String indentation, boolean validating) throws SAXException, ParserConfigurationException;
111
    XmlTemplateEngine(XmlParser xmlParser, ClassLoader parentLoader);
112
    XmlTemplateEngine(XmlParser xmlParser, GroovyShell groovyShell);
113
    
114
    Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
115
    void setIndentation(String indentation);
116
    String getIndentation();
117
    void setConfigurePrinter(Closure configurePrinter);
118
}
119
```
120

121
[XML Template Engine](./xml-template-engine.md)
122

123
### Streaming Template Engine
124

125
High-performance template engine optimized for large templates (>64k) with better error reporting and memory efficiency.
126

127
```java { .api }
128
class StreamingTemplateEngine extends TemplateEngine {
129
    StreamingTemplateEngine();
130
    StreamingTemplateEngine(ClassLoader parentLoader);
131
    
132
    Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
133
}
134
```
135

136
[Streaming Template Engine](./streaming-template-engine.md)
137

138
### Markup Template Engine
139

140
Advanced type-safe template engine for XML/HTML generation with compile-time checking, template inheritance, and layout support.
141

142
```java { .api }
143
class MarkupTemplateEngine extends TemplateEngine {
144
    MarkupTemplateEngine();
145
    MarkupTemplateEngine(TemplateConfiguration config);
146
    MarkupTemplateEngine(ClassLoader parentLoader, TemplateConfiguration config);
147
    MarkupTemplateEngine(ClassLoader parentLoader, TemplateConfiguration config, TemplateResolver resolver);
148
    
149
    Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
150
}
151
```
152

153
```java { .api }
154
class TemplateConfiguration {
155
    TemplateConfiguration();
156
    TemplateConfiguration(TemplateConfiguration that);
157
    
158
    // XML/HTML output configuration
159
    void setDeclarationEncoding(String declarationEncoding);
160
    String getDeclarationEncoding();
161
    void setExpandEmptyElements(boolean expandEmptyElements);
162
    boolean isExpandEmptyElements();
163
    void setUseDoubleQuotes(boolean useDoubleQuotes);
164
    boolean isUseDoubleQuotes();
165
    void setNewLineString(String newLineString);
166
    String getNewLineString();
167
    
168
    // Content processing configuration
169
    void setAutoEscape(boolean autoEscape);
170
    boolean isAutoEscape();
171
    void setAutoIndent(boolean autoIndent);
172
    boolean isAutoIndent();
173
    void setAutoIndentString(String autoIndentString);
174
    String getAutoIndentString();
175
    void setAutoNewLine(boolean autoNewLine);
176
    boolean isAutoNewLine();
177
    
178
    // Template system configuration
179
    void setBaseTemplateClass(Class<? extends BaseTemplate> baseTemplateClass);
180
    Class<? extends BaseTemplate> getBaseTemplateClass();
181
    void setLocale(Locale locale);
182
    Locale getLocale();
183
    void setCacheTemplates(boolean cacheTemplates);
184
    boolean isCacheTemplates();
185
}
186
```
187

188
[Markup Template Engine](./markup-template-engine.md)
189

190
## Core Interfaces
191

192
### TemplateEngine
193

194
Abstract base class for all template engines providing common template creation methods.
195

196
```java { .api }
197
abstract class TemplateEngine {
198
    abstract Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
199
    Template createTemplate(String templateText) throws CompilationFailedException, ClassNotFoundException, IOException;
200
    Template createTemplate(File file) throws CompilationFailedException, ClassNotFoundException, IOException;
201
    Template createTemplate(File file, Charset cs) throws CompilationFailedException, ClassNotFoundException, IOException;
202
    Template createTemplate(URL url) throws CompilationFailedException, ClassNotFoundException, IOException;
203
    Template createTemplate(URL url, Charset cs) throws CompilationFailedException, ClassNotFoundException, IOException;
204
}
205
```
206

207
### Template
208

209
Interface representing a compiled template that can be bound with data and executed.
210

211
```java { .api }
212
interface Template {
213
    Writable make();
214
    Writable make(Map binding);
215
}
216
```
217

218
### TemplateResolver
219

220
Interface for template resolvers used by MarkupTemplateEngine to locate template resources.
221

222
```java { .api }
223
interface TemplateResolver {
224
    void configure(ClassLoader templateClassLoader, TemplateConfiguration configuration);
225
    URL resolveTemplate(String templatePath) throws IOException;
226
}
227
```
228

229
## Exception Handling
230

231
```java { .api }
232
class TemplateExecutionException extends Exception {
233
    TemplateExecutionException(int lineNumber);
234
    TemplateExecutionException(int lineNumber, String message);
235
    TemplateExecutionException(int lineNumber, String message, Throwable cause);
236
    TemplateExecutionException(int lineNumber, Throwable cause);
237
    
238
    int getLineNumber();
239
}
240
```
241

242
```java { .api }
243
class TemplateParseException extends RuntimeException {
244
    TemplateParseException(int lineNumber, int column);
245
    TemplateParseException(String message, int lineNumber, int column);
246
    TemplateParseException(String message, Throwable cause, int lineNumber, int column);
247
    TemplateParseException(Throwable t, int lineNumber, int column);
248
    
249
    int getLineNumber();
250
    int getColumn();
251
}
252
```
253

254
## Types
255

256
```java { .api }
257
// From Groovy Lang
258
interface Writable {
259
    Writer writeTo(Writer writer) throws IOException;
260
}
261

262
// Standard Java types used throughout
263
interface Map<K,V> { }
264
interface Reader { }
265
interface Writer { }
266
class File { }
267
class URL { }
268
class Charset { }
269
class Locale { }
270
class ClassLoader { }
271
```