The first parameter of block helpers (documentation)

[ept]

I'm currently struggling to see the purpose of the first parameter of block helper functions (context). Could you explain how it differs from this?

A brief look at the code suggests that what a block helper calls this is actually called context or wrappedContext internally, and what a block helper calls context is called proxy internally. (In the addBlock and handleBlock methods.) Beyond that I find it gets a bit involved. A few experiments suggest that they behave quite similarly, with subtle differences (e.g. issue #11 doesn't occur with this replaced by context).

Moreover, the README suggests that:

Whenever the block helper is called it is given a single parameter, the compiled contents of the block.

...which is not the case, unless I misunderstand the sentence. Should that be more something like:

Whenever the block helper is called it is given two parameters: a context (which differs from this as follows: ...) and the precompiled contents of the block.

Hope you could shed some light on the intentions behind this vs. context. Thanks!

[nalanj]

Hey, good catch in the docs. Yehuda and I changed things right before announcing handlebars and didn't update the docs correctly, it seems.

The first parameter is the context that is handled to the block (it's the parameter for helpers used with expressions as well). So, for example, if you had a helper named link:

function link(context, fn) {
   return "<a href=\"context.url\">" + fn(context) + "</a>";
}

And data like:

{folks:[
    {name: "Alan", website: {url: "http://www.commondream.net"}}, 
    {name: "Yehuda", website: {url: "http://yehudakatz.com"}}
]}

You could then use it in a template as:

{{#folks}}
  {{#link website}}{{name}}{{/link}}
{{/folks}}

[ept]

Ok, that makes sense — thanks. I see you updated the Readme to say that the context parameter is null when none is passed in the template; however, the current behaviour seems to be that actually the hash at the current context is passed (like this but without the __get__ method). What's the intended behaviour?

[nalanj]

I just updated the docs. I was working from memory when I answered you and I remembered it wrong. So if no argument is given the current context will be passed as the first argument (basically equivalent to passing . as the argument).

[ept]

Ok, that is clear. Thanks very much! :)