DOCSEARCHbyAlgolia
Submit Docs

Handlebars.js Documentation

website·Indexed 42 days ago

https://handlebarsjs.com/

A simple templating language that provides the power to build semantic templates. Documentation covers installation, precompilation, expressions, built-in and block helpers, partials, and the Handlebars runtime API.

Tokens
10.6K
Snippets
67
Records
105
Agent score
75%

What's inside Handlebars

  1. Overview of Handlebars templating

    Handlebars is a templating language that uses a template and an input object to generate HTML or other text formats. Templates consist of regular text with embedded expressions denoted by double curly braces {{ }}. During execution, these expressions are replaced with values from the provided input object.

  2. Determine if Handlebars is the right tool for your project

    Handlebars is a pure rendering engine designed for generating HTML pages, emails, or markdown files. It is highly effective for server-side rendering of pure content, CLI applications, and non-HTML text content. Because it has been ported to multiple languages (such as Java and Rust), it is suitable for cross-language environments.

    However, Handlebars is not suitable for building complex Single-Page Applications (SPAs) because it lacks built-in support for:

    • Event-handling
    • Accessing backend services
    • Incremental DOM updates
    • Frontend-backend communication

    If your project requires these capabilities, consider using a dedicated frontend framework such as React, Vue, Angular, Svelte, or Ember.

  4. Use the options parameter in Handlebars helpers

    When a Handlebars helper is called, it receives an options object as an additional parameter alongside the explicit parameters defined in the helper call. This object provides utility functions and metadata about the current execution context.

  6. Return HTML from a block helper using SafeString

    When a block helper needs to return HTML markup without it being escaped by Handlebars, wrap the resulting string in new Handlebars.SafeString().
    Handlebars.registerHelper("bold", function (options) {
  return new Handlebars.SafeString('<div class="mybold">' + options.fn(this) + "</div>");
});

  7. Use Block Parameters to avoid name conflicts

    Introduced in Handlebars 3.0, block parameters allow helpers to pass named variables to the template block. This is particularly useful for nested helpers to avoid name collisions that occur when using private variables. The syntax uses the as |param1 param2| pattern.
    {{#each users as |user userId|}}
  {{#each user.book as |book bookId|}}
    User Id: {{userId}}
    Book Id: {{bookId}}
  {{/each}}
{{/each}}

  8. Execute Handlebars partials dynamically

    You can dynamically select which partial to execute using sub-expression syntax. Because sub-expressions do not resolve variables, the value must be returned by a function. If the partial name is stored in a simple variable, use the lookup helper to resolve it.
    {{!-- Using a function --}}
{{> (whichPartial)}}

{{!-- Using a variable via lookup helper --}}
{{> (lookup . 'whichPartial')}}

  9. Submit contributions to Handlebars documentation

    The Handlebars documentation site is hosted on GitHub and rendered with VitePress. There are two ways to submit changes:

    1. Single-page content changes: Use the Suggest changes to this page link at the bottom of the page to edit files directly via GitHub.
    2. Complex changes: For styling updates, multi-page changes, new pages, or build fixes, fork the repository and submit a pull request. This allows the use of a local dev-server to preview changes before submission.
    Repository: https://github.com/handlebars-lang/docs

  10. Pass custom contexts and parameters to partials

    Partials can be executed on a custom context by passing the context object directly in the call. Additionally, custom data can be passed to partials using hash parameters, which is useful for exposing parent context data to the partial.
    {{!-- Pass a custom context --}}
{{> myPartial someContext}}

{{!-- Pass hash parameters --}}
{{> myPartial parameter="value"}}

  12. Reuse base data for Handlebars examples

    To maintain consistency across documentation, examples should use variations of the common data set located in src/examples/_example-base-data.yaml. If the base data is insufficient, new related data should be added to this file.