Package com.github.jknack.handlebars

Class Handlebars

  • All Implemented Interfaces:
    HelperRegistry
    public class Handlebars
extends java.lang.Object
implements HelperRegistry

    Handlebars provides the power necessary to let you build semantic templates effectively with no frustration.

    Getting Started:

     Handlebars handlebars = new Handlebars();
 Template template = handlebars.compileInline("Hello {{this}}!");
 System.out.println(template.apply("Handlebars.java"));

    Loading templates

    Templates are loaded using the ```TemplateLoader``` class. Handlebars.java provides three implementations of a ```TemplateLoader```:
    • ClassPathTemplateLoader (default)
    • FileTemplateLoader
    • SpringTemplateLoader (available at the handlebars-springmvc module)

    This example load mytemplate.hbs from the root of the classpath: 

     Handlebars handlebars = new Handlebars();

 Template template = handlebars.compileInline(URI.create("mytemplate"));

 System.out.println(template.apply("Handlebars.java"));

    You can specify a different ```TemplateLoader``` by: 

     TemplateLoader loader = ...;
 Handlebars handlebars = new Handlebars(loader);
    Since:
    0.1.0

    • Field Detail

      • DELIM_START

        public static final java.lang.String DELIM_START
        The default start delimiter.
        See Also:
        Constant Field Values

      • DELIM_END

        public static final java.lang.String DELIM_END
        The default end delimiter.
        See Also:
        Constant Field Values

    • Method Detail

      • precompile

        public java.lang.String precompile​(java.lang.String path)
        Precompile a template to JavaScript.
        Parameters:
        path - Template path.
        Returns:
        JavaScript.

      • precompileInline

        public java.lang.String precompileInline​(java.lang.String template)
        Precompile a template to JavaScript.
        Parameters:
        template - Template.
        Returns:
        JavaScript.

      • compile

        public Template compile​(java.lang.String location)
                 throws java.io.IOException
        Compile the resource located at the given uri. The implementation uses a cache for previously compiled Templates. By default, if the resource has been compiled previously, and no changes have occurred since in the resource, compilation will be skipped and the previously created Template will be returned. You can set an alternate cache implementation using with.
        Parameters:
        location - The resource's location. Required.
        Returns:
        A compiled template.
        Throws:
        java.io.IOException - If the resource cannot be loaded.

      • compile

        public Template compile​(java.lang.String location,
                        java.lang.String startDelimiter,
                        java.lang.String endDelimiter)
                 throws java.io.IOException
        Compile the resource located at the given uri. The implementation uses a cache for previously compiled Templates. By default, if the resource has been compiled previously, and no changes have occurred since in the resource, compilation will be skipped and the previously created Template will be returned. You can set an alternate cache implementation using with.
        Parameters:
        location - The resource's location. Required.
        startDelimiter - The start delimiter. Required.
        endDelimiter - The end delimiter. Required.
        Returns:
        A compiled template.
        Throws:
        java.io.IOException - If the resource cannot be loaded.

      • compileInline

        public Template compileInline​(java.lang.String input)
                       throws java.io.IOException
        Compile a handlebars template. The implementation uses a cache for previously compiled Templates. By default, if same input string has been compiled previously, compilation will be skipped and the previously created Template will be returned. You can set an alternate cache implementation using with.
        Parameters:
        input - The handlebars input. Required.
        Returns:
        A compiled template.
        Throws:
        java.io.IOException - If the resource cannot be loaded.

      • compileInline

        public Template compileInline​(java.lang.String input,
                              java.lang.String startDelimiter,
                              java.lang.String endDelimiter)
                       throws java.io.IOException
        Compile a handlebars template. The implementation uses a cache for previously compiled Templates. By default, if same input string has been compiled previously, compilation will be skipped and the previously created Template will be returned. You can set an alternate cache implementation using with.
        Parameters:
        input - The input text. Required.
        startDelimiter - The start delimiter. Required.
        endDelimiter - The end delimiter. Required.
        Returns:
        A compiled template.
        Throws:
        java.io.IOException - If the resource cannot be loaded.

      • compile

        public Template compile​(TemplateSource source)
                 throws java.io.IOException
        Compile a handlebars template. The implementation uses a cache for previously compiled Templates. By default, if the resource has been compiled previously, and no changes have occurred since in the resource, compilation will be skipped and the previously created Template will be returned. You can set an alternate cache implementation using with.
        Parameters:
        source - The template source. Required.
        Returns:
        A handlebars template.
        Throws:
        java.io.IOException - If the resource cannot be loaded.

      • compile

        public Template compile​(TemplateSource source,
                        java.lang.String startDelimiter,
                        java.lang.String endDelimiter)
                 throws java.io.IOException
        Compile a handlebars template. The implementation uses a cache for previously compiled Templates. By default, if the resource has been compiled previously, and no changes have occurred since in the resource, compilation will be skipped and the previously created Template will be returned. You can set an alternate cache implementation using with.
        Parameters:
        source - The template source. Required.
        startDelimiter - The start delimiter. Required.
        endDelimiter - The end delimiter. Required.
        Returns:
        A handlebars template.
        Throws:
        java.io.IOException - If the resource cannot be loaded.

      • helper

        public <C> Helper<C> helper​(java.lang.String name)
        Find a helper by name.
        Specified by:
        helper in interface HelperRegistry
        Type Parameters:
        C - The helper runtime type.
        Parameters:
        name - The helper's name. Required.
        Returns:
        A helper or null if it's not found.

      • registerHelper

        public <H> Handlebars registerHelper​(java.lang.String name,
                                     Helper<H> helper)
        Register a helper in the helper registry.
        Specified by:
        registerHelper in interface HelperRegistry
        Type Parameters:
        H - The helper runtime type.
        Parameters:
        name - The helper's name. Required.
        helper - The helper object. Required.
        Returns:
        This handlebars.

      • registerHelperMissing

        public <H> Handlebars registerHelperMissing​(Helper<H> helper)
        Register a missing helper in the helper registry.
        Specified by:
        registerHelperMissing in interface HelperRegistry
        Type Parameters:
        H - The helper runtime type.
        Parameters:
        helper - The helper object. Required.
        Returns:
        This handlebars.

      • registerHelpers

        public Handlebars registerHelpers​(java.lang.Object helperSource)

        Register all the helper methods for the given helper source.

        A helper method looks like: 

         public static? CharSequence methodName(context?, parameter*, options?) {
 }
        Where:
        • A method can/can't be static
        • The method's name became the helper's name
        • Context, parameters and options are all optional
        • If context and options are present they must be the first and last method arguments.
        Instance and static methods will be registered as helpers.
        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        helperSource - The helper source. Required.
        Returns:
        This handlebars object.

      • registerHelpers

        public Handlebars registerHelpers​(java.lang.Class<?> helperSource)

        Register all the helper methods for the given helper source.

        A helper method looks like: 

         public static? CharSequence methodName(context?, parameter*, options?) {
 }
        Where:
        • A method can/can't be static
        • The method's name became the helper's name
        • Context, parameters and options are all optional
        • If context and options are present they must be the first and last method arguments.
        Only static methods will be registered as helpers.

        Enums are supported too

        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        helperSource - The helper source. Enums are supported. Required.
        Returns:
        This handlebars object.

      • registerHelpers

        public Handlebars registerHelpers​(java.net.URI location)
                           throws java.lang.Exception

        Register helpers from a JavaScript source.

        A JavaScript source file looks like: 

          Handlebars.registerHelper('hey', function (context) {
    return 'Hi ' + context.name;
  });
  ...
  Handlebars.registerHelper('hey', function (context, options) {
    return 'Hi ' + context.name + options.hash['x'];
  });
  ...
  Handlebars.registerHelper('hey', function (context, p1, p2, options) {
    return 'Hi ' + context.name + p1 + p2 + options.hash['x'];
  });
  ...
        To keep your helpers reusable between server and client avoid DOM manipulation.
        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        location - A classpath location. Required.
        Returns:
        This handlebars object.
        Throws:
        java.lang.Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(java.io.File input)
                           throws java.lang.Exception

        Register helpers from a JavaScript source.

        A JavaScript source file looks like: 

          Handlebars.registerHelper('hey', function (context) {
    return 'Hi ' + context.name;
  });
  ...
  Handlebars.registerHelper('hey', function (context, options) {
    return 'Hi ' + context.name + options.hash['x'];
  });
  ...
  Handlebars.registerHelper('hey', function (context, p1, p2, options) {
    return 'Hi ' + context.name + p1 + p2 + options.hash['x'];
  });
  ...
        To keep your helpers reusable between server and client avoid DOM manipulation.
        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        input - A JavaScript file name. Required.
        Returns:
        This handlebars object.
        Throws:
        java.lang.Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(java.lang.String filename,
                                  java.io.Reader source)
                           throws java.lang.Exception

        Register helpers from a JavaScript source.

        A JavaScript source file looks like: 

          Handlebars.registerHelper('hey', function (context) {
    return 'Hi ' + context.name;
  });
  ...
  Handlebars.registerHelper('hey', function (context, options) {
    return 'Hi ' + context.name + options.hash['x'];
  });
  ...
  Handlebars.registerHelper('hey', function (context, p1, p2, options) {
    return 'Hi ' + context.name + p1 + p2 + options.hash['x'];
  });
  ...
        To keep your helpers reusable between server and client avoid DOM manipulation.
        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        filename - The file name (just for debugging purpose). Required.
        source - The JavaScript source. Required.
        Returns:
        This handlebars object.
        Throws:
        java.lang.Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(java.lang.String filename,
                                  java.io.InputStream source)
                           throws java.lang.Exception

        Register helpers from a JavaScript source.

        A JavaScript source file looks like: 

          Handlebars.registerHelper('hey', function (context) {
    return 'Hi ' + context.name;
  });
  ...
  Handlebars.registerHelper('hey', function (context, options) {
    return 'Hi ' + context.name + options.hash['x'];
  });
  ...
  Handlebars.registerHelper('hey', function (context, p1, p2, options) {
    return 'Hi ' + context.name + p1 + p2 + options.hash['x'];
  });
  ...
        To keep your helpers reusable between server and client avoid DOM manipulation.
        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        filename - The file name (just for debugging purpose). Required.
        source - The JavaScript source. Required.
        Returns:
        This handlebars object.
        Throws:
        java.lang.Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(java.lang.String filename,
                                  java.lang.String source)
                           throws java.io.IOException

        Register helpers from a JavaScript source.

        A JavaScript source file looks like: 

          Handlebars.registerHelper('hey', function (context) {
    return 'Hi ' + context.name;
  });
  ...
  Handlebars.registerHelper('hey', function (context, options) {
    return 'Hi ' + context.name + options.hash['x'];
  });
  ...
  Handlebars.registerHelper('hey', function (context, p1, p2, options) {
    return 'Hi ' + context.name + p1 + p2 + options.hash['x'];
  });
  ...
        To keep your helpers reusable between server and client avoid DOM manipulation.
        Specified by:
        registerHelpers in interface HelperRegistry
        Parameters:
        filename - The file name (just for debugging purpose). Required.
        source - The JavaScript source. Required.
        Returns:
        This handlebars object.
        Throws:
        java.io.IOException - If the JavaScript helpers can't be registered.

      • helpers

        public java.util.Set<java.util.Map.Entry<java.lang.String,​Helper<?>>> helpers()
        Description copied from interface: HelperRegistry
        List all the helpers from registry.
        Specified by:
        helpers in interface HelperRegistry
        Returns:
        Available helpers in the registry.

      • getLoader

        public TemplateLoader getLoader()
        The resource locator.
        Returns:
        The resource locator.

      • getCache

        public TemplateCache getCache()
        The template cache.
        Returns:
        The template cache.

      • getEscapingStrategy

        public EscapingStrategy getEscapingStrategy()
        The escaping strategy.
        Returns:
        The escaping strategy.

      • stringParams

        public boolean stringParams()
        If true, missing helper parameters will be resolve to their names.
        Returns:
        If true, missing helper parameters will be resolve to their names.

      • prettyPrint

        public boolean prettyPrint()
        If true, unnecessary spaces and new lines will be removed from output. Default is: false.
        Returns:
        If true, unnecessary spaces and new lines will be removed from output. Default is: false.

      • setPrettyPrint

        public void setPrettyPrint​(boolean prettyPrint)
        If true, unnecessary spaces and new lines will be removed from output. Default is: false.
        Parameters:
        prettyPrint - If true, unnecessary spaces and new lines will be removed from output. Default is: false.

      • prettyPrint

        public Handlebars prettyPrint​(boolean prettyPrint)
        If true, unnecessary spaces and new lines will be removed from output. Default is: false.
        Parameters:
        prettyPrint - If true, unnecessary spaces and new lines will be removed from output. Default is: false.
        Returns:
        This handlebars object.

      • setStringParams

        public void setStringParams​(boolean stringParams)
        If true, missing helper parameters will be resolve to their names.
        Parameters:
        stringParams - If true, missing helper parameters will be resolve to their names.

      • stringParams

        public Handlebars stringParams​(boolean stringParams)
        If true, missing helper parameters will be resolve to their names.
        Parameters:
        stringParams - If true, missing helper parameters will be resolve to their names.
        Returns:
        The handlebars object.

      • infiniteLoops

        public boolean infiniteLoops()
        If true, templates will be able to call him self directly or indirectly. Use with caution. Default is: false.
        Returns:
        If true, templates will be able to call him self directly or indirectly. Use with caution. Default is: false.

      • setInfiniteLoops

        public void setInfiniteLoops​(boolean infiniteLoops)
        If true, templates will be able to call him self directly or indirectly. Use with caution. Default is: false.
        Parameters:
        infiniteLoops - If true, templates will be able to call him self directly or indirectly.

      • infiniteLoops

        public Handlebars infiniteLoops​(boolean infiniteLoops)
        If true, templates will be able to call him self directly or indirectly. Use with caution. Default is: false.
        Parameters:
        infiniteLoops - If true, templates will be able to call him self directly or indirectly.
        Returns:
        The handlebars object.

      • deletePartialAfterMerge

        public boolean deletePartialAfterMerge()
        If true, templates will be deleted once applied. Useful, in some advanced template inheritance use cases. Used by {{#block}} helper. Default is: false. At any time you can override the default setup with: 
         {{#block "footer" delete-after-merge=true}}
        Returns:
        True for clearing up templates once they got applied. Used by {{#block}} helper.

      • deletePartialAfterMerge

        public Handlebars deletePartialAfterMerge​(boolean deletePartialAfterMerge)
        If true, templates will be deleted once applied. Useful, in some advanced template inheritance use cases. Used by {{#block}} helper. Default is: false. At any time you can override the default setup with: 
         {{#block "footer" delete-after-merge=true}}
        Parameters:
        deletePartialAfterMerge - True for clearing up templates once they got applied. Used by {{#block}} helper.
        Returns:
        This handlebars object.

      • setDeletePartialAfterMerge

        public void setDeletePartialAfterMerge​(boolean deletePartialAfterMerge)
        If true, templates will be deleted once applied. Useful, in some advanced template inheritance use cases. Used by {{#block}} helper. Default is: false. At any time you can override the default setup with: 
         {{#block "footer" delete-after-merge=true}}
        Parameters:
        deletePartialAfterMerge - True for clearing up templates once they got applied. Used by {{#block}} helper.

      • setEndDelimiter

        public void setEndDelimiter​(java.lang.String endDelimiter)
        Set the end delimiter.
        Parameters:
        endDelimiter - The end delimiter. Required.

      • endDelimiter

        public Handlebars endDelimiter​(java.lang.String endDelimiter)
        Set the end delimiter.
        Parameters:
        endDelimiter - The end delimiter. Required.
        Returns:
        This handlebars object.

      • getEndDelimiter

        public java.lang.String getEndDelimiter()
        The End Delimiter.
        Returns:
        The End Delimiter.

      • setStartDelimiter

        public void setStartDelimiter​(java.lang.String startDelimiter)
        Set the start delimiter.
        Parameters:
        startDelimiter - The start delimiter. Required.

      • startDelimiter

        public Handlebars startDelimiter​(java.lang.String startDelimiter)
        Set the start delimiter.
        Parameters:
        startDelimiter - The start delimiter. Required.
        Returns:
        This handlebars object.

      • getStartDelimiter

        public java.lang.String getStartDelimiter()
        The Start Delimiter.
        Returns:
        The Start Delimiter.

      • with

        public Handlebars with​(HelperRegistry registry)
        Set the helper registry. This operation will override will remove any previously registered helper.
        Parameters:
        registry - The helper registry. Required.
        Returns:
        This handlebars object.

      • getFormatter

        public Formatter.Chain getFormatter()
        Returns:
        A formatter chain.

      • with

        public Handlebars with​(Formatter formatter)
        Add a new variable formatter. 
        
 Handlebars hbs = new Handlebars();

 hbs.with(new Formatter() {
   public Object format(Object value, Chain next) {
    if (value instanceof Date) {
      return ((Date) value).getTime();
    }
    return next.format(value);
   }
 });
        Parameters:
        formatter - A formatter.
        Returns:
        This handlebars object.

      • handlebarsJsFile

        public Handlebars handlebarsJsFile​(java.lang.String location)
        Set the handlebars.js location used it to compile/precompile template to JavaScript.

        Using handlebars.js 4.x: 

           Handlebars handlebars = new Handlebars()
      .handlebarsJsFile("handlebars-v4.0.4.js");

        Using handlebars.js 1.x: 

           Handlebars handlebars = new Handlebars()
      .handlebarsJsFile("handlebars-v1.3.0.js");
        Default handlebars.js is handlebars-v4.0.4.js.
        Parameters:
        location - A classpath location of the handlebar.js file.
        Returns:
        This instance of Handlebars.

      • handlebarsJsFile

        public java.lang.String handlebarsJsFile()
        Returns:
        Classpath location of the handlebars.js file. Default is: handlebars-v4.0.4.js

      • parentScopeResolution

        public boolean parentScopeResolution()
        Returns:
        True, if we want to extend lookup to parent scope, like Mustache Spec. Or false, if lookup is restricted to current scope, like handlebars.js.

      • setParentScopeResolution

        public void setParentScopeResolution​(boolean parentScopeResolution)
        Given: 
         {
   "value": "Brett",
   "child": {
      "bestQB" : "Favre"
    }
 }
        Handlebars.java will output: Hello Favre Brett while handlebars.js: Hello Favre. Why? Handlebars.java is a 100% Mustache implementation while handlebars.js isn't. This option forces Handlebars.java mimics handlebars.js behavior: 
         Handlebars hbs = new Handlebars()
   .parentScopeResolution(true);
        Outputs: Hello Favre.
        Parameters:
        parentScopeResolution - False, if we want to restrict lookup to current scope (like in handlebars.js). Default is true

      • parentScopeResolution

        public Handlebars parentScopeResolution​(boolean parentScopeResolution)
        Given: 
         {
   "value": "Brett",
   "child": {
      "bestQB" : "Favre"
    }
 }
        Handlebars.java will output: Hello Favre Brett while handlebars.js: Hello Favre. Why? Handlebars.java is a 100% Mustache implementation while handlebars.js isn't. This option forces Handlebars.java mimics handlebars.js behavior: 
         Handlebars hbs = new Handlebars()
   .parentScopeResolution(true);
        Outputs: Hello Favre.
        Parameters:
        parentScopeResolution - False, if we want to restrict lookup to current scope (like in handlebars.js). Default is true
        Returns:
        This handlebars.

      • preEvaluatePartialBlocks

        public boolean preEvaluatePartialBlocks()
        If true, partial blocks will implicitly be evaluated before the partials will actually be executed. If false, you need to explicitly evaluate and render partial blocks with 
        
     {{> @partial-block}}
        Attention: If this is set to true, Handlebars works *much* slower! while rendering partial blocks. Default is: true for compatibility reasons.
        Returns:
        If true partial blocks will be evaluated before the partial will be rendered to allow inline block side effects. If false, you will have to evaluate and render partial blocks explitly (this option is *much* faster).

      • setPreEvaluatePartialBlocks

        public void setPreEvaluatePartialBlocks​(boolean preEvaluatePartialBlocks)
        If true, partial blocks will implicitly be evaluated before the partials will actually be executed. If false, you need to explicitly evaluate and render partial blocks with 
        
     {{> @partial-block}}
        Attention: If this is set to true, Handlebars works *much* slower! while rendering partial blocks. Default is: true for compatibility reasons.
        Parameters:
        preEvaluatePartialBlocks - If true partial blocks will be evaluated before the partial will be rendered to allow inline block side effects. If false, you will have to evaluate and render partial blocks explitly (this option is *much* faster).

      • preEvaluatePartialBlocks

        public Handlebars preEvaluatePartialBlocks​(boolean preEvaluatePartialBlocks)
        If true, partial blocks will implicitly be evaluated before the partials will actually be executed. If false, you need to explicitly evaluate and render partial blocks with 
        
     {{> @partial-block}}
        Attention: If this is set to true, Handlebars works *much* slower! while rendering partial blocks. Default is: true for compatibility reasons.
        Parameters:
        preEvaluatePartialBlocks - If true partial blocks will be evaluated before the partial will be rendered to allow inline block side effects. If false, you will have to evaluate and render partial blocks explitly (this option is *much* faster).
        Returns:
        The Handlebars object

      • getParserFactory

        public ParserFactory getParserFactory()
        Return a parser factory.
        Returns:
        A parser factory.

      • log

        public static void log​(java.lang.String message,
                       java.lang.Object... args)
        Log the given message and format the message within the args.
        Parameters:
        message - The log's message.
        args - The optional args.
        See Also:
        String.format(String, Object...)

      • log

        public static void log​(java.lang.String message)
        Log the given message and format the message within the args.
        Parameters:
        message - The log's message.
        See Also:
        String.format(String, Object...)

      • warn

        public static void warn​(java.lang.String message,
                        java.lang.Object... args)
        Log the given message as warn and format the message within the args.
        Parameters:
        message - The log's message.
        args - The optional args.
        See Also:
        String.format(String, Object...)

      • warn

        public static void warn​(java.lang.String message)
        Log the given message as warn and format the message within the args.
        Parameters:
        message - The log's message.
        See Also:
        String.format(String, Object...)

      • debug

        public static void debug​(java.lang.String message,
                         java.lang.Object... args)
        Log the given message as debug and format the message within the args.
        Parameters:
        message - The log's message.
        args - The optional args.
        See Also:
        String.format(String, Object...)

      • debug

        public static void debug​(java.lang.String message)
        Log the given message as debug and format the message within the args.
        Parameters:
        message - The log's message.
        See Also:
        String.format(String, Object...)

      • error

        public static void error​(java.lang.String message,
                         java.lang.Object... args)
        Log the given message as error and format the message within the args.
        Parameters:
        message - The log's message.
        args - The optional args.
        See Also:
        String.format(String, Object...)

      • error

        public static void error​(java.lang.String message)
        Log the given message as error and format the message within the args.
        Parameters:
        message - The log's message.
        See Also:
        String.format(String, Object...)

      • decorator

        public Decorator decorator​(java.lang.String name)
        Description copied from interface: HelperRegistry
        Find a decorator by name.
        Specified by:
        decorator in interface HelperRegistry
        Parameters:
        name - A decorator's name.
        Returns:
        A decorator or null.

      • setCharset

        public Handlebars setCharset​(java.nio.charset.Charset charset)
        Description copied from interface: HelperRegistry
        Set the charset to use.
        Specified by:
        setCharset in interface HelperRegistry
        Parameters:
        charset - Charset.
        Returns:
        This registry.

      • getCharset

        public java.nio.charset.Charset getCharset()
        Returns:
        Charset.