diff --git a/docs/client/basic/sections/collections.md b/docs/client/basic/sections/collections.md index f3b19e4461..cccd7e1277 100644 --- a/docs/client/basic/sections/collections.md +++ b/docs/client/basic/sections/collections.md @@ -11,7 +11,7 @@ are called `documents`. To get started, declare a collection with Calling the `Mongo.Collection` constructor creates a collection object which acts just like a MongoDB collection. If you pass a name when you create the collection, then you are declaring a persistent collection -— one that is stored on the server and seen by all users. +— one that is stored on the server and can be published to clients. To allow both client code and server code to access the same collection using the same API, it's usually best to declare collections as global @@ -105,9 +105,9 @@ or a [`Tracker.autorun`](#tracker_autorun) callback, it will automatically rerender the view or rerun the computation if the returned document changes. -Note that `findOne` will return `null` if it fails to find a matching -document, which often happens after the document has been removed from the -collection, so you should be prepared to handle `null` values. +Note that `findOne` will return `null` if it fails to find a matching document, +which often happens if the document hasn't been loaded yet or has been removed +from the collection, so you should be prepared to handle `null` values. {{> autoApiBox "Mongo.Collection#find"}} diff --git a/docs/client/basic/sections/templates.md b/docs/client/basic/sections/templates.md index 20f536ae01..721ed0ee87 100644 --- a/docs/client/basic/sections/templates.md +++ b/docs/client/basic/sections/templates.md @@ -2,9 +2,9 @@

Templates

-In Meteor, you define your views in _templates_. A template is a snippet of -HTML that can also include special pieces of code to include data and change -which parts of the page are displayed. +In Meteor, views are defined in _templates_. A template is a snippet of HTML +that can include dynamic data. You can also interact with your templates from +JavaScript code to insert data and listen to events.

Defining Templates in HTML

@@ -36,7 +36,7 @@ templates is to avoid writing the same HTML multiple times by hand. ``` -The `{{dstache}} ... }}` syntax is part of a language called "Spacebars" that +The `{{dstache}} ... }}` syntax is part of a language called Spacebars that Meteor uses to add functionality to HTML. As shown above, it lets you include templates in other parts of your page. Using Spacebars, you can also display data obtained from _helpers_. Helpers are written in JavaScript, and can be @@ -120,12 +120,34 @@ Now, each time you use the `username` helper, the helper function above will be called to determine the user's name: ``` -// in your HTML + ``` +Helpers can also take arguments. For example, here's a helper that pluralizes +a word: + +```js +Template.post.helpers({ + commentCount: function (numComments) { + if (numComments === 1) { + return "1 comment"; + } else { + return numComments + " comments"; + } + } +}); +``` + +Pass in arguments by putting them inside the curly braces after the name of the +helper: + +```html +

There are {{dstache}}commentCount 3}} comments.

+``` + The helpers above have all been associated with specific templates, but you can also make a helper available in all templates by using [`Template.registerHelper`](#template_registerhelper). @@ -139,19 +161,22 @@ to your templates. {{> autoApiBox "Template#events"}} -The event map passed into `Template.myTemplate.events` has event -descriptors as its keys and event handler functions as the values. Event -handlers get two arguments: the event object and the template instance. +The event map passed into `Template.myTemplate.events` has event descriptors as +its keys and event handler functions as the values. Event handlers get two +arguments: the event object and the template instance. Event handlers can also +access the data context of the target element in `this`. To attach event handlers to the following template ``` ``` @@ -164,7 +189,8 @@ Template.example.events({ }, "submit form": function (event, template) { var inputValue = event.target.myInput.value; - alert(inputValue); + var helperValue = this; + alert(inputValue, helperValue); } }); ``` @@ -174,7 +200,7 @@ event being captured. Pretty much any DOM event is supported. Some common ones are: `click`, `mousedown`, `mouseup`, `mouseenter`, `mouseleave`, `keydown`, `keyup`, `keypress`, `focus`, `blur`, and `change`. -The second part of the key (after the first space) is a selector that +The second part of the key (after the first space) is a CSS selector that indicates which elements to listen to. This can be almost any selector [supported by JQuery](http://api.jquery.com/category/selectors/). @@ -187,7 +213,7 @@ for details. {{> autoApiBox "Template#rendered"}} The function assigned to this property is called once for every instance of -*Template.myTemplate* when it is inserted into the document for the first time. +*Template.myTemplate* when it is inserted into the page for the first time. This _rendered_ callback can be used to integrate external libraries that aren't familiar with Meteor's automatic view rendering, and need to be initialized @@ -217,8 +243,8 @@ rendered HTML.

Template instances

A template instance object represents a single inclusion of a template in the -document. It can be used to access the DOM and it can be assigned properties -that persist as the template is reactively updated. +document. It can be used to access the HTML elements inside the template and it +can be assigned properties that persist as the template is reactively updated. Template instance objects can be found in several places: @@ -237,15 +263,14 @@ to perform initialization or clean-up. {{> autoApiBox "Blaze.TemplateInstance#findAll"}} `template.findAll` returns an array of DOM elements matching `selector`. You can -also use `template.$`, which works exactly like JQuery but only returns elements -within `template`. +also use `template.$`, which works exactly like the JQuery `$` function but only +returns elements within `template`. {{> autoApiBox "Blaze.TemplateInstance#find"}} -Get one DOM element matching `selector`, or `null` if there are no -such elements. Like `findAll`, `find` only returns elements from inside the -template. +`find` is just like `findAll` but only returns the first element found. Like +`findAll`, `find` only returns elements from inside the template. {{/template}} diff --git a/docs/client/basic/sections/tracker.md b/docs/client/basic/sections/tracker.md index e083722039..16adf697ed 100644 --- a/docs/client/basic/sections/tracker.md +++ b/docs/client/basic/sections/tracker.md @@ -3,15 +3,14 @@

Tracker

Meteor has a simple dependency tracking system which allows it to -automatically rerun templates and other computations whenever +automatically rerun templates and other functions whenever [`Session`](#session) variables, database queries, and other data sources change. Unlike most other systems, you don't have to manually declare these dependencies — it "just works." The mechanism is simple and efficient. Once you've -initialized a computation with `Tracker.autorun`, whenever you call a function -that supports reactive updates, `Tracker` automatically records which data were -accessed. Later, when those data change, the computation is rerun automatically. +initialized a computation with `Tracker.autorun`, whenever you call a Meteor function that returns data, `Tracker` automatically records which data were +accessed. Later, when this data changes, the computation is rerun automatically. This is how a template knows how to re-render whenever its [helper functions](#template_helpers) have new data to return. diff --git a/docs/client/common/principles.md b/docs/client/common/principles.md index ceb5112823..45090da8e0 100644 --- a/docs/client/common/principles.md +++ b/docs/client/common/principles.md @@ -11,8 +11,7 @@ application in JavaScript. - _Database Everywhere_. You can use the same methods to access your database from the client or the server. -- _Latency Compensation_. On the client, Meteor does prefetching and model -simulation to make it look like server method calls return instantly. +- _Latency Compensation_. On the client, Meteor prefetches data and simulates models to make it look like server method calls return instantly. - _Full Stack Reactivity_. In Meteor, realtime is the default. All layers, from database to template, update themselves automatically when necessary.