Package org.jusecase.jte

Class 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 Detail

      • create

        public static TemplateEngine create​(CodeResolver codeResolver)
        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
        Returns:
        a fresh TemplateEngine instance

      • create

        public static TemplateEngine create​(CodeResolver codeResolver,
                                    Path classDirectory)
        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
        Returns:
        a fresh TemplateEngine instance

      • createPrecompiled

        public static TemplateEngine createPrecompiled​(Path classDirectory)
        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
        Returns:
        a fresh TemplateEngine instance

      • render

        public void render​(String name,
                   Object model,
                   TemplateOutput output)
            throws TemplateException
        Renders the template with the given name.
        Parameters:
        name - the template name relative to the specified root directory, for instance "pages/welcome.jte".
        model - the model instance 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.

      • 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 a dynamic 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,
                         Map<String,​String> layoutDefinitions,
                         TemplateOutput output)
                  throws TemplateException
        Renders a layout with the given name. This comes at the cost of a dynamic 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.
        layoutDefinitions - map of layout definitions 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.

      • 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 void precompileAll()
        Compiles all templates located in the sources directory, to the compiled template classes directory.

      • precompileAll

        public void 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.

      • setNullSafeTemplateCode

        public void setNullSafeTemplateCode​(boolean value)
        Experimental mode, that ignores any NullPointerException that occurs in template files.
        Parameters:
        value - true, to enable

      • setHtmlTags

        public void setHtmlTags​(String... htmlTags)
        Experimental mode, that intercepts the given html tags during template compilation and calls the configured htmlTagSupport during template rendering.
        Parameters:
        htmlTags - tags to be intercepted, for instance setHtmlTags("form", "input");

      • setHtmlAttributes

        public void setHtmlAttributes​(String... htmlAttributes)
        Experimental mode, that intercepts the given html attributes for configured htmlTags during template compilation and calls the configured htmlTagSupport during template rendering.
        Parameters:
        htmlAttributes - attributes to be intercepted, for instance setHtmlAttributes("class");

      • setHtmlTagSupport

        public void setHtmlTagSupport​(HtmlTagSupport htmlTagSupport)
        Experimental listener that is called during template rendering when one of the configured htmlTags is rendered. This allows to integrate existing frameworks into jte.
        Parameters:
        htmlTagSupport - the listener