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.
Blaze.render(templateOrView, parentNode, [nextNode], [parentView])
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 609) 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
.
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.
Blaze.renderWithData(templateOrView, data, parentNode, [nextNode], [parentView])
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 660) Renders a template or View to DOM nodes with a data context. Otherwise identical to Blaze.render
.
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; }))
.
Blaze.remove(renderedView)
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 672) 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.
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.
Blaze.getData([elementOrView])
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 738) Returns the current data context, or the data context that was used when rendering a particular DOM element or View from a Meteor template.
elementOrView
DOM Element or Blaze.View Optional. An element that was rendered by a Meteor, or a View.
Blaze.toHTML(templateOrView)
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 693) Renders a template or View to a string of HTML.
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 ({{> myTemplate}}
) 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
).
Blaze.toHTMLWithData(templateOrView, data)
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 705) Renders a template or View to HTML with a data context. Otherwise identical to Blaze.toHTML
.
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.
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.
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 {{foo}}
or {{#if}}
— 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:
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”.
The enclosing View that caused this View to be rendered, if any.
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.
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.
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.
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.
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
.
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.
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.
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.
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.
The last node of the View’s rendered content.
See firstNode()
.
For Views created by invoking templates, the original Template object. For example, Blaze.render(Template.foo).template === Template.foo
.
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.
Blaze.currentView
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 527) 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.
Blaze.getView([element])
import { Blaze } from 'meteor/blaze'
(blaze/view.js, line 776) Gets either the current View, or the View enclosing the given DOM element.
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
.
Blaze.With(data, contentFunc)
import { Blaze } from 'meteor/blaze'
(blaze/builtins.js, line 13) Constructs a View that renders content with a data context.
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 {{#with}}
(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.
Blaze.If(conditionFunc, contentFunc, [elseFunc])
import { Blaze } from 'meteor/blaze'
(blaze/builtins.js, line 73) Constructs a View that renders content conditionally.
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 {{#if}}
in templates.
Blaze.Unless(conditionFunc, contentFunc, [elseFunc])
import { Blaze } from 'meteor/blaze'
(blaze/builtins.js, line 98) An inverted Blaze.If
.
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 {{#unless}}
in templates.
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.
argFunc
Function A function to reactively re-run. The function can return one of two options:
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.
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 {{#each}}
in templates.
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.
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:
Same as the constructor argument.
Same as the constructor argument.
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.
Blaze.isTemplate(value)
import { Blaze } from 'meteor/blaze'
(blaze/template.js, line 61) Returns true if value
is a template object like Template.myTemplate
.
value
Any The value to test.
A value is renderable content if it is one of the following:
Template.myTemplate
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.
© 2011–2017 Meteor Development Group, Inc.
Licensed under the MIT License.
http://blazejs.org/api/blaze.html