Package com.github.jknack.handlebars

Class Handlebars

  • All Implemented Interfaces:
    HelperRegistry
    public class Handlebars
extends 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 ```TemplateLodaer```:
    • 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

    • Method Detail

      • compile

        public Template compile​(String location)
                 throws IOException
        Compile the resource located at the given uri.
        Parameters:
        location - The resource's location. Required.
        Returns:
        A compiled template.
        Throws:
        IOException - If the resource cannot be loaded.

      • compile

        public Template compile​(String location,
                        String startDelimiter,
                        String endDelimiter)
                 throws IOException
        Compile the resource located at the given uri.
        Parameters:
        location - The resource's location. Required.
        startDelimiter - The start delimiter. Required.
        endDelimiter - The end delimiter. Required.
        Returns:
        A compiled template.
        Throws:
        IOException - If the resource cannot be loaded.

      • compileInline

        public Template compileInline​(String input)
                       throws IOException
        Compile a handlebars template.
        Parameters:
        input - The handlebars input. Required.
        Returns:
        A compiled template.
        Throws:
        IOException - If the resource cannot be loaded.

      • compileInline

        public Template compileInline​(String input,
                              String startDelimiter,
                              String endDelimiter)
                       throws IOException
        Compile a handlebars template.
        Parameters:
        input - The input text. Required.
        startDelimiter - The start delimiter. Required.
        endDelimiter - The end delimiter. Required.
        Returns:
        A compiled template.
        Throws:
        IOException - If the resource cannot be loaded.

      • compile

        public Template compile​(TemplateSource source)
                 throws IOException
        Compile a handlebars template.
        Parameters:
        source - The template source. Required.
        Returns:
        A handlebars template.
        Throws:
        IOException - If the resource cannot be loaded.

      • compile

        public Template compile​(TemplateSource source,
                        String startDelimiter,
                        String endDelimiter)
                 throws IOException
        Compile a handlebars template.
        Parameters:
        source - The template source. Required.
        startDelimiter - The start delimiter. Required.
        endDelimiter - The end delimiter. Required.
        Returns:
        A handlebars template.
        Throws:
        IOException - If the resource cannot be loaded.

      • helper

        public <C> Helper<C> helper​(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​(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​(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​(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​(URI location)
                           throws 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:
        Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(File input)
                           throws 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:
        Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(String filename,
                                  Reader source)
                           throws 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:
        Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(String filename,
                                  InputStream source)
                           throws 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:
        Exception - If the JavaScript helpers can't be registered.

      • registerHelpers

        public Handlebars registerHelpers​(String filename,
                                  String source)
                           throws 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:
        Exception - If the JavaScript helpers can't be registered.

      • 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​(String endDelimiter)
        Set the end delimiter.
        Parameters:
        endDelimiter - The end delimiter. Required.

      • endDelimiter

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

      • setStartDelimiter

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

      • startDelimiter

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

      • 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​(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 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.

      • getParserFactory

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

      • log

        public static void log​(String message,
                       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​(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​(String message,
                        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​(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​(String message,
                         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​(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​(String message,
                         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​(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...)