Package gg.jte

Class TemplateEngine

java.lang.Object

gg.jte.TemplateEngine

public final class TemplateEngine
extends Object

jte is a simple, yet powerful template engine for Java. All jte templates are compiled to Java class files, meaning jte adds essentially zero overhead to your application. jte is designed to introduce as few new keywords as possible and builds upon existing Java features, so that it is very easy to reason about what a template does. Read more at the official documentation at https://github.com/casid/jte/blob/master/DOCUMENTATION.md

Method Summary

Modifier and Type	Method	Description
void	cleanAll()	Cleans the directory containing the compiled template classes.
static TemplateEngine	create(CodeResolver codeResolver, ContentType contentType)	Creates a new template engine.
static TemplateEngine	create(CodeResolver codeResolver, Path classDirectory, ContentType contentType)	Creates a new template engine.
static TemplateEngine	createPrecompiled(Path classDirectory, ContentType contentType)	Creates a new template engine.
List<String>	getTemplatesUsing(String name)
int	precompileAll()	Compiles all templates located in the sources directory, to the compiled template classes directory.
int	precompileAll(List<String> compilePath)	Compiles all templates located in the sources directory, to the compiled template classes directory.
void	prepareForRendering(String name)	Prepares the template with the given name for rendering
void	render(String name, Object param, TemplateOutput output)	Renders the template with the given name.
void	render(String name, Map<String,Object> params, TemplateOutput output)	Renders the template with the given name.
void	renderLayout(String name, Map<String,Object> params, TemplateOutput output)	Renders a layout with the given name.
void	renderTag(String name, Map<String,Object> params, TemplateOutput output)	Renders a tag with the given name.
void	setHtmlAttributes(String... htmlAttributes)	Intercepts the given html attributes for configured htmlTags during template compilation and calls the configured htmlInterceptor during template rendering.
void	setHtmlInterceptor(HtmlInterceptor htmlInterceptor)	Interceptor that is called during template rendering when one of the configured htmlTags is rendered.
void	setHtmlPolicy(HtmlPolicy htmlPolicy)	Policy that checks the parsed HTML at compile time.
void	setHtmlTags(String... htmlTags)	Intercepts the given html tags during template compilation and calls the configured htmlInterceptor during template rendering.
void	setNullSafeTemplateCode(boolean value)	Experimental mode, that ignores any NullPointerException that occurs in template files.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static TemplateEngine create(CodeResolver codeResolver,
                                    ContentType contentType)

Creates a new template engine. All templates are compiled to Java class files on demand. A JDK is required. Every template has its own class loader. This is recommended when running templates on your developer machine.

Parameters:

codeResolver - to lookup jte templates

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

create

public static TemplateEngine create(CodeResolver codeResolver,
                                    Path classDirectory,
                                    ContentType contentType)

Creates a new template engine. All templates are compiled to Java class files on demand. A JDK is required. Every template has its own class loader. This is recommended when running templates on your developer machine.

Parameters:

codeResolver - to lookup jte templates

classDirectory - where template class files are compiled to

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

createPrecompiled

public static TemplateEngine createPrecompiled(Path classDirectory,
                                               ContentType contentType)

Creates a new template engine. All templates must have been precompiled to Java class files already. The template engine will load them from the specified classDirectory. No JDK is required. All templates share one class loader with each other. This is recommended when running templates in production. How to precompile templates: https://github.com/casid/jte/blob/master/DOCUMENTATION.md#precompiling-templates

Parameters:

classDirectory - where template class files are located

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

render

public void render(String name,
                   Object param,
                   TemplateOutput output)
            throws TemplateException

Renders the template with the given name. It is preferred to use this method, if all your templates have exactly one parameter.

Parameters:

name - the template name relative to the specified root directory, for instance "pages/welcome.jte".

param - the param passed to the template.

output - any implementation of TemplateOutput, where the template will be written to.

Throws:

TemplateException - in case the template failed to render, containing information where the error happened.

render

public void render(String name,
                   Map<String,Object> params,
                   TemplateOutput output)
            throws TemplateException

Renders the template with the given name. Parameters in the params map are mapped to the corresponding parameters in the template. Template parameters with a default value don't have to be provided in the map.

Parameters:

name - the template name relative to the specified root directory, for instance "pages/welcome.jte".

params - the parameters passed to the template as key value pairs.

output - any implementation of TemplateOutput, where the template will be written to.

Throws:

TemplateException - in case the template failed to render, containing information where the error happened.

renderTag

public void renderTag(String name,
                      Map<String,Object> params,
                      TemplateOutput output)
               throws TemplateException

Renders a tag with the given name. This comes at the cost of an extra method invocation and losing the type safety for params that jte usually provides. However, this is useful while migrating to jte. For instance, you can port a JSP tag to a jte tag and invoke the new jte tag from all other JSPs, so that there are no redundant implementations during the migration.

Parameters:

name - the template name relative to the specified root directory, for instance "tag/myTag.jte".

params - map of parameters that should be passed to the tag.

output - any implementation of TemplateOutput, where the template will be written to.

Throws:

TemplateException - in case the tag failed to render, containing information where the error happened.

renderLayout

public void renderLayout(String name,
                         Map<String,Object> params,
                         TemplateOutput output)
                  throws TemplateException

Renders a layout with the given name. This comes at the cost of an extra method invocation and losing the type safety for params that jte usually provides. However, this is useful while migrating to jte. For instance, you can port a JSP layout to a jte layout and invoke the new jte layout from all other JSPs, so that there are no redundant implementations during the migration.

Parameters:

name - the template name relative to the specified root directory, for instance "layout/myLayout.jte".

params - map of parameters that should be passed to the layout.

output - any implementation of TemplateOutput, where the template will be written to.

Throws:

TemplateException - in case the layout failed to render, containing information where the error happened.

getTemplatesUsing

public List<String> getTemplatesUsing(String name)

prepareForRendering

public void prepareForRendering(String name)

Prepares the template with the given name for rendering

Parameters:

name - the template name relative to the specified root directory, for instance "pages/welcome.jte".

cleanAll

public void cleanAll()

Cleans the directory containing the compiled template classes.

precompileAll

public int precompileAll()

Compiles all templates located in the sources directory, to the compiled template classes directory.

Returns:

amount of templates that were compiled

precompileAll

public int precompileAll(List<String> compilePath)

Compiles all templates located in the sources directory, to the compiled template classes directory.

Parameters:

compilePath - additional compile path arguments for the Java compiler.

Returns:

amount of templates that were compiled

setNullSafeTemplateCode

public void setNullSafeTemplateCode(boolean value)

Experimental mode, that ignores any NullPointerException that occurs in template files.

Parameters:

value - true, to enable

setHtmlPolicy

public void setHtmlPolicy(HtmlPolicy htmlPolicy)

Policy that checks the parsed HTML at compile time.

Parameters:

htmlPolicy - the policy

Throws:

NullPointerException - if policy is null

setHtmlTags

public void setHtmlTags(String... htmlTags)

Intercepts the given html tags during template compilation and calls the configured htmlInterceptor during template rendering.

Parameters:

htmlTags - tags to be intercepted, for instance setHtmlTags("form", "input");

setHtmlAttributes

public void setHtmlAttributes(String... htmlAttributes)

Intercepts the given html attributes for configured htmlTags during template compilation and calls the configured htmlInterceptor during template rendering.

Parameters:

htmlAttributes - attributes to be intercepted, for instance setHtmlAttributes("class");

setHtmlInterceptor

public void setHtmlInterceptor(HtmlInterceptor htmlInterceptor)

Interceptor that is called during template rendering when one of the configured htmlTags is rendered. This allows to integrate existing frameworks into jte.

Parameters:

htmlInterceptor - the interceptor