0
# Simple Templates
1

2
The SimpleTemplateEngine provides basic JSP-style template processing with `<% %>` scriptlets and `<%= %>` expressions. It's ideal for simple templating scenarios where ease of use and familiar syntax are priorities.
3

4
## Capabilities
5

6
### Simple Template Engine Class
7

8
Creates templates using JSP-style syntax with optional verbose debugging and backslash escaping.
9

10
```java { .api }
11
/**
12
 * Basic template engine supporting JSP-style syntax
13
 */
14
public class SimpleTemplateEngine extends TemplateEngine {
15
    /**
16
     * Creates a new SimpleTemplateEngine with default settings
17
     */
18
    public SimpleTemplateEngine();
19
    
20
    /**
21
     * Creates a new SimpleTemplateEngine with verbose mode setting
22
     * @param verbose true to enable template source debugging output
23
     */
24
    public SimpleTemplateEngine(boolean verbose);
25
    
26
    /**
27
     * Creates a new SimpleTemplateEngine with custom class loader
28
     * @param parentLoader ClassLoader for template compilation
29
     */
30
    public SimpleTemplateEngine(ClassLoader parentLoader);
31
    
32
    /**
33
     * Creates a new SimpleTemplateEngine with custom GroovyShell
34
     * @param groovyShell GroovyShell instance for script execution
35
     */
36
    public SimpleTemplateEngine(GroovyShell groovyShell);
37
    
38
    /**
39
     * Enable or disable verbose template debugging
40
     * @param verbose true to display template source for debugging
41
     */
42
    public void setVerbose(boolean verbose);
43
    
44
    /**
45
     * Check if verbose mode is enabled
46
     * @return true if verbose debugging is enabled
47
     */
48
    public boolean isVerbose();
49
    
50
    /**
51
     * Enable or disable backslash escaping for GROOVY-4585 compatibility
52
     * @param escapeBackslash true to enable backslash escaping
53
     */
54
    public void setEscapeBackslash(boolean escapeBackslash);
55
    
56
    /**
57
     * Check if backslash escaping is enabled
58
     * @return true if backslash escaping is enabled
59
     */
60
    public boolean isEscapeBackslash();
61
}
62
```
63

64
**Usage Examples:**
65

66
```java
67
import groovy.text.SimpleTemplateEngine;
68
import groovy.text.Template;
69
import groovy.lang.GroovyShell;
70
import java.util.Map;
71
import java.util.HashMap;
72

73
// Basic usage with default settings
74
SimpleTemplateEngine engine = new SimpleTemplateEngine();
75

76
// Enable verbose debugging to see generated script
77
SimpleTemplateEngine verboseEngine = new SimpleTemplateEngine(true);
78

79
// Use custom class loader
80
ClassLoader customLoader = MyClass.class.getClassLoader();
81
SimpleTemplateEngine customEngine = new SimpleTemplateEngine(customLoader);
82

83
// Use custom GroovyShell with specific configuration
84
GroovyShell shell = new GroovyShell();
85
SimpleTemplateEngine shellEngine = new SimpleTemplateEngine(shell);
86

87
// Template with mixed JSP and GString syntax
88
String templateText = """
89
Dear <%= firstname %> $lastname,
90

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

95
The conference committee.
96
""";
97

98
Template template = engine.createTemplate(templateText);
99

100
Map<String, Object> binding = new HashMap<>();
101
binding.put("firstname", "Grace");
102
binding.put("lastname", "Hopper");
103
binding.put("accepted", true);
104
binding.put("title", "Groovy for COBOL programmers");
105

106
String result = template.make(binding).toString();
107
```
108

109
### Template Syntax Support
110

111
SimpleTemplateEngine supports multiple syntax styles for maximum flexibility:
112

113
#### JSP-Style Scriptlets
114
Use `<% %>` blocks for executing Groovy code:
115

116
```java
117
String template = """
118
<% 
119
def greeting = "Hello"
120
if (name) {
121
    greeting += " " + name
122
} else {
123
    greeting += " World"
124
}
125
%>
126
$greeting!
127
""";
128
```
129

130
#### JSP-Style Expressions
131
Use `<%= %>` blocks for outputting expression results:
132

133
```java
134
String template = """
135
Current time: <%= new Date() %>
136
User count: <%= users.size() %>
137
""";
138
```
139

140
#### GString Expressions
141
Use `${expression}` or `$variable` for variable substitution:
142

143
```java
144
String template = """
145
Welcome ${user.name}!
146
Your balance is $balance.
147
""";
148
```
149

150
### Configuration Options
151

152
#### Verbose Mode
153
Enable verbose mode to see the generated Groovy script for debugging:
154

155
```java
156
SimpleTemplateEngine engine = new SimpleTemplateEngine(true);
157
// or
158
engine.setVerbose(true);
159

160
// When creating templates, the generated script will be printed to System.out
161
Template template = engine.createTemplate(templateText);
162
```
163

164
#### Backslash Escaping
165
Enable backslash escaping for compatibility with templates containing backslashes:
166

167
```java
168
SimpleTemplateEngine engine = new SimpleTemplateEngine();
169
engine.setEscapeBackslash(true);
170

171
// Now backslashes in templates will be properly escaped
172
String template = "Path: C:\\Users\\$username\\Documents";
173
```
174

175
### Web Integration
176

177
SimpleTemplateEngine can be used with servlet containers by configuring TemplateServlet:
178

179
```xml
180
<servlet>
181
  <servlet-name>SimpleTemplate</servlet-name>
182
  <servlet-class>groovy.servlet.TemplateServlet</servlet-class>
183
  <init-param>
184
    <param-name>template.engine</param-name>
185
    <param-value>groovy.text.SimpleTemplateEngine</param-value>
186
  </init-param>
187
</servlet>
188
```
189

190
### Error Handling
191

192
SimpleTemplateEngine provides basic error handling through standard Groovy exceptions:
193

194
```java
195
try {
196
    Template template = engine.createTemplate(templateText);
197
    String result = template.make(binding).toString();
198
} catch (CompilationFailedException e) {
199
    // Template compilation failed - syntax error in template
200
    System.err.println("Template compilation error: " + e.getMessage());
201
} catch (IOException e) {
202
    // File I/O error when reading template from file/URL
203
    System.err.println("I/O error: " + e.getMessage());
204
} catch (ClassNotFoundException e) {
205
    // Missing class dependencies
206
    System.err.println("Class not found: " + e.getMessage());
207
}
208
```