Clarification on valid partial identifiers

[knksmith57]

Heya Team,

I'm seeking clarification on a few edge cases regarding the naming of partials.

context

My team has been developing a system for npm-installing modules that contain handlebars templates (among other things). We publish using a private (scoped) package namespace (call it @rmn for argument's sake 😉 ).

Partials are named according to their directory structure. We have a spec that defines this structure and a suite of tools used for loading handlebars partials that are bundled up according to the spec (express middleware, a partialresolver for our php stack using LightnCandy, etc).

Partial names are formed by prefixing the relative path to the directory containing the partial with the package name. This is best explained using an example.

example

Given a package named @rmn/homepage that provides two partials, button and card, the following is installed in node_modules:

❯ tree
.
└── @rmn
    └── homepage
        ├── button
        │   └── index.hbs
        ├── card
        │   └── index.hbs
        └── package.json

Loading this package will result in 2 partials available for inclusion in a template:

• @rmn/homepage/button
• @rmn/homepage/card

The nested @rmn/ + homepage directory structure is an artifact of npm and the way it installs scoped packages on disk.

Up until this point, we've had no trouble using this naming convention (actually, we've enjoyed a lot of success!), but now we are running into issues with other handlebars libraries handling the @rmn/ prefix (namely LightnCandy).

I'm here to seek clarification on what is and what is not allowed in a partial name.

partial naming rules

Directly from the grammar at the time of writing:

/*
ID is the inverse of control characters.
Control characters ranges:
  [\s]          Whitespace
  [!"#%-,\./]   !, ", #, %, &, ', (, ), *, +, ,, ., /,  Exceptions in range: $, -
  [;->@]        ;, <, =, >, @,                          Exceptions in range: :, ?
  [\[-\^`]      [, \, ], ^, `,                          Exceptions in range: _
  [\{-~]        {, |, }, ~
*/
ID    [^\s!"#%-,\.\/;->@\[-\^`\{-~]+/{LOOKAHEAD}

Compilers class was a dark time in my life. My primitive understanding of this file leads me to believe the following:

• ID refers to a partial name (eg: the thing used when one invokes a partial, {{> thisIsTheID}}).
• ID can start with any character except those in the negated character class.
• ID can not start with @.

but it works

The behavior that I see (and have been seeing across both handlebars.js & LnC for many versions) fails these assertions.

• regular partial invocation: https://jsfiddle.net/kg7vrdk3/
• partial block invocation: https://jsfiddle.net/kg7vrdk3/1/

Until that second use case cropped up (recently), where my team started using partial blocks, everything was kosher in both handlebars.js & LnC.

Given that using @rmn/foo now fails in LnC, I started digging into the spec and have finally arrived here. We need our templates to be portable and that has led me to the following observations:

• Quoting the partial name does not impact handlebars.js: https://jsfiddle.net/kg7vrdk3/2/
• Quoting the partial name is portable and works in LnC

questions

• Is our current naming convention invalid (ie: @rmn/foo)?
• Does quoting the partial name make it valid (ie: {{> "@rmn/foo"}}
• Is this a bad idea?

Thanks for taking the time to give this issue a read.

[mootari]

I wondered the same thing and found that the spec contains tests that cover slashes and dots in partial names: https://github.com/wycats/handlebars.js/blob/94419deb95c0c8d1edc860026a159139e4800cf6/spec/partials.js#L133-L145

[mootari]

@ at the beginning of a partial name is recognized, while inside a partial name it is not. This is likely meant to support internal partials, like the special @partial-block. I wouldn't consider it public API and try to stay away.

The handling of @partial-block: https://github.com/wycats/handlebars.js/blob/94419deb95c0c8d1edc860026a159139e4800cf6/lib/handlebars/runtime.js#L199-L212

Related: #1277, #1192

[nknapp]

Closing due to inactivity.