It'll be {{dstache}}prediction}} tonight
{{lt}}/template>
```
```js
// in client/myapp.js: reactive helper function
Template.forecast.helpers({
prediction: function () {
return Session.get("weather");
}
});
```
```js
// in the JavaScript console
> Session.set("weather", "cloudy");
> document.body.innerHTML
=> "Today's weather!
It'll be cloudy tonight
"
> Session.set("weather", "cool and dry");
> document.body.innerHTML
=> "Today's weather!
It'll be cool and dry tonight
"
```
To iterate over an array or database cursor, use `{{dstache}}#each}}`:
```html
{{dstache}}#each topScorers}}
{{dstache}}name}}
{{dstache}}/each}}
{{lt}}/template>
```
```js
// in myapp.js
Template.players.helpers({
topScorers: function () {
return Users.find({score: {$gt: 100}}, {sort: {score: -1}});
}
});
```
In this case, the data is coming from a database query. When the
database cursor is passed to `{{dstache}}#each}}`, it will wire up all of the
machinery to efficiently add and move DOM nodes as new results enter
the query.
Helpers can take arguments, and they receive the current template context data
in `this`. Note that some block helpers change the current context (notably
`{{dstache}}#each}}` and `{{dstache}}#with}}`):
```js
// in a JavaScript file
Template.players.helpers({
leagueIs: function (league) {
return this.league === league;
}
});
```
```html
{{dstache}}#each topScorers}}
{{dstache}}#if leagueIs "junior"}}
Junior: {{dstache}}name}}
{{dstache}}/if}}
{{dstache}}#if leagueIs "senior"}}
Senior: {{dstache}}name}}
{{dstache}}/if}}
{{dstache}}/each}}
{{lt}}/template>
```
Helpers can also be used to pass in constant data.
```js
// Works fine with {{dstache}}#each sections}}
Template.report.helpers({
sections: ["Situation", "Complication", "Resolution"]
});
```
Finally, you can use the `events` function on a template to attach
event handlers. The object passed into `events` is documented at
[Event Maps](#eventmaps). The `this` argument to the event handler will
be the data context of the element that triggered the event.
```html
{{dstache}}#each player}}
{{dstache}}> playerScore}}
{{dstache}}/each}}
{{lt}}/template>
{{dstache}}name}}: {{dstache}}score}}
Give points
{{lt}}/template>
```
```js
// myapp.js
Template.playerScore.events({
'click .give-points': function () {
Users.update(this._id, {$inc: {score: 2}});
}
});
```
For more details about Spacebars, read [the Spacebars
README](https://github.com/meteor/meteor/blob/devel/packages/spacebars/README.md).
{{/markdown}}
{{#markdown}}
Using packages
All of the functionality you've read about so far is implemented in standard
Meteor packages. This is possible thanks to Meteor's unusually powerful
isomorphic package and build system. Isomorphic means the same packages work in
the web browser, in mobile apps, and on the server. Packages can also contain
plugins that extend the build process, such as `coffeescript`
([CoffeeScript](http://coffeescript.org) compilation) or `templating` (compiling
HTML templates).
Anyone can publish a Meteor package, and thousands of community-written packages
have been published to date. The easiest way to browse these packages is
Atmosphere, by Percolate Studio.
You can also use the [`meteor search`](#meteorsearch) and
[`meteor show`](#meteorshow) commands.
You can add packages to your project with [`meteor add`](#meteoradd) and remove
them with [`meteor remove`](#meteorremove).
Additionally, [`meteor list`](#meteorlist) will tell you what
packages your project is using, and [`meteor update`](#meteorupdate)
will update them to the newest versions when possible.
By default all apps include the `meteor-platform` package. This
automatically pulls in the packages that make up the core Meteor
stack. If you want to build your own custom stack, just remove
`meteor-platform` from your app and add back in whichever of the standard
packages you want to keep.
Meteor uses a single-loading packaging system, meaning that it loads just one
version of every package. Before adding or upgrading to a particular version of
a package, Meteor uses a constraint solver to check if doing so will cause
other packages to break. By default, Meteor will choose conservatively. When
adding transitive dependencies (packages that other packages, but not the
application itself) depend on, Meteor will try to choose the earlier version.
In addition to the packages in the official Meteor release being used by your
app, `meteor list` and `meteor add` also search the `packages` directory at the
top of your app. You can also use the `packages` directory to break your app
into subpackages for your convenience, or to test packages that you might want
to publish. See [Writing Packages](#writingpackages).
{{/markdown}}
{{#markdown}}
Namespacing
Meteor's namespacing support makes it easy to write large applications
in JavaScript. Each package that you use in your app exists in its own
separate namespace, meaning that it sees only its own global variables
and any variables provided by the packages that it specifically
uses. Here's how it works.
When you declare a top-level variable, you have a choice. You can make
the variable File Scope or Package Scope.
// File Scope. This variable will be visible only inside this
// one file. Other files in this app or package won't see it.
var alicePerson = {name: "alice"};
// Package Scope. This variable is visible to every file inside
// of this package or app. The difference is that 'var' is
// omitted.
bobPerson = {name: "bob"};
Notice that this is just the normal JavaScript syntax for declaring a
variable that is local or global. Meteor scans your source code for
global variable assignments and generates a wrapper that makes sure
that your globals don't escape their appropriate namespace.
In addition to File Scope and Package Scope, there are also
Exports. An export is a variable that a package makes available to you
when you use it. For example, the `email` package exports the `Email`
variable. If your app uses the `email` package (and _only_ if it uses
the `email` package!) then your app can see `Email` and you can call
`Email.send`. Most packages have only one export, but some packages
might have two or three (for example, a package that provides several
classes that work together).
You see only the exports of the packages that you use directly. If you
use package A, and package A uses package B, then you only see package
A's exports. Package B's exports don't "leak" into your namespace just
because you used package A. This keeps each namespace nice and
tidy. Each app or package only sees their own globals plus the APIs of
the packages that they specifically asked for.
When debugging your app, your browser's JavaScript console behaves as
if it were attached to your app's namespace. You see your app's
globals and the exports of the packages that your app uses
directly. You don't see the variables from inside those packages, and
you don't see the exports of your transitive dependencies (packages
that aren't used directly by your app, but that are used by packages
that are used by your app).
If you want to look inside packages from inside your in-browser
debugger, you've got two options:
* Set a breakpoint inside package code. While stopped on that
breakpoint, the console will be in the package's namespace. You'll
see the package's package-scope variables, imports, and also any
file-scope variables for the file you're stopped in.
* If a package `foo` is included in your app, regardless of whether
your app uses it directly, its exports are available in
`Package.foo`. For example, if the `email` package is loaded, then
you can access `Package.email.Email.send` even from namespaces that
don't use the `email` package directly.
When declaring functions, keep in mind that `function x () {}` is just
shorthand for `var x = function x () {}` in JavaScript. Consider these
examples:
// This is the same as 'var x = function x () ...'. So x() is
// file-scope and can be called only from within this one file.
function x () { ... }
// No 'var', so x() is package-scope and can be called from
// any file inside this app or package.
x = function () { ... }
{{#note}}
Technically speaking, globals in an app (as opposed to in a package)
are actually true globals. They can't be captured in a scope that is
private to the app code, because that would mean that they wouldn't be
visible in the console during debugging! This means that app globals
actually end up being visible in packages. That should never be a
problem for properly written package code (since the app globals will
still be properly shadowed by declarations in the packages). You
certainly shouldn't depend on this quirk, and in the future Meteor may
check for it and throw an error if you do.
{{/note}}
{{/markdown}}
{{#markdown}}
Deploying
Meteor is a full application server. We include everything you need
to deploy your application on the internet: you just provide the JavaScript,
HTML, and CSS.
Running on Meteor's infrastructure
The easiest way to deploy your application is to use `meteor
deploy`. We provide it because it's what, personally, we've always
wanted: an easy way to take an app idea, flesh it out over a weekend,
and put it out there for the world to use, with nothing getting in the
way of creativity.
```bash
meteor deploy myapp.meteor.com
```
Your application is now available at myapp.meteor.com. If
this is the first time deploying to this hostname, Meteor creates a
fresh empty database for your application. If you want to deploy an
update, Meteor will preserve the existing data and just refresh the
code.
You can also deploy to your own domain. Just set up the hostname you
want to use as a CNAME to `origin.meteor.com`, then deploy to that name.
```bash
meteor deploy www.myapp.com
```
We provide this as a free service so you can try Meteor. It is also
helpful for quickly putting up internal betas, demos, and so on. For
more information, see [meteor deploy](#meteordeploy).
Running on your own infrastructure
You can also run your application on your own infrastructure or any
hosting provider that can run Node.js apps.
To get started, run
```bash
meteor build my_directory
```
This command will generate a fully-contained Node.js application in the form of
a tarball. To run this application, you need to provide Node.js 0.10 and a
MongoDB server. (The current release of Meteor has been tested with Node
0.10.36.) You can then run the application by invoking node, specifying the
HTTP port for the application to listen on, and the MongoDB endpoint.
```bash
cd my_directory
(cd programs/server && npm install)
env PORT=3000 MONGO_URL=mongodb://localhost:27017/myapp node main.js
```
Some packages might require other environment variables. For example,
the `email` package requires a `MAIL_URL` environment variable.
{{/markdown}}
{{#markdown}}
Writing packages
Writing Meteor packages is easy. To initialize a meteor package, run
`meteor create --package username:packagename`, where `username` is your Meteor
Developer username. This will create a package from scratch and prefill the
directory with a package.js control file and some javascript. By default, Meteor
will take the package name from the name of the directory that contains the
package.js file. Don't forget to run `meteor add [packagename]`, even if the
package is internal to the app, in order to use it.
Meteor promises repeatable builds for both packages and applications. This means
that, if you built your package on a machine, then checked the code into a
repository and checked it out elsewhere, you should get the same result. In your
package directory, you will find an automatically generated `.versions`
file. This file specifies the versions of all packages used to build your
package and is part of the source. Check it into version control to ensure
repeatable builds across machines.
{{#note}}
Sometimes, packages do not just stand on their own, but function in the context
of an app (specifically, packages in the packages directory of an app). In that
case, the app's context will take precedence. Rather than using the
`.versions` file as a guide, we will build the package with the same
dependencies as used by the app (we think that, in practice, it would be
confusing to find your local packages built with different versions of
things).
{{/note}}
Meteor uses extended semver versioning for its packages: that means that the version
number has three parts separated by dots: major version, minor version and patch version
(for example: 1.2.3) with an optional pre-release version. You can read more about it on
[semver.org](http://www.semver.org).
Additionally, because some meteor packages wrap external libraries,
Meteor supports the convention of using `_` to denote a wrap number.
You can read more about [`package.js`](#packagejs) files in the API
section.
A word on testing: since testing is an important part of the development process,
there are two common ways to test a package:
* Integration tests (putting a package directly into an application, and writing
tests against the application) is the most common way to test a package. After
creating your package, add it to your app's /packages directory and run `meteor
add`. This will add your package to your app as a local package. You can then
test and run your app as usual. Meteor will detect and respond to changes to
your local package, just as it does to your app files.
* Unit tests are run with the command [`meteor test-packages
package-name`](#meteortestpackages). As described in the [`package.js`](#packagejs)
section, you can use the `package.js` file to specify where your unit tests are
located. If you have a repository that contains only the package source, you can
test your package by specifying the path to the package directory (which must
contain a slash), such as `meteor test-packages ./`.
To publish a package, run [`meteor publish`](#meteorpublish) from the package
directory. There are some extra restrictions on published packages: they must
contain a version (Meteor packages are versioned using
strict semver versioning) and their names
must be prefixed with the username of the author and a colon, like so:
`iron:router`. This namespacing allows for more descriptive and on-topic package
names.
{{/markdown}}
`. This is the best place
for `favicon.ico`, `robots.txt`, and similar files.
- **private**
All files inside a top-level directory called `private` are only accessible
from server code and can be loaded via the [`Assets`](#assets) API. This can
be used for private data files and any files that are in your project
directory that you don't want to be accessible from the outside.
- **client/compatibility**
This folder is for compatibility JavaScript libraries that rely on variables
declared with var at the top level being exported as globals. Files in this
directory are executed without being wrapped in a new variable scope. These
files are executed before other client-side JavaScript files.
- **tests**
Any directory named `tests` is not loaded anywhere. Use this for any local
test code.
### Files outside special directories
All JavaScript files outside special directories are loaded on both the client
and the server. That's the place for model definitions and other functions.
Meteor provides the variables [`Meteor.isClient`](#meteor_isclient) and
[`Meteor.isServer`](#meteor_isserver) so that your code can alter its behavior
depending on whether it's running on the client or the server.
CSS and HTML files outside special directories are loaded on the client only,
and cannot be used from server code.
### Example File Structure
The file structure of your Meteor app is very flexible. Here is an example layout that takes advantage of some of the special folders mentioned above.
```bash
lib/ # common code like collections and utilities
lib/methods.js # Meteor.methods definitions
lib/constants.js # constants used in the rest of the code
client/compatibility # legacy libraries that expect to be global
client/lib/ # code for the client to be loaded first
client/lib/helpers.js # useful helpers for your client code
client/body.html # content that goes in the of your HTML
client/head.html # content for of your HTML: tags, etc
client/style.css # some CSS code
client/