mirror of
https://github.com/meteor/meteor.git
synced 2026-05-02 03:01:46 -04:00
a bunch of updates to Templates api section
This commit is contained in:
David Glasser
@@ -2011,11 +2011,19 @@ Example:
|
||||
|
||||
<h2 id="templates_api"><span>Templates</span></h2>
|
||||
|
||||
A template that you declare as `<{{! }}template name="foo"> ... <{{!
|
||||
}}/template>` can be accessed as the function `Template.foo`,
|
||||
which returns a string of HTML when called.
|
||||
|
||||
The same template may occur many times on the page, and these
|
||||
When you write a template as `<{{! }}template name="foo"> ... <{{!
|
||||
}}/template>` in an HTML file in your app, Meteor generates a
|
||||
"component object" named `Template.foo`.
|
||||
|
||||
{{#note}}
|
||||
Meteor's component API is currently in flux. This section documents a few
|
||||
features of the component object that are useful for writing apps; a future
|
||||
release will elaborate more about how components work and about how to build
|
||||
components that aren't just template.
|
||||
{{/note}}
|
||||
|
||||
The same template may occur many times on a page, and these
|
||||
occurrences are called template instances. Template instances have a
|
||||
life cycle of being created, put into the document, and later taken
|
||||
out of the document and destroyed. Meteor manages these stages for
|
||||
@@ -2024,61 +2032,6 @@ or replaced and should be cleaned up. You can associate data with a
|
||||
template instance, and you can access its DOM nodes when it is in the
|
||||
document.
|
||||
|
||||
Additionally, Meteor will maintain a template instance and its state
|
||||
even if its surrounding HTML is re-rendered into new DOM nodes. As
|
||||
long as the structure of template invocations is the same, Meteor will
|
||||
not consider any instances to have been created or destroyed. You can
|
||||
request that the same DOM nodes be retained as well using `preserve`
|
||||
and `constant`.
|
||||
|
||||
There are a number of callbacks and directives that you can specify on
|
||||
a named template and that apply to all instances of the template.
|
||||
They are described below.
|
||||
|
||||
{{> api_box template_call}}
|
||||
|
||||
When called inside a template helper, the body of `Meteor.render`, or
|
||||
other settings where reactive HTML is being generated, the resulting
|
||||
HTML is annotated so that it renders as reactive DOM elements.
|
||||
Otherwise, the HTML is unadorned and static.
|
||||
|
||||
|
||||
{{> api_box template_rendered}}
|
||||
|
||||
This callback is called once when an instance of Template.*myTemplate* is
|
||||
rendered into DOM nodes and put into the document for the first time, and again
|
||||
each time any part of the template is re-rendered.
|
||||
|
||||
In the body of the callback, `this` is a [template
|
||||
instance](#template_inst) object that is unique to this occurrence of
|
||||
the template and persists across re-renderings. Use the `created` and
|
||||
`destroyed` callbacks to perform initialization or clean-up on the
|
||||
object.
|
||||
|
||||
{{> api_box template_created}}
|
||||
|
||||
This callback is called when an invocation of *myTemplate* represents
|
||||
a new occurrence of the template and not a re-rendering of an existing
|
||||
template instance. Inside the callback, `this` is the new [template
|
||||
instance](#template_inst) object. Properties you set on this object
|
||||
will be visible from the `rendered` and `destroyed` callbacks and from
|
||||
event handlers.
|
||||
|
||||
This callback fires once and is the first callback to fire. Every
|
||||
`created` has a corresponding `destroyed`; that is, if you get a
|
||||
`created` callback with a certain template instance object in `this`,
|
||||
you will eventually get a `destroyed` callback for the same object.
|
||||
|
||||
{{> api_box template_destroyed}}
|
||||
|
||||
This callback is called when an occurrence of a template is taken off
|
||||
the page for any reason and not replaced with a re-rendering. Inside
|
||||
the callback, `this` is the [template instance](#template_inst) object
|
||||
being destroyed.
|
||||
|
||||
This callback is most useful for cleaning up or undoing any external
|
||||
effects of `created`. It fires once and is the last callback to fire.
|
||||
|
||||
|
||||
{{> api_box template_events}}
|
||||
|
||||
@@ -2101,31 +2054,81 @@ Example:
|
||||
}
|
||||
});
|
||||
|
||||
In Handlebars, this helper would then be invoked as `{{dstache}}foo}}`.
|
||||
Now you can invoke this helper with `{{dstache}}foo}}` in the template defined
|
||||
with `<{{! }}template name="myTemplate">`.
|
||||
|
||||
The following syntax is equivalent, but won't work for reserved property
|
||||
names:
|
||||
The following syntax is a shorthand for when you only have one helper to define:
|
||||
|
||||
Template.myTemplate.foo = function () {
|
||||
return Session.get("foo");
|
||||
};
|
||||
|
||||
|
||||
|
||||
{{> api_box template_rendered}}
|
||||
|
||||
This callback is called once when an instance of Template.*myTemplate* is
|
||||
rendered into DOM nodes and put into the document for the first time.
|
||||
|
||||
In the body of the callback, `this` is a [template
|
||||
instance](#template_inst) object that is unique to this occurrence of
|
||||
the template and persists across re-renderings. Use the `created` and
|
||||
`destroyed` callbacks to perform initialization or clean-up on the
|
||||
object.
|
||||
|
||||
Because your template has been rendered, you can use functions like
|
||||
`this.findAll` which look at its DOM nodes.
|
||||
|
||||
{{> api_box template_created}}
|
||||
|
||||
This callback is called before your template's logic is evaluated for the first
|
||||
time. Inside the callback, `this` is the new [template
|
||||
instance](#template_inst) object. Properties you set on this object will be
|
||||
visible from the `rendered` and `destroyed` callbacks and from event handlers.
|
||||
|
||||
This callback fires once and is the first callback to fire. Every
|
||||
`created` has a corresponding `destroyed`; that is, if you get a
|
||||
`created` callback with a certain template instance object in `this`,
|
||||
you will eventually get a `destroyed` callback for the same object.
|
||||
|
||||
{{#note}}
|
||||
The `created` callback is not currently very useful. In a later release, the
|
||||
template instance object (or something like it) will be visible from helper
|
||||
functions, and `created` will be a useful way to set up values that are read
|
||||
from helpers. For now, you probably just want to use `rendered`.
|
||||
{{/note}}
|
||||
|
||||
{{> api_box template_destroyed}}
|
||||
|
||||
This callback is called when an occurrence of a template is taken off
|
||||
the page for any reason and not replaced with a re-rendering. Inside
|
||||
the callback, `this` is the [template instance](#template_inst) object
|
||||
being destroyed.
|
||||
|
||||
This callback is most useful for cleaning up or undoing any external effects of
|
||||
`created` or `rendered`. It fires once and is the last callback to fire.
|
||||
|
||||
|
||||
<h2 id="template_inst"><span>Template instances</span></h2>
|
||||
|
||||
A template instance object represents an occurrence of a template in
|
||||
the document. It can be used to access the DOM and it can be
|
||||
assigned properties that persist across page re-renderings.
|
||||
assigned properties that persist as the template is reactively updated.
|
||||
|
||||
Template instance objects are found as the value of `this` in the
|
||||
`created`, `rendered`, and `destroyed` template callbacks and as an
|
||||
`created`, `rendered`, and `destroyed` template callbacks, and as an
|
||||
argument to event handlers.
|
||||
|
||||
In addition to the properties and functions described below, you can
|
||||
assign additional properties of your choice to the object. Property names
|
||||
starting with `_` are guaranteed to be available for your use. Use
|
||||
the `created` and `destroyed` callbacks to perform initialization or
|
||||
clean-up on the object.
|
||||
{{#note}}
|
||||
You cannot currently access the template instance object from helpers.
|
||||
We plan to refactor how template instances work and make them more
|
||||
universally accessible.
|
||||
{{/note}}
|
||||
|
||||
In addition to the properties and functions described below, you can assign
|
||||
additional properties of your choice to the object. Use the
|
||||
[`created`](#template_created) and [`destroyed`](#template_destroyed) callbacks
|
||||
to perform initialization or clean-up on the object.
|
||||
|
||||
You can only access `findAll`, `find`, `firstNode`, and `lastNode`
|
||||
from the `rendered` callback and event handlers, not from `created`
|
||||
@@ -2134,7 +2137,11 @@ in the DOM.
|
||||
|
||||
{{> api_box template_findAll}}
|
||||
|
||||
Returns an array of DOM elements matching `selector`.
|
||||
Returns a [jQuery object](http://api.jquery.com/Types/#jQuery) of DOM elements
|
||||
matching `selector`. This object is similar to an array but has other methods
|
||||
defined by the jQuery library.
|
||||
|
||||
You can also call this function as `this.$(selector)`.
|
||||
|
||||
The template instance serves as the document root for the selector. Only
|
||||
elements inside the template and its sub-templates can match parts of
|
||||
@@ -2195,8 +2202,8 @@ information about the event, and `template`, a [template
|
||||
instance](#template_inst) for the template where the handler is
|
||||
defined. The handler also receives some additional context data in
|
||||
`this`, depending on the context of the current element handling the
|
||||
event. In a Handlebars template, an element's context is the
|
||||
Handlebars data context where that element occurs, which is set by
|
||||
event. In a template, an element's context is the
|
||||
data context where that element occurs, which is set by
|
||||
block helpers such as `#with` and `#each`.
|
||||
|
||||
Example:
|
||||
@@ -2328,11 +2335,6 @@ catching typing in text fields, while `keydown` and `keyup` can be
|
||||
used for arrow keys or modifier keys.
|
||||
{{/dtdd}}
|
||||
|
||||
{{#dtdd "<code>tap</code>"}} Tap on an element. On touch-enabled
|
||||
devices, this is a replacement to `click` that fires immediately.
|
||||
These events are synthesized from `touchmove` and `touchend`.
|
||||
{{/dtdd}}
|
||||
|
||||
</dl>
|
||||
|
||||
Other DOM events are available as well, but for the events above,
|
||||
|
||||
@@ -1746,19 +1746,6 @@ Template.api.http_del = {
|
||||
};
|
||||
|
||||
|
||||
// XXX move these up to right place
|
||||
Template.api.template_call = {
|
||||
id: "template_call",
|
||||
name: "Template.<em>myTemplate</em>([data])",
|
||||
locus: "Client",
|
||||
descr: ["Call a template function by name to produce HTML."],
|
||||
args: [
|
||||
{name: "data",
|
||||
type: "Object",
|
||||
descr: 'Optional. The data context object with which to call the template.'}
|
||||
]
|
||||
};
|
||||
|
||||
Template.api.template_rendered = {
|
||||
id: "template_rendered",
|
||||
name: "Template.<em>myTemplate</em>.rendered = function ( ) { ... }",
|
||||
|
||||
@@ -232,12 +232,12 @@ var toc = [
|
||||
],
|
||||
|
||||
{name: "Templates", id: "templates_api"}, [
|
||||
{prefix: "Template", instance: "myTemplate", id: "template_call"}, [
|
||||
{prefix: "Template", instance: "myTemplate", id: "templates_api"}, [
|
||||
{name: "events", id: "template_events"},
|
||||
{name: "helpers", id: "template_helpers"},
|
||||
{name: "rendered", id: "template_rendered"},
|
||||
{name: "created", id: "template_created"},
|
||||
{name: "destroyed", id: "template_destroyed"},
|
||||
{name: "events", id: "template_events"},
|
||||
{name: "helpers", id: "template_helpers"}
|
||||
{name: "destroyed", id: "template_destroyed"}
|
||||
],
|
||||
{name: "Template instances", id: "template_inst"}, [
|
||||
{instance: "this", name: "findAll", id: "template_findAll"},
|
||||
|
||||
Reference in New Issue
Block a user