Blaze

Blaze is the package that makes reactive templates possible. You can use the Blaze API directly in order to render templates programmatically and manipulate “Views,” the building blocks of reactive templates. For more information, check out the Blaze project page.

Client

Blaze.render(templateOrView, parentNode, [nextNode], [parentView])

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 614)

Renders a template or View to DOM nodes and inserts it into the DOM, returning a rendered View which can be passed to Blaze.remove.

Arguments

templateOrView Blaze.Template or Blaze.View

The template (e.g. Template.myTemplate) or View object to render. If a template, a View object is constructed. If a View, it must be an unrendered View, which becomes a rendered View and is returned.

parentNode DOM Node

The node that will be the parent of the rendered template. It must be an Element node.

nextNode DOM Node

Optional. If provided, must be a child of parentNode; the template will be inserted before this node. If not provided, the template will be inserted as the last child of parentNode.

parentView Blaze.View

Optional. If provided, it will be set as the rendered View's parentView.

When you render a template, the callbacks added with onCreated are invoked immediately, before evaluating the content of the template. The callbacks added with onRendered are invoked after the View is rendered and inserted into the DOM.

The rendered template will update reactively in response to data changes until the View is removed using Blaze.remove or the View’s parent element is removed by Meteor or jQuery.

If the View is removed by some other mechanism besides Meteor or jQuery (which Meteor integrates with by default), the View may continue to update indefinitely. Most users will not need to manually render templates and insert them into the DOM, but if you do, be mindful to always call Blaze.remove when the View is no longer needed.

Client

Blaze.renderWithData(templateOrView, data, parentNode, [nextNode], [parentView])

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 665)

Renders a template or View to DOM nodes with a data context. Otherwise identical to Blaze.render.

Arguments

templateOrView Blaze.Template or Blaze.View

The template (e.g. Template.myTemplate) or View object to render.

data Object or Function

The data context to use, or a function returning a data context. If a function is provided, it will be reactively re-run.

parentNode DOM Node

The node that will be the parent of the rendered template. It must be an Element node.

nextNode DOM Node

Optional. If provided, must be a child of parentNode; the template will be inserted before this node. If not provided, the template will be inserted as the last child of parentNode.

parentView Blaze.View

Optional. If provided, it will be set as the rendered View's parentView.

Blaze.renderWithData(Template.myTemplate, data) is essentially the same as Blaze.render(Blaze.With(data, function () { return Template.myTemplate; })).

Client

Blaze.remove(renderedView)

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 677)

Removes a rendered View from the DOM, stopping all reactive updates and event listeners on it. Also destroys the Blaze.Template instance associated with the view.

Arguments

renderedView Blaze.View

The return value from Blaze.render or Blaze.renderWithData, or the view property of a Blaze.Template instance. Calling Blaze.remove(Template.instance().view) from within a template event handler will destroy the view as well as that template and trigger the template's onDestroyed handlers.

Use Blaze.remove to remove a template or View previously inserted with Blaze.render, in such a way that any behaviors attached to the DOM by Meteor are cleaned up. The rendered template or View is now considered “destroyed”, along with all nested templates and Views. In addition, any data assigned via jQuery to the DOM nodes is removed, as if the nodes were passed to jQuery’s $(...).remove().

As mentioned in Blaze.render, it is important to “remove” all content rendered via Blaze.render using Blaze.remove, unless the parent node of renderedView is removed by a Meteor reactive update or with jQuery.

Blaze.remove can be used even if the DOM nodes in question have already been removed from the document, to tell Blaze to stop tracking and updating these nodes.

Client

Blaze.getData([elementOrView])

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 743)

Returns the current data context, or the data context that was used when rendering a particular DOM element or View from a Meteor template.

Arguments

elementOrView DOM Element or Blaze.View

Optional. An element that was rendered by a Meteor, or a View.

Client

Blaze.toHTML(templateOrView)

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 698)

Renders a template or View to a string of HTML.

Arguments

templateOrView Blaze.Template or Blaze.View

The template (e.g. Template.myTemplate) or View object from which to generate HTML.

Rendering a template to HTML loses all fine-grained reactivity. The normal way to render a template is to either include it from another template ({% raw %}{{> myTemplate}}{% endraw %}) or render and insert it programmatically using Blaze.render. Only occasionally is generating HTML useful.

Because Blaze.toHTML returns a string, it is not able to update the DOM in response to reactive data changes. Instead, any reactive data changes will invalidate the current Computation if there is one (for example, an autorun that is the caller of Blaze.toHTML).

Client

Blaze.toHTMLWithData(templateOrView, data)

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 710)

Renders a template or View to HTML with a data context. Otherwise identical to Blaze.toHTML.

Arguments

templateOrView Blaze.Template or Blaze.View

The template (e.g. Template.myTemplate) or View object from which to generate HTML.

data Object or Function

The data context to use, or a function returning a data context.

Client

new Blaze.View([name], renderFunction)

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 43)

Constructor for a View, which represents a reactive region of DOM.

Arguments

name String

Optional. A name for this type of View. See view.name.

renderFunction Function

A function that returns renderable content. In this function, this is bound to the View.

Behind every template or part of a template — a template tag, say, like {% raw %}{{foo}}{% endraw %} or {% raw %}{{#if}}{% endraw %} — is a View object, which is a reactively updating region of DOM.

Most applications do not need to be aware of these Views, but they offer a way to understand and customize Meteor’s rendering behavior for more advanced applications and packages.

You can obtain a View object by calling Blaze.render on a template, or by accessing template.view on a template instance.

At the heart of a View is an autorun that calls the View’s renderFunction, uses the result to create DOM nodes, and replaces the contents of the View with these new DOM nodes. A View’s content may consist of any number of consecutive DOM nodes (though if it is zero, a placeholder node such as a comment or an empty text node is automatically supplied). Any reactive dependency established by renderFunction causes a full recalculation of the View’s contents when the dependency is invalidated. Templates, however, are compiled in such a way that they do not have top-level dependencies and so will only ever render once, while their parts may re-render many times.

When a Blaze.View is constructed by calling the constructor, no hooks are fired and no rendering is performed. In particular, the View is not yet considered to be “created.” Only when the View is actually used, by a call to Blaze.render or Blaze.toHTML or by inclusion in another View, is it “created,” right before it is rendered for the first time. When a View is created, its .parentView is set if appropriate, and then the onViewCreated hook is fired. The term “unrendered View” means a newly constructed View that has not been “created” or rendered.

The “current View” is kept in Blaze.currentView and is set during View rendering, callbacks, autoruns, and template event handlers. It affects calls such as Template.currentData().

The following properties and methods are available on Blaze.View:

nameString

The name of this type of View. View names may be used to identify particular kinds of Views in code, but more often they simply aid in debugging and comprehensibility of the View tree. Views generated by Meteor have names like “Template.foo” and “if”.

parentViewView or null

The enclosing View that caused this View to be rendered, if any.

isCreatedBoolean

True if this View has been called on to be rendered by Blaze.render or Blaze.toHTML or another View. Once it becomes true, never becomes false again. A “created” View’s .parentView has been set to its final value. isCreated is set to true before onViewCreated hooks are called.

isRenderedBoolean

True if this View has been rendered to DOM by Blaze.render or by the rendering of an enclosing View. Conversion to HTML by Blaze.toHTML doesn’t count. Once true, never becomes false.

isDestroyedBoolean

True if this View has been destroyed, such as by Blaze.remove() or by a reactive update that removes it. A destroyed View’s autoruns have been stopped, and its DOM nodes have generally been cleaned of all Meteor reactivity and possibly dismantled.

renderCountInteger

The number of times the View has been rendered, including the current time if the View is in the process of being rendered or re-rendered.

autorun(runFunc)

Like Tracker.autorun, except that the autorun is automatically stopped when the View is destroyed, and the current View is always set when running runFunc. There is no relationship to the View’s internal autorun or render cycle. In runFunc, the View is bound to this.

onViewCreated(func)

If the View hasn’t been created yet, calls func when the View is created. In func, the View is bound to this.

This hook is the basis for the created template callback.

onViewReady(func)

Calls func when the View is rendered and inserted into the DOM, after waiting for the end of flush time. Does not fire if the View is destroyed at any point before it would fire. May fire multiple times (if the View re-renders). In func, the View is bound to this.

This hook is the basis for the rendered template callback.

onViewDestroyed(func)

If the View hasn’t been destroyed yet, calls func when the View is destroyed. A View may be destroyed without ever becoming “ready.” In func, the View is bound to this.

This hook is the basis for the destroyed template callback.

firstNode()DOM node

The first node of the View’s rendered content. Note that this may be a text node. Requires that the View be rendered. If the View rendered to zero DOM nodes, it may be a placeholder node (comment or text node). The DOM extent of a View consists of the nodes between view.firstNode() and view.lastNode(), inclusive.

lastNode()DOM node

The last node of the View’s rendered content.

See firstNode().

templateTemplate

For Views created by invoking templates, the original Template object. For example, Blaze.render(Template.foo).template === Template.foo.

templateInstance()Template instance

For Views created by invoking templates, returns the template instance object for this particular View. For example, in a created callback, this.view.templateInstance() === this.

Template instance objects have fields like data, firstNode, and lastNode which are not reactive and which are also not automatically kept up to date. Calling templateInstance() causes these fields to be updated.

Client

Blaze.currentView

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 532)

The View corresponding to the current template helper, event handler, callback, or autorun. If there isn't one, null.

The “current view” is used by Template.currentData() and Template.instance() to determine the contextually relevant data context and template instance.

Client

Blaze.getView([element])

import { Blaze } from 'meteor/blaze' (blaze/view.js, line 781)

Gets either the current View, or the View enclosing the given DOM element.

Arguments

element DOM Element

Optional. If specified, the View enclosing element is returned.

If you don’t specify an element, there must be a current View or an error will be thrown. This is in contrast to Blaze.currentView.

Client

Blaze.With(data, contentFunc)

import { Blaze } from 'meteor/blaze' (blaze/builtins.js, line 13)

Constructs a View that renders content with a data context.

Arguments

data Object or Function

An object to use as the data context, or a function returning such an object. If a function is provided, it will be reactively re-run.

contentFunc Function

A Function that returns renderable content.

Returns an unrendered View object you can pass to Blaze.render.

Unlike {% raw %}{{#with}}{% endraw %} (as used in templates), Blaze.With has no “else” case, and a falsy value for the data context will not prevent the content from rendering.

Client

Blaze.If(conditionFunc, contentFunc, [elseFunc])

import { Blaze } from 'meteor/blaze' (blaze/builtins.js, line 73)

Constructs a View that renders content conditionally.

Arguments

conditionFunc Function

A function to reactively re-run. Whether the result is truthy or falsy determines whether contentFunc or elseFunc is shown. An empty array is considered falsy.

contentFunc Function

A Function that returns renderable content.

elseFunc Function

Optional. A Function that returns renderable content. If no elseFunc is supplied, no content is shown in the "else" case.

Returns an unrendered View object you can pass to Blaze.render.

Matches the behavior of {% raw %}{{#if}}{% endraw %} in templates.

Client

Blaze.Unless(conditionFunc, contentFunc, [elseFunc])

import { Blaze } from 'meteor/blaze' (blaze/builtins.js, line 98)

An inverted Blaze.If.

Arguments

conditionFunc Function

A function to reactively re-run. If the result is falsy, contentFunc is shown, otherwise elseFunc is shown. An empty array is considered falsy.

contentFunc Function

A Function that returns renderable content.

elseFunc Function

Optional. A Function that returns renderable content. If no elseFunc is supplied, no content is shown in the "else" case.

Returns an unrendered View object you can pass to Blaze.render.

Matches the behavior of {% raw %}{{#unless}}{% endraw %} in templates.

Client

Blaze.Each(argFunc, contentFunc, [elseFunc])

import { Blaze } from 'meteor/blaze' (blaze/builtins.js, line 122)

Constructs a View that renders contentFunc for each item in a sequence.

Arguments

argFunc Function

A function to reactively re-run. The function can return one of two options:

1. An object with two fields: '_variable' and '_sequence'. Each iterates over '_sequence', it may be a Cursor, an array, null, or undefined. Inside the Each body you will be able to get the current item from the sequence using the name specified in the '_variable' field.

2. Just a sequence (Cursor, array, null, or undefined) not wrapped into an object. Inside the Each body, the current item will be set as the data context.

contentFunc Function

A Function that returns renderable content.

elseFunc Function

A Function that returns renderable content to display in the case when there are no items in the sequence.

Returns an unrendered View object you can pass to Blaze.render.

Matches the behavior of {% raw %}{{#each}}{% endraw %} in templates.

Client

new Blaze.Template([viewName], renderFunction)

import { Blaze } from 'meteor/blaze' (blaze/template.js, line 16)

Constructor for a Template, which is used to construct Views with particular name and content.

Arguments

viewName String

Optional. A name for Views constructed by this Template. See view.name.

renderFunction Function

A function that returns renderable content. This function is used as the renderFunction for Views constructed by this Template.

Templates defined by the template compiler, such as Template.myTemplate, are objects of type Blaze.Template (aliased as Template).

In addition to methods like events and helpers, documented as part of the Template API, the following fields and methods are present on template objects:

viewNameString

Same as the constructor argument.

renderFunctionFunction

Same as the constructor argument.

constructView()

Constructs and returns an unrendered View object. This method is invoked by Meteor whenever the template is used, such as by Blaze.render or by {{> foo}} where foo resolves to a Template object.

constructView() constructs a View using viewName and renderFunction as constructor arguments, and then configures it as a template View, setting up view.template, view.templateInstance(), event maps, and so on.

Client

Blaze.isTemplate(value)

import { Blaze } from 'meteor/blaze' (blaze/template.js, line 61)

Returns true if value is a template object like Template.myTemplate.

Arguments

value Any

The value to test.

Renderable Content

A value is renderable content if it is one of the following:

• A template object like Template.myTemplate
• An unrendered View object, like the return value of Blaze.With
• null or undefined

Internally, renderable content includes objects representing HTML tags as well, but these objects are not yet part of the officially-supported, public API.