0
# Template Engine
1

2
The template engine provides a Groovy-based template processing system that allows complete customization of generated documentation appearance and structure. It processes templates with access to the full documentation model to generate HTML output.
3

4
## Core API
5

6
### GroovyDocTemplateEngine
7

8
The main template processing engine that applies templates to documentation model objects.
9

10
```java { .api }
11
public class GroovyDocTemplateEngine {
12
    // Simple constructor with single class template
13
    public GroovyDocTemplateEngine(GroovyDocTool tool, ResourceManager resourceManager, String classTemplate)
14
    
15
    // Full constructor with all template types
16
    public GroovyDocTemplateEngine(GroovyDocTool tool, ResourceManager resourceManager, 
17
                                  String[] docTemplates, String[] packageTemplates, 
18
                                  String[] classTemplates, Properties properties)
19
    
20
    // Template application methods  
21
    public String applyClassTemplates(GroovyClassDoc classDoc)                               // Apply class template
22
    public String applyPackageTemplate(String template, GroovyPackageDoc packageDoc)        // Apply package template  
23
    public String applyRootDocTemplate(String template, GroovyRootDoc rootDoc)             // Apply root doc template
24
    public void copyBinaryResource(String template, String destFileName)                   // Copy binary resources
25
}
26
```
27

28
### ResourceManager
29

30
Abstract interface for loading template resources from various sources.
31

32
```java { .api }
33
public interface ResourceManager {
34
    Reader getReader(String resourceName)    // Get reader for template resource
35
}
36
```
37

38
## Resource Manager Implementations
39

40
### FileSystemResourceManager
41

42
Loads templates from the file system.
43

44
```java { .api }
45
public class FileSystemResourceManager implements ResourceManager {
46
    public FileSystemResourceManager()                     // Default constructor (current directory)
47
    public FileSystemResourceManager(String basedir)      // Constructor with base directory
48
    public Reader getReader(String resourceName)          // Load from file system
49
}
50
```
51

52
### ClasspathResourceManager  
53

54
Loads templates from the classpath.
55

56
```java { .api }
57
public class ClasspathResourceManager implements ResourceManager {
58
    public ClasspathResourceManager()                           // Default constructor
59
    public ClasspathResourceManager(ClassLoader classLoader)   // Constructor with custom class loader
60
    public Reader getReader(String resourceName)               // Load from classpath
61
    public InputStream getInputStream(String resourceName)      // Get input stream for resource
62
}
63
```
64

65
## Template Configuration
66

67
### GroovyDocTemplateInfo
68

69
Provides default template configurations and constants.
70

71
```java { .api }
72
public class GroovyDocTemplateInfo {
73
    // Default template arrays
74
    public static final String[] DEFAULT_DOC_TEMPLATES         // Default top-level templates
75
    public static final String[] DEFAULT_PACKAGE_TEMPLATES     // Default package templates
76
    public static final String[] DEFAULT_CLASS_TEMPLATES       // Default class templates
77
}
78
```
79

80
The default templates include:
81
- **Doc Templates**: `overview-frame.html`, `allclasses-frame.html`, `overview-summary.html`, `help-doc.html`, `index.html`, `package-list`, `stylesheet.css`
82
- **Package Templates**: `package-frame.html`, `package-summary.html`  
83
- **Class Templates**: `class.html`
84

85
## Usage Examples
86

87
### Basic Template Engine Setup
88

89
```java
90
import org.codehaus.groovy.tools.groovydoc.*;
91
import org.codehaus.groovy.tools.groovydoc.gstringTemplates.GroovyDocTemplateInfo;
92

93
// Use default templates with file system resource manager
94
ResourceManager resourceManager = new FileSystemResourceManager("templates");
95
GroovyDocTemplateEngine engine = new GroovyDocTemplateEngine(
96
    tool,
97
    resourceManager,
98
    "class.html"  // Single class template
99
);
100

101
// Use default template configuration
102
GroovyDocTemplateEngine defaultEngine = new GroovyDocTemplateEngine(
103
    tool,
104
    new ClasspathResourceManager(),
105
    GroovyDocTemplateInfo.DEFAULT_DOC_TEMPLATES,
106
    GroovyDocTemplateInfo.DEFAULT_PACKAGE_TEMPLATES,
107
    GroovyDocTemplateInfo.DEFAULT_CLASS_TEMPLATES,
108
    new Properties()
109
);
110
```
111

112
### Custom Template Configuration
113

114
```java
115
import java.util.Properties;
116

117
// Set up custom templates
118
String[] docTemplates = {
119
    "custom-index.html",
120
    "custom-overview.html", 
121
    "custom-stylesheet.css"
122
};
123

124
String[] packageTemplates = {
125
    "custom-package-summary.html",
126
    "custom-package-frame.html"
127
};
128

129
String[] classTemplates = {
130
    "custom-class.html"
131
};
132

133
// Configure template properties
134
Properties templateProps = new Properties();
135
templateProps.setProperty("windowTitle", "My API Documentation");
136
templateProps.setProperty("docTitle", "My Project API");
137
templateProps.setProperty("header", "<b>My Project</b>");
138
templateProps.setProperty("footer", "<i>Copyright 2023</i>");
139
templateProps.setProperty("bottom", "Generated by GroovyDoc");
140

141
// Create resource manager for custom templates
142
ResourceManager resourceManager = new FileSystemResourceManager("src/main/templates");
143

144
// Create template engine with custom configuration
145
GroovyDocTemplateEngine engine = new GroovyDocTemplateEngine(
146
    tool,
147
    resourceManager,
148
    docTemplates,
149
    packageTemplates,
150
    classTemplates,
151
    templateProps
152
);
153
```
154

155
### Template Processing Examples
156

157
```java
158
import org.codehaus.groovy.groovydoc.*;
159

160
// Get documentation model objects
161
GroovyRootDoc rootDoc = tool.getRootDoc();
162
GroovyClassDoc[] classes = rootDoc.classes();
163
GroovyPackageDoc[] packages = rootDoc.specifiedPackages();
164

165
// Apply class template to generate HTML
166
for (GroovyClassDoc classDoc : classes) {
167
    String classHtml = engine.applyClassTemplates(classDoc);
168
    System.out.println("Generated HTML for " + classDoc.name());
169
    // classHtml contains the processed HTML for this class
170
}
171

172
// Apply package template
173
for (GroovyPackageDoc packageDoc : packages) {
174
    String packageHtml = engine.applyPackageTemplate("package-summary.html", packageDoc);
175
    System.out.println("Generated package HTML for " + packageDoc.name());
176
}
177

178
// Apply root documentation template
179
String indexHtml = engine.applyRootDocTemplate("index.html", rootDoc);
180
System.out.println("Generated index HTML");
181
```
182

183
### Working with Binary Resources
184

185
```java
186
// Copy binary resources (CSS, images, JavaScript) to output
187
engine.copyBinaryResource("stylesheet.css", "stylesheet.css");
188
engine.copyBinaryResource("images/logo.png", "images/logo.png");
189
engine.copyBinaryResource("scripts/doc.js", "scripts/doc.js");
190

191
// Resources are copied from the resource manager to the output location
192
```
193

194
### Template Development
195

196
Templates are Groovy templates that have access to the documentation model. Here's an example custom class template:
197

198
```html
199
<!-- custom-class.html template -->
200
<!DOCTYPE html>
201
<html>
202
<head>
203
    <title>${classDoc.qualifiedName()} - ${properties.windowTitle}</title>
204
    <link rel="stylesheet" type="text/css" href="../stylesheet.css">
205
</head>
206
<body>
207
    <h1>Class ${classDoc.name()}</h1>
208
    
209
    <% if (classDoc.commentText()) { %>
210
    <div class="description">
211
        ${classDoc.commentText()}
212
    </div>
213
    <% } %>
214
    
215
    <h2>Methods</h2>
216
    <% classDoc.methods().each { method -> %>
217
    <div class="method">
218
        <h3>${method.name()}${method.signature()}</h3>
219
        <% if (method.commentText()) { %>
220
        <p>${method.commentText()}</p>
221
        <% } %>
222
        
223
        <% if (method.parameters().length > 0) { %>
224
        <h4>Parameters:</h4>
225
        <ul>
226
        <% method.parameters().each { param -> %>
227
            <li><code>${param.name()}</code> (${param.type().typeName()}) 
228
            <% if (param.defaultValue()) { %>
229
                - default: ${param.defaultValue()}
230
            <% } %>
231
            </li>
232
        <% } %>
233
        </ul>
234
        <% } %>
235
        
236
        <% if (method.returnType().typeName() != 'void') { %>
237
        <h4>Returns:</h4>
238
        <p><code>${method.returnType().typeName()}</code></p>
239
        <% } %>
240
    </div>
241
    <% } %>
242
    
243
    <footer>${properties.footer}</footer>
244
</body>
245
</html>
246
```
247

248
### Advanced Template Engine Integration
249

250
```java
251
// Create a custom template engine workflow
252
public class CustomDocumentationGenerator {
253
    private final GroovyDocTool tool;
254
    private final GroovyDocTemplateEngine engine;
255
    private final OutputTool output;
256
    
257
    public CustomDocumentationGenerator(String[] sourcePaths, String templateDir, String outputDir) {
258
        this.tool = new GroovyDocTool(sourcePaths);
259
        this.output = new FileOutputTool();
260
        
261
        ResourceManager resourceManager = new FileSystemResourceManager(templateDir);
262
        this.engine = new GroovyDocTemplateEngine(
263
            tool, resourceManager,
264
            new String[]{"custom-index.html"},
265
            new String[]{"custom-package.html"}, 
266
            new String[]{"custom-class.html"},
267
            createProperties()
268
        );
269
    }
270
    
271
    public void generate(List<String> sourceFiles) {
272
        // Add source files
273
        tool.add(sourceFiles);
274
        
275
        // Generate using custom workflow
276
        GroovyRootDoc rootDoc = tool.getRootDoc();
277
        
278
        // Generate index
279
        String indexHtml = engine.applyRootDocTemplate("custom-index.html", rootDoc);
280
        output.writeToOutput("index.html", indexHtml, "UTF-8");
281
        
282
        // Generate package documentation
283
        for (GroovyPackageDoc pkg : rootDoc.specifiedPackages()) {
284
            String packageHtml = engine.applyPackageTemplate("custom-package.html", pkg);
285
            output.writeToOutput(pkg.name() + "/package.html", packageHtml, "UTF-8");
286
        }
287
        
288
        // Generate class documentation
289
        for (GroovyClassDoc classDoc : rootDoc.classes()) {
290
            String classHtml = engine.applyClassTemplates(classDoc);
291
            String fileName = classDoc.containingPackage().name().replace('.', '/') + 
292
                            "/" + classDoc.name() + ".html";
293
            output.writeToOutput(fileName, classHtml, "UTF-8");
294
        }
295
        
296
        // Copy resources
297
        engine.copyBinaryResource("custom-stylesheet.css", "stylesheet.css");
298
    }
299
    
300
    private Properties createProperties() {
301
        Properties props = new Properties();
302
        props.setProperty("windowTitle", "Custom API Docs");
303
        props.setProperty("docTitle", "API Documentation");
304
        return props;
305
    }
306
}
307

308
// Usage
309
CustomDocumentationGenerator generator = new CustomDocumentationGenerator(
310
    new String[]{"src/main/groovy"}, 
311
    "custom-templates",
312
    "build/custom-docs"
313
);
314
generator.generate(Arrays.asList("com/example/MyClass.groovy"));
315
```
316

317
## Template Variables
318

319
Templates have access to several variables and objects:
320

321
- **Documentation Objects**: `classDoc`, `packageDoc`, `rootDoc` depending on template type
322
- **Properties**: `properties` object containing configured properties
323
- **Utility Methods**: Various utility methods for formatting and navigation
324
- **Tool Reference**: Access to the `GroovyDocTool` instance for additional functionality
325

326
This template system provides complete flexibility for customizing the appearance and structure of generated documentation while maintaining access to the full documentation model.