DOCSEARCHbyAlgolia
Submit Docs

Blaze Documentation

repository·master·Indexed 19 days ago

https://github.com/meteor/blaze

A reactive user interface library for Meteor that uses HTML templates to automatically update the DOM in response to data changes. The documentation covers the core Blaze runtime, the Spacebars templating language, and the blaze-html-templates meta-package. It also includes technical details on the CachingHtmlCompiler for build plugins, HTMLTools for parsing HTML fragments and extending the parser with custom tags, and HTMLjs for expressing HTML trees using JavaScript syntax.

Tokens
23.8K
Snippets
79
Records
121
Agent score
68%

What's inside Blaze

  2. Introduction to Spacebars template syntax

    master

    Spacebars is a Meteor template language inspired by Handlebars, designed for reactive DOM updates. A template consists of HTML interspersed with four types of template tags:

    • Double-braced {{value}}: Inserts text. The text is automatically escaped for safety (e.g., < becomes &lt;).
    • Inclusion {{> templateName}}: Inserts another template by name.
    • Block tags {{#block}}...{{/block}}: Defines a block of content. Built-in tags include #if, #each, #with, and #unless. Some (like #each and #with) establish a new data context for the content inside the block.
    • Triple-braced {{{rawHTML}}}: Inserts raw HTML. Warning: You are responsible for ensuring this HTML is safe and contains balanced tags.
    <template name="myPage">
  <h1>{{pageTitle}}</h1>

  {{> nav}}

  {{#each posts}}
    <div class="post">
      <h3>{{title}}</h3>
      <div class="post-content">
        {{{content}}}
      </div>
    </div>
  {{/each}}
</template>

  3. What is Blaze?

    master

    Blaze is a library for creating user interfaces using reactive HTML templates. It eliminates the need for manual DOM manipulation by integrating template directives with reactive data sources.

    Core Components

    • Template Compiler: Compiles template files into JavaScript code that runs against the Blaze runtime. It supports various syntaxes via a compiler toolchain; the primary syntax is Spacebars (a Handlebars variant), though others like Jade are supported.
    • Reactive DOM Engine: A runtime engine that manages the DOM, providing reactively updating regions, lists, and attributes. It includes event delegation and various developer hooks/callbacks.

    Reactivity Model

    Blaze uses template directives like {{#if}} and {{#each}} to automatically update the DOM when underlying data changes. It relies on Tracker for transparent reactivity and Minimongo for database cursors to trigger these updates.

  4. What is BlazeJS

    master

    Blaze is a reactive UI library that allows you to create user interfaces using HTML templates. It eliminates manual DOM manipulation by integrating with Meteor's reactivity system (Tracker) and database cursors (Minimongo).

    Instead of writing logic to listen for data changes and update the DOM manually (as one might do with jQuery), you use template directives like {{#if}} and {{#each}}. When the underlying data changes, Blaze automatically updates the corresponding parts of the DOM.

  5. Use CachingHtmlCompiler to implement HTML-style template plugins

    master

    The CachingHtmlCompiler is a pluggable class designed for Meteor build plugins that need to compile HTML-style templates. It abstracts away caching logic and communication with build plugin APIs, making it easier to implement plugins similar to templating, static-html, or simple:markdown-templating.

    To use it, you must provide two core functions to the constructor:

    1. A tag scanner function that parses a template string into an array of Tag objects.
    2. A tag handler function that processes those Tag objects into a structured object containing js, body, head, and bodyAttr properties.

    This separation allows you to unit test your parsing and compilation logic independently of the file system and caching layers.

    Plugin.registerCompiler({
  extensions: ['html'],
  archMatching: 'web',
  isTemplate: true
}, () => new CachingHtmlCompiler(
  "templating",
  TemplatingTools.scanHtmlForTags,
  TemplatingTools.compileTagsWithSpacebars
));

  6. Use blaze-html-templates to run Meteor templates

    master

    The blaze-html-templates meta-package provides a complete environment for compiling and executing Meteor templates. It bundles the necessary components to handle the full template lifecycle, including compilation of .html files and the runtime execution using Spacebars and Blaze.

    This package includes:

    • templating: Responsible for compiling .html files.
    • blaze: The core runtime library.
    • spacebars: The templating language used within the templates.

  7. What is a Blaze View?

    master

    A View is the core building block representing a reactively rendering area of a template. It is the underlying machinery that tracks reactivity, performs name lookups, and manages re-rendering. In Blaze, the View is the unit of re-rendering.

    While you can technically walk the view tree to traverse the component hierarchy, it is recommended to communicate between components using callbacks, template arguments, or global data stores instead.

  8. What is Blaze and how does it work?

    master
    Blaze is Meteor's built-in reactive rendering library used to build user interfaces. It works by taking templates written in Spacebars (a reactive variant of Handlebars) and compiling them into JavaScript UI components. These components are then rendered by the Blaze engine. Blaze is designed to integrate deeply with Tracker, Meteor's reactivity system, allowing the UI to automatically update when underlying data changes.

  9. Name data contexts for template inclusions

    master

    When including a template (e.g., {{> MyTemplate}}), avoid letting it inherit the parent's data context implicitly. Instead, explicitly name the arguments. This improves clarity (e.g., {{todo.title}} vs {{title}}) and provides flexibility for adding more arguments later.

    Best Practices:

    • Explicit Naming: Use {{> Todos_item todo=todo}} instead of {{> Todos_item todo}}.
    • Explicit Empty Context: If a template should not inherit parent data, pass an empty context: {{> myTemplate ""}}.
    <!-- bad: inherits data context, who knows what is in there! -->
{{> myTemplate}}

<!-- explicitly passes empty data context -->
{{> myTemplate ""}}

  10. Identify renderable content in Blaze

    master

    In Blaze, a value is considered renderable content if it can be processed by the rendering engine. When passing content to Blaze functions or templates, ensure the value is one of the following supported types:

    • A template object: For example, Template.myTemplate.
    • An unrendered View object: Such as the object returned by Blaze.With.
    • null or undefined: These are treated as empty content.

    Note that while Blaze internally handles objects representing HTML tags, these are not part of the officially supported public API and should not be used directly by consumers.

  11. Understand Spacebars HTML syntax and requirements

    master

    Spacebars templates use standard HTML extended with template tags. Unlike web browsers, Spacebars is strict about HTML structure and will throw compile-time errors for malformed markup (e.g., a bare < that isn't a tag).

    Key Syntax Rules:

    • Tag Closing: You must close all HTML tags except for self-closing tags like BR, HR, IMG, and INPUT (which can be written as <br> or <br/>).
    • Strictness: Unlike the HTML spec, Spacebars does not currently support omitting end tags for elements like <p> or <li>.
    • Flexibility: Attribute values do not require quotes, and tags are not case-sensitive.