com.github.jknack.handlebars

Class Handlebars

java.lang.Object

com.github.jknack.handlebars.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

Author:

edgar.espina

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Handlebars.SafeString A Handlebars.SafeString tell Handlebars that the content should not be escaped as HTML.
static class	Handlebars.Utils Utilities function like: Handlebars.Utils.escapeExpression(CharSequence) and Handlebars.Utils.isEmpty(Object).

Field Summary

Fields

Modifier and Type	Field and Description
static String	DELIM_END The default end delimiter.
static String	DELIM_START The default start delimiter.

Fields inherited from interface com.github.jknack.handlebars.HelperRegistry

HELPER_MISSING

Constructor Summary

Constructors

Constructor and Description
Handlebars() Creates a new Handlebars with a ClassPathTemplateLoader and no cache.
Handlebars(TemplateLoader loader) Creates a new Handlebars with no cache.

Method Summary

Methods

Modifier and Type	Method and Description
Template	compile(String location) Compile the resource located at the given uri.
Template	compile(String location, String startDelimiter, String endDelimiter) Compile the resource located at the given uri.
Template	compile(TemplateSource source) Compile a handlebars template.
Template	compile(TemplateSource source, String startDelimiter, String endDelimiter) Compile a handlebars template.
Template	compileInline(String input) Compile a handlebars template.
Template	compileInline(String input, String startDelimiter, String endDelimiter) Compile a handlebars template.
static void	debug(String message) Log the given message as debug and format the message within the args.
static void	debug(String message, Object... args) Log the given message as debug and format the message within the args.
boolean	deletePartialAfterMerge() If true, templates will be deleted once applied.
Handlebars	deletePartialAfterMerge(boolean deletePartialAfterMerge) If true, templates will be deleted once applied.
Handlebars	endDelimiter(String endDelimiter) Set the end delimiter.
static void	error(String message) Log the given message as error and format the message within the args.
static void	error(String message, Object... args) Log the given message as error and format the message within the args.
TemplateCache	getCache() The template cache.
EscapingStrategy	getEscapingStrategy() The escaping strategy.
Formatter.Chain	getFormatter()
TemplateLoader	getLoader() The resource locator.
ParserFactory	getParserFactory() Return a parser factory.
String	handlebarsJsFile()
Handlebars	handlebarsJsFile(String location) Set the handlebars.js location used it to compile/precompile template to JavaScript.
<C> Helper<C>	helper(String name) Find a helper by name.
Set<Map.Entry<String,Helper<?>>>	helpers() List all the helpers from registry.
boolean	infiniteLoops() If true, templates will be able to call him self directly or indirectly.
Handlebars	infiniteLoops(boolean infiniteLoops) If true, templates will be able to call him self directly or indirectly.
static void	log(String message) Log the given message and format the message within the args.
static void	log(String message, Object... args) Log the given message and format the message within the args.
boolean	prettyPrint() If true, unnecessary spaces and new lines will be removed from output.
Handlebars	prettyPrint(boolean prettyPrint) If true, unnecessary spaces and new lines will be removed from output.
<H> Handlebars	registerHelper(String name, Helper<H> helper) Register a helper in the helper registry.
<H> Handlebars	registerHelperMissing(Helper<H> helper) Register a missing helper in the helper registry.
Handlebars	registerHelpers(Class<?> helperSource) Register all the helper methods for the given helper source.
Handlebars	registerHelpers(File input) Register helpers from a JavaScript source.
Handlebars	registerHelpers(Object helperSource) Register all the helper methods for the given helper source.
Handlebars	registerHelpers(String filename, InputStream source) Register helpers from a JavaScript source.
Handlebars	registerHelpers(String filename, Reader source) Register helpers from a JavaScript source.
Handlebars	registerHelpers(String filename, String source) Register helpers from a JavaScript source.
Handlebars	registerHelpers(URI location) Register helpers from a JavaScript source.
void	setDeletePartialAfterMerge(boolean deletePartialAfterMerge) If true, templates will be deleted once applied.
void	setEndDelimiter(String endDelimiter) Set the end delimiter.
void	setInfiniteLoops(boolean infiniteLoops) If true, templates will be able to call him self directly or indirectly.
void	setPrettyPrint(boolean prettyPrint) If true, unnecessary spaces and new lines will be removed from output.
void	setStartDelimiter(String startDelimiter) Set the start delimiter.
void	setStringParams(boolean stringParams) If true, missing helper parameters will be resolve to their names.
Handlebars	startDelimiter(String startDelimiter) Set the start delimiter.
boolean	stringParams() If true, missing helper parameters will be resolve to their names.
Handlebars	stringParams(boolean stringParams) If true, missing helper parameters will be resolve to their names.
static void	warn(String message) Log the given message as warn and format the message within the args.
static void	warn(String message, Object... args) Log the given message as warn and format the message within the args.
Handlebars	with(EscapingStrategy escapingStrategy) Set a new EscapingStrategy.
Handlebars	with(Formatter formatter) Add a new variable formatter.
Handlebars	with(HelperRegistry registry) Set the helper registry.
Handlebars	with(ParserFactory parserFactory) Set a new ParserFactory.
Handlebars	with(TemplateCache cache) Set a new TemplateCache.
Handlebars	with(TemplateLoader... loader) Set one or more TemplateLoader.

Methods inherited from class java.lang.Object

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

Field Detail

DELIM_START

public static final String DELIM_START

The default start delimiter.

See Also:

Constant Field Values

DELIM_END

public static final String DELIM_END

The default end delimiter.

See Also:

Constant Field Values

Constructor Detail

Handlebars

public Handlebars(TemplateLoader loader)

Creates a new Handlebars with no cache.

Parameters:

loader - The template loader. Required.

Handlebars

public Handlebars()

Creates a new Handlebars with a ClassPathTemplateLoader and no cache.

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.

helpers

public Set<Map.Entry<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(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(TemplateLoader... loader)

Set one or more TemplateLoader. In the case of two or more TemplateLoader, a CompositeTemplateLoader will be created. Default is: ClassPathTemplateLoader.

Parameters:

loader - The template loader. Required.

Returns:

This handlebars object.

See Also:

CompositeTemplateLoader

with

public Handlebars with(ParserFactory parserFactory)

Set a new ParserFactory.

Parameters:

parserFactory - A parser factory. Required.

Returns:

This handlebars object.

with

public Handlebars with(TemplateCache cache)

Set a new TemplateCache.

Parameters:

cache - The template cache. 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.

with

public Handlebars with(EscapingStrategy escapingStrategy)

Set a new EscapingStrategy.

Parameters:

escapingStrategy - The escaping strategy. 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 2.x:

   Handlebars handlebars = new Handlebars()
      .withHandlberasJs("handlebars-v2.0.0.js");
 

Using handlebars.js 1.x:

   Handlebars handlebars = new Handlebars()
      .withHandlberasJs("handlebars-v1.3.0.js");
 

Default handlebars.js is handlebars-v2.0.0.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-v1.3.0.js

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...)