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.
      • Hello {{or [First-Name] "Valued Customer"}}!
  • 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 ltonly with numeric values.
      • {{#if (lt [Days-Until-Expiration] 7)}}  <p><strong>URGENT:</strong> Your membership expires in {{[Days-Until-Expiration]}} days!</p> {{/if}}


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: