diff --git a/docs/client/api.html b/docs/client/api.html index d0011432e4..7b982a1530 100644 --- a/docs/client/api.html +++ b/docs/client/api.html @@ -2011,11 +2011,19 @@ Example:

Templates

-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. + +

Template instances

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 "tap"}} 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}} - Other DOM events are available as well, but for the events above, diff --git a/docs/client/api.js b/docs/client/api.js index 8e74f8d47a..6135eede92 100644 --- a/docs/client/api.js +++ b/docs/client/api.js @@ -1746,19 +1746,6 @@ Template.api.http_del = { }; -// XXX move these up to right place -Template.api.template_call = { - id: "template_call", - name: "Template.myTemplate([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.myTemplate.rendered = function ( ) { ... }", diff --git a/docs/client/docs.js b/docs/client/docs.js index 35db9c03dd..6af0e15408 100644 --- a/docs/client/docs.js +++ b/docs/client/docs.js @@ -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"},