Best Practices


When adding Handlebars, there are some Best Practices to keep in mind:

  • Always provide fallbacks: Use default or or helpers to ensure graceful degradation when data is missing.
  • Wrap complex variables: Any variable name with special characters (hyphens, colons, spaces) must be wrapped in square brackets:
    {{[First-Name]}} Correct (has hyphen)
    {{[todaysdate:Ymd]}} Correct (has colon)
    {{[subscriber-timezone]}} Correct (has hypen)
    {{First-Name}} Incorrect (should be wrapped in square brackets)
  • Variables with underscores only (like current_day, subscriber_id) do NOT need brackets:
    {{current_day}} Correct (has underscore)
    {{[random_number]}} Incorrect (square brackets not required)
  • Test with empty data: Ensure your templates render correctly when custom fields are empty.
  • Use meaningful fallbacks: Instead of generic "Customer", try context-specific fallbacks:
    Hello {{or [First-Name] "Valued member"}}!
  • Combine helpers for complex logic: Nest helpers to create sophisticated conditional logic:
    {{#if (and (eq [Country] "US") (gt [Order-Total] 50))}
  • Keep comparisons data type-appropriate: Use gt and lt only with numeric values.


Troubleshooting


Issue: Variable not displaying

Solution: Check if the variable name has special characters (hyphens, colons, spaces) and wrap it in brackets 

  • {{[First-Name]}}, {{[todaysdate:Ymd]}}

  • Note: Variables with only underscores don't need brackets 

    • {{current_day}}, {{subscriber_id}}

  • Issue: Comparison not working

    • Solution: Ensure you're comparing compatible types (numbers with numbers, strings with strings)

  • Issue: Syntax errors

    • Solution: Verify all opening {{#if}} tags have closing {{/if}} tags

  • Issue: gt or lt not working

    • Solution: These helpers only work with numeric values. Ensure your custom fields contain numbers.


For more detailed information on Handlebars, please consult the appropriate article below: