Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Block Helper documentation / behavior confusing, inconsistent #231

Closed
jmm opened this Issue Apr 27, 2012 · 2 comments

Comments

Projects
None yet
2 participants

jmm commented Apr 27, 2012

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?

Collaborator

wagenet commented Apr 27, 2012

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 commented Apr 27, 2012

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>";

};

@kpdecker kpdecker closed this in 7fb9750 May 19, 2013

alejandroiglesias added a commit to alejandroiglesias/handlebars.js that referenced this issue May 27, 2013

Update to 1.0.11
commit 5f34991
Author: kpdecker <kpdecker@gmail.com>
Date:   Mon May 27 12:29:57 2013 -0500

    Update in the wild section

    Fixes #246

commit c1020a0
Author: kpdecker <kpdecker@gmail.com>
Date:   Mon May 27 11:52:32 2013 -0500

    Add unicode support for ID tokens

    Fixes #433
    Fixes #469

commit bff71d7
Author: kpdecker <kpdecker@gmail.com>
Date:   Sat May 25 12:32:16 2013 -0500

    Update release notes

commit 4d95d58
Author: kpdecker <kpdecker@gmail.com>
Date:   Sat May 25 12:27:31 2013 -0500

    Rebuild

commit 47e0aa7
Merge: 6bf9c6f f5fe6d0
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Sat May 25 10:07:46 2013 -0700

    Merge pull request #526 from jamesgorrie/master

    Fixing regex on partial names

commit 6bf9c6f
Merge: 533be69 10669e0
Author: kpdecker <kpdecker@gmail.com>
Date:   Wed May 22 08:40:28 2013 -0400

    Merge branch 'master' of github.com:wycats/handlebars.js

commit 533be69
Author: kpdecker <kpdecker@gmail.com>
Date:   Tue May 21 13:12:11 2013 -0500

    Use better variable name

commit a97820f
Author: kpdecker <kpdecker@gmail.com>
Date:   Tue May 21 13:03:41 2013 -0500

    Update testing notes

    Fixes #467

commit f6b6361
Author: kpdecker <kpdecker@gmail.com>
Date:   Tue May 21 13:03:01 2013 -0500

    Fix typo

commit 10669e0
Merge: 5ba17c9 69bcdf3
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Tue May 21 08:46:27 2013 -0700

    Merge pull request #533 from blessenm/amd-precompilation-fix

    Fix for the issue #517

commit 69bcdf3
Author: Blessan Mathew <blessenm@gmail.com>
Date:   Tue May 21 20:50:46 2013 +0530

    Fix for issue #517.

    Now when compiiled with amd option and a single input argument, we are
    checking to see whether the input is a file or folder.

commit 5ba17c9
Merge: 7fb9750 94cc419
Author: kpdecker <kpdecker@gmail.com>
Date:   Sun May 19 11:47:01 2013 -0500

    Merge branch 'master' of github.com:wycats/handlebars.js

commit 7fb9750
Author: kpdecker <kpdecker@gmail.com>
Date:   Sun May 19 11:45:20 2013 -0500

    Update block helper docs in README

    Fixes #231, #259

commit c95d9d6
Author: kpdecker <kpdecker@gmail.com>
Date:   Sun May 19 11:30:26 2013 -0500

    Use context rather than arg in README examples

commit 3aef7f6
Author: kpdecker <kpdecker@gmail.com>
Date:   Sun May 19 11:30:04 2013 -0500

    Misc readme updates

commit f5fe6d0
Author: James Gorrie <james@bravenewtalent.com>
Date:   Fri May 17 16:58:34 2013 +0100

    Allowed for points to be in partial path name

commit 94cc419
Merge: 4cf0410 d649b35
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Tue May 14 21:10:14 2013 -0700

    Merge pull request #515 from jjclark1982/master

    Allow requiring ".handlebars" files within Node.js scripts

commit d649b35
Author: Jesse Clark <jjclark1982@gmail.com>
Date:   Wed May 15 10:50:01 2013 +1000

    Only run "require" tests when require() is available

commit 229b82b
Author: Jesse Clark <jjclark1982@gmail.com>
Date:   Wed May 15 10:38:45 2013 +1000

    Add unit tests for require() handler

commit 531be77
Author: Jesse Clark <jjclark1982@gmail.com>
Date:   Tue May 14 22:26:20 2013 +1000

    Publish a Node.js require() handler for handlebars files

commit 4cf0410
Author: kpdecker <kpdecker@gmail.com>
Date:   Mon May 13 23:09:21 2013 -0500

    1.0.11

commit 2ec5a97
Author: kpdecker <kpdecker@gmail.com>
Date:   Mon May 13 23:08:43 2013 -0500

    Update release notes

commit ddc4d31
Author: kpdecker <kpdecker@gmail.com>
Date:   Mon May 13 23:07:29 2013 -0500

    Rev to rc4

commit 85dd394
Author: kpdecker <kpdecker@gmail.com>
Date:   Fri May 10 01:35:25 2013 -0500

    Add regex escapes

commit 8b65fa7
Author: kpdecker <kpdecker@gmail.com>
Date:   Fri May 10 01:24:11 2013 -0500

    Update release notes

commit fa6cec2
Author: kpdecker <kpdecker@gmail.com>
Date:   Fri May 10 01:02:13 2013 -0500

    Update client packager versions

commit 436973f
Author: kpdecker <kpdecker@gmail.com>
Date:   Fri May 10 01:00:39 2013 -0500

    Version update script

commit a279678
Merge: d355d1f 8a5705a
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Thu May 9 22:37:23 2013 -0700

    Merge pull request #505 from MikeMayer/master

    Include a .nuspec package file to include handlebars.js on NuGet

commit d355d1f
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Fri May 10 00:35:05 2013 -0500

    Fix links in release notes

commit 71c5e36
Merge: 44ae572 fc52a65
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Thu May 9 22:29:27 2013 -0700

    Merge pull request #489 from DevinClark/bower-update

    Added a component.json file for Twitter's Bower package manager.

commit 44ae572
Author: kpdecker <kpdecker@gmail.com>
Date:   Fri May 10 00:14:55 2013 -0500

    Add release notes

    Fixes #471

commit 7cd9cdb
Merge: ef32573 090ee7c
Author: Kevin Decker <kpdecker@gmail.com>
Date:   Thu May 9 21:03:03 2013 -0700

    Merge pull request #513 from tommydudebreaux/master

    Using handlebars with browserify causes IE to throw - TypeError: Invalid calling object

commit 090ee7c
Author: Tommy Messbauer <tommy@vast.com>
Date:   Thu May 9 17:17:34 2013 -0500

    added local pointer to handlerbars.utils to allow this to browserify properly for IE

commit 8a5705a
Author: MikeMayer <mike@mikemayer.me>
Date:   Wed May 1 09:58:17 2013 -0700

    Explicitly only include the handlebars.js from the dist folder

commit 344bb90
Author: MikeMayer <mike@mikemayer.me>
Date:   Wed May 1 09:52:55 2013 -0700

    Create handlebars.js.nuspec for inclusion in NuGet

    Added a .nuspec file for those people who use Visual Studio and NuGet and might want to use handlebars.js deployed from NuGet in their application.

commit fc52a65
Author: DevinClark <dclarkdesign@gmail.com>
Date:   Thu Apr 25 21:05:21 2013 -0500

    Changed component.json to bower.json per Bower 0.9.0 update.

commit 5c9aa9e
Author: DevinClark <dclarkdesign@gmail.com>
Date:   Mon Apr 8 12:28:13 2013 -0500

    Added a component.json file for Twitter's Bower package manager.

    See [https://github.com/twitter/bower#defining-a-package](Defining a
    package) for more information about how the file was generated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment