Update docs to specify need for explicit resolvers

[matthewpwatkins]

Hi. I just started using handlebars java yesterday. I could not get something simple like this to render:

var handlebars = new Handlebars.registerHelperMissing((context, options) -> {
  throw new RuntimeException(
    String.format("Unregistered helper name %s rendering %s.", options.helperName, options.fn.text()));
});

var myObj = new MyObject();
var myObj .setFirstName("Luke");
myObj .getRelationship().setName("father");

var template = handlebars.compileInline("{{ firstName }}, I am your {{ relationship.name }}.");
var res = template.apply(myObj);

Every time, it threw saying it couldn't find firstName. I tried using fluent named accessors, exposing the fields directly, etc but no change in the names or access would get it to work. I could get it working by passing in a map, but not a POJO.

After a lot of searching documentation where others said it should "just work" out of the box, I stumbled on a code sample of someone who was explicitly setting the resolvers of the context:

var context = Context.newBuilder(myObj)
  .resolvers(JavaBeanValueResolver.INSTANCE, FieldValueResolver.INSTANCE)
  .build();
var res = template.apply(context);

This works like a charm.

But why doesn't it work "out of the box?" Or can we update the docs to reflect that you need to specify the resolvers for java objects?

I'm using version 4.1.2.

[agentgt]

The default resolvers for using the builder can be seen here:

https://github.com/jknack/handlebars.java/blob/52edac903966f607bf3e949d73ae325292c07997/handlebars/src/main/java/com/github/jknack/handlebars/Context.java#L261

And its defined here:

https://github.com/jknack/handlebars.java/blob/52edac903966f607bf3e949d73ae325292c07997/handlebars/src/main/java/com/github/jknack/handlebars/ValueResolver.java#L37

What version of Java are you using (it should not matter since you are using 4.1.2 but I'm curious anyway)?

Anyway my guess is MyObject is either not public and or its getters are not public.

I highly recommend you do not use the FieldValueResolver if you plan on upgrading (unless of course you want to make your fields public).

One gotcha in 4.3.0 is if you upgrade Java you will get different behavior because:

  static List<ValueResolver> defaultValueResolvers() {
    if (Handlebars.Utils.javaVersion14) {
      return unmodifiableList(asList(MapValueResolver.INSTANCE,
          JavaBeanValueResolver.INSTANCE, MethodValueResolver.INSTANCE));
    }
    return unmodifiableList(asList(MapValueResolver.INSTANCE, JavaBeanValueResolver.INSTANCE));
  }

I'm hoping someday @jknack will take my PR #962 because I expect more and more folks to be even more confused with Value Resolver behavior changing on Java upgrade.

That is why in general right now I recommend you should set the Value Resolvers.