Skip to content

2.4.4

Latest

Choose a tag to compare

@stencil-harness stencil-harness released this 22 Nov 19:13
· 12 commits to master since this release
74bf99f

New features

  • System.Text.Json JsonNode support. You can now pass JsonObject, JsonArray and JsonValue into templates directly. They support the same things as JsonElement: member access, #each with @index/@key/@first/@last, truthiness, includeZero and partials. JsonElement also gains array index access ({{items.[0]}}, {{lookup items 1}}), {{items.Count}} (plus {{items.length}} with UseCollectionMemberAliasProvider()), and support for custom alias providers. New public types: JsonNodeObjectDescriptorProvider, JsonNodeMemberAccessor, JsonNodeIterator. JsonElementObjectDescriptorProvider and JsonElementMemberAccessor get new constructor overloads that take alias providers. (#670)
  • Error locations on exceptions. HandlebarsException has new Line and Column properties (int?, zero-based, null when 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, default false): 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 has unless semantics, and {{else with x}} chains to the built-in with. (#687, #689, fixes #683)
  • {{#if}}/{{#unless}} with a missing argument now throw HandlebarsCompilerException instead of a bare InvalidOperationException. (#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 threw InvalidCastException, 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)
  • JsonArray member access is limited to indexes, Count and configured aliases, so Parent/Root/Options no longer resolve through reflection. Scalar JsonValues read through JsonSerializer no longer throw. (#670)

Internal

  • Sealed ReusableStringWriter (it has only a private constructor, so this doesn't break anything), and split up Tokenizer/LiteralParser methods 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}} with condition = true used to render yes{ condition = True }no and now renders yes. With condition = false it used to render nothing and now renders no. To restore the old output, set Configuration.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 ignore someHelper. It now calls it, and throws the usual missing-helper HandlebarsRuntimeException if someHelper isn'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:c to Line 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 for Occured at: or compares the full Message will not match. Use the new Line/Column properties instead. {{#if}} with no argument now throws HandlebarsCompilerException instead of InvalidOperationException. With too many arguments, it now says #if requires exactly one argument. (#678, #680, #681, #682)
  • JsonNode: false, 0 and "" are now falsy in #if/#unless/#each. Before, they were truthy. JsonObject lookups now fall back to the lowercase property name. Custom member alias providers are now consulted for JsonElement and JsonObject members that don't otherwise resolve. When interpolated directly, JsonNode booleans still render as true/false, while JsonElement booleans render as True/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