how to pass parameters to Handlebars helper? What's the difference between options.hash & options.data

Question

Here's a typical Handlebars helper:

Ember.Handlebars.helper 'myHelper', (value, options) ->
  ...

According to this protip you can pass hash to Handlebars helpers. I looked over the source and found out that it provides both options.hash and options.data. I'm a bit confused as this wouldn't work as expected:

{{#with controllers.currentCardCategory}}
  {{#each property in cardProperties}}
    <td class="td">{{cardProperty this property=property.symbol}}</td> 
  {{/each}}
{{/with}}

this is the current Card record. Here I got property.symbol as string

But this worked:

{{#with controllers.currentCardCategory}}
  {{#each property in cardProperties}}
    <td class="td">{{cardProperty this property.symbol}}</td> 
  {{/each}}
{{/with}}

and the value was accessible via options.

But now I can't do this:

{{#with controllers.currentCardCategory}}
  {{#each property in cardProperties}}
    <td class="td">{{cardProperty this property.symbol anotherParam yetAnotherParam}}</td> 
  {{/each}}
{{/with}}

My question is: how to pass other parameters to the helper and what's the difference between options.hash and options.data in the helper?

Solution

Parameters passed to a helper become arguments to the helper function. The values you provide in the template immediately after the {{helperName become the arguments. The last argument passed to the helper is an options object that provides additional information to helper like, an options.hash and options.contexts, etc. Key value pairs provided after the parameters correspond to the options.hash property.

For a hello helper that takes 3 arguments, the helper would be,

Ember.Handlebars.helper('hello', function(a, b, c, options) {
  return '%@ - %@ - %@'.fmt(a, b, c);
});

The hello helper can be used in a template like so,

{{hello lorem ipsum dolor}}

Here the values of lorem, ipsum, and dolor properties would be used and returned as a combined string.

In addition to the required arguments, if you pass in additonal parameters they would be available in options.hash. These properties are treated as strings and aren't resolved by default. You would need to use, options.data.view to lookup their values first. See this answer for an example if you need to do this.

Finally options.data is special property provided to helpers. It's the raw handlebars Frame that holds variables, contexts and so on. It is mostly for use with block helpers. Since block helpers don't do rendering themselves but call other helpers, options.data allows such block helpers to inject additional variables into the child helpers frame. For details see the docs here.

Here's a jsbin example.