Repository navigation
New features
System.Text.JsonJsonNodesupport. You can now passJsonObject,JsonArrayandJsonValueinto templates directly. They support the same things asJsonElement: member access,#eachwith@index/@key/@first/@last, truthiness,includeZeroand partials.JsonElementalso gains array index access ({{items.[0]}},{{lookup items 1}}),{{items.Count}}(plus{{items.length}}withUseCollectionMemberAliasProvider()), and support for custom alias providers. New public types:JsonNodeObjectDescriptorProvider,JsonNodeMemberAccessor,JsonNodeIterator.JsonElementObjectDescriptorProviderandJsonElementMemberAccessorget new constructor overloads that take alias providers. (#670)- Error locations on exceptions.
HandlebarsExceptionhas newLineandColumnproperties (int?, zero-based,nullwhen the location isn't known). The derived compiler, parser and runtime exceptions inherit them. When a compile-time error has a location, its message now ends with the offending template line and a caret under the column. (#681, refs #314) - Clearer messages for common syntax errors.
{{#if !x}}now says that!isn't a negation operator and points you to#unless. Unclosed blocks, stray closing tags and mismatched}}}now report where they happened. (#680, refs #314) Compatibility.BlockScopedInlinePartials(opt-in, defaultfalse): when enabled, an inline partial declared inside a block or an included partial is visible only within that block and its children, as in Handlebars.js. With the default, existing behavior is unchanged. (#688, refs #673)Compatibility.LegacyStandaloneCaretBehavior: a new opt-out flag that restores the old{{^}}behavior (see Fixes). (#675, fixes #672)
Fixes
- A standalone
{{^}}inside a block (also{{^ }}and{{~^~}}) is now the inverse separator, the same as{{else}}, matching Handlebars.js. Inside raw blocks it stays literal text. (#675, fixes #672) {{else name args}}under{{#if}}/{{#unless}}now chains to the named helper, as in Handlebars.js. Previously it was evaluated as{{else if …}}, or the condition was silently dropped.{{else unless x}}now hasunlesssemantics, and{{else with x}}chains to the built-inwith. (#687, #689, fixes #683){{#if}}/{{#unless}}with a missing argument now throwHandlebarsCompilerExceptioninstead of a bareInvalidOperationException. (#678, fixes #674)- Raw block helpers now compile when
Compatibility.RelaxedHelperNaming = true. (#677, fixes #676) {{#each}}over items of different runtime types now looks each item's members up by its own type. Before, a dictionary followed by a number threwInvalidCastException, and a number followed by a dictionary rendered empty. For example,{{#each items}}[{{name}}]{{/each}}over[{name: "Erik"}, 42, {name: "Helen"}]now renders[Erik][][Helen]. Collections whose items all share one type behave as before. (#691, fixes #685)JsonArraymember access is limited to indexes,Countand configured aliases, soParent/Root/Optionsno longer resolve through reflection. ScalarJsonValues read throughJsonSerializerno longer throw. (#670)
Internal
- Sealed
ReusableStringWriter(it has only a private constructor, so this doesn't break anything), and split upTokenizer/LiteralParsermethods for the SonarCloud S3881/S3776 items. No behavior change. (#679, closes #641)
Compatibility notes
Some templates and code that worked before will behave differently:
{{^}}inside a block used to render the current context, and the block had no inverse branch. It is now{{else}}. For example,{{#if condition}}yes{{^}}no{{/if}}withcondition = trueused to renderyes{ condition = True }noand now rendersyes. Withcondition = falseit used to render nothing and now rendersno. To restore the old output, setConfiguration.Compatibility.LegacyStandaloneCaretBehavior = true. (#675){{else unless x}}under{{#if}}used to be evaluated as{{else if x}}, which inverted the condition.{{else someHelper x}}used to ignoresomeHelper. It now calls it, and throws the usual missing-helperHandlebarsRuntimeExceptionifsomeHelperisn't registered.{{else if a b}}and{{else unless a b}}(too many arguments) and a second{{else}}now fail at compile time. Plain{{else}},{{else if x}}and a bare{{else name}}are unchanged. (#687)- Exception messages: the location text changed from
Occured at: l:ctoLine l, column c., and located compile errors now end with a source line and a caret. Code that matches on the exception type or message prefix keeps working. Code that searches forOccured at:or compares the fullMessagewill not match. Use the newLine/Columnproperties instead.{{#if}}with no argument now throwsHandlebarsCompilerExceptioninstead ofInvalidOperationException. With too many arguments, it now says#if requires exactly one argument. (#678, #680, #681, #682) JsonNode:false,0and""are now falsy in#if/#unless/#each. Before, they were truthy.JsonObjectlookups now fall back to the lowercase property name. Custom member alias providers are now consulted forJsonElementandJsonObjectmembers that don't otherwise resolve. When interpolated directly,JsonNodebooleans still render astrue/false, whileJsonElementbooleans render asTrue/False. (#670)
Contributors: @jsneedles (JsonNode support), @EnesKartal (#684, whose test case and approach were incorporated into #687/#689), @bardrop (#686, whose fix and tests were incorporated into #691), @rexm
Full Changelog: 2.4.3...2.4.4