Block Helper documentation / behavior confusing, inconsistent

[jmm]

Hello,

I'm finding the documentation / behavior of block helpers confusing. This is with 1.0.beta.6.

The README states that:

Whenever the block helper is called it is given two parameters, the argument that is passed to the helper, or the current context if no argument is passed and the compiled contents of the block.

But that doesn't seem to be the case.

If I have this...

{{#process}}I just want to process this content{{/process}}

...I get the options object as the first and only argument. Only if I have this do I get 2 arguments:

{{#process ugh}}I just want to process this content{{/process}}

This documentation (which I actually just discovered, because the links on the handlebarsjs.com index page are semi-invisible in Opera) seems to describe the actual behavior.

What is the intended behavior?

If there's always going to be an options argument, and the only other possible argument is a context object, would it not make more sense to have the helper signature be function ( options, context ) so that options will always be in the same position whether there's a context or not? That would make it easier to use the same method to process both of the above template fragments. Or, maybe just eliminate the context argument altogether and pass it as options.context?

What is this Hash Arguments documentation referring to when it mentions "accept[ing] a variable number of parameters" and "the complexity caused by positional arguments."? Is it intended to be able to do this?:

{{#process one two three}}I just want to process this content{{/process}}

helper = function ( one, two, three, options ) {};

I haven't noticed that in any of the examples, but when I try it, it works. In any case, if the options object is the one argument that will always be passed, would it not make sense to pass it as the first arg?

In that Hash Arguments documentation, I'm not sure it's helpful to show usage of an SC object that's not identified in the example or referred to anywhere else on the page. I assume that's part of SproutCore, but I only figured that out by doing a case-insensitive search of the page for "sc", which matched inside "underscore.js", which just happened to be next to a mention of SproutCore.

Another inconsistency in the helper documentation is that handlebarsjs.com says to call options.fn(), while the README says to call options(). I see that options is a function and options.fn is a reference to options, so I'm guessing options.fn() is what you're supposed to call now, and options is still a function for backward compatibility?

[wagenet]

Definitely seems like the README is wrong on this. I also know that much of the setup is for backwards compatibility with Mustache. So even if something is not ideal, Handlebars may be keeping it for that reason.

[jmm]

Thanks for your reply.

I also know that much of the setup is for backwards compatibility with Mustache. So even if something is not ideal, Handlebars may be keeping it for that reason.

Oh yeah, good point. I'm coming to Handlebars fresh, with no Mustache background, so I wasn't really thinking of that. But is there actually parity in this case? The README lists block helpers as one of the differences from Mustache, and I'll offer an example.

I'll use the example in the Mustache documentation. First of all, same deal here: there are 2 different versions of the documentation that show different helper implementations:

README:

Template:

{{#bold}}Hi {{name}}.{{/bold}}

View:

{
  "name": "Tater",
  "bold": function () {
    return function (text, render) {
      return "<b>" + render(text) + "</b>";
    }
  }
}

Mustache Manual:

Template

{{#wrapped}}
  {{name}} is awesome.
{{/wrapped}}

View:

{
  "name": "Willy",
  "wrapped": function() {
    return function(text) {
      return "<b>" + render(text) + "</b>"
    }
  }
}

In both cases, I have no idea what the point of the outer function that returns the actual helper function is. In the example from the manual, I don't know where render is coming from.

At any rate, using the example from the README, to achieve the same effect in Handlebars, don't you have to change the function as follows to achieve the same effect? (Not to mention, register it with Handlebars.registerHelper() instead of passing it in the view object.)

function ( render ) {

    return "<b>" + render( this ) + "</b>";

};