DDPRateLimiter

DDPRateLimiter

Customize rate limiting for methods and subscriptions.

By default, DDPRateLimiter is configured with a single rule. This rule limits login attempts, new user creation, and password resets to 5 attempts every 10 seconds per connection. It can be removed by calling Accounts.removeDefaultRateLimit().

Custom rules can be added by calling DDPRateLimiter.addRule. The rate limiter is called on every method and subscription invocation.

A rate limit is reached when a bucket has surpassed the rule's predefined capactiy, at which point errors will be returned for that input until the buckets are reset. Buckets are regularly reset after the end of a time interval.

Here's example of defining a rule and adding it into the DDPRateLimiter:

// Define a rule that matches login attempts by non-admin users
var loginRule = {
  userId: function (userId) {
    return Meteor.users.findOne(userId).type !== 'Admin';
  },
  type: 'method',
  name: 'login'
}
// Add the rule, allowing up to 5 messages every 1000 milliseconds.
DDPRateLimiter.addRule(loginRule, 5, 1000);

Check

The check package includes pattern checking functions useful for checking the types and structure of variables and an extensible library of patterns to specify which types you are expecting.

Meteor methods and publish functions can take arbitrary EJSON types as arguments, but most functions expect their arguments to be of a particular type. check is a lightweight function for checking that arguments and other values are of the expected type. For example:

Meteor.publish("chats-in-room", function (roomId) {
  // Make sure roomId is a string, not an arbitrary mongo selector object.
  check(roomId, String);
  return Chats.find({room: roomId});
});

Meteor.methods({addChat: function (roomId, message) {
  check(roomId, String);
  check(message, {
    text: String,
    timestamp: Date,
    // Optional, but if present must be an array of strings.
    tags: Match.Maybe([String])
  });

  // ... do something with the message ...
}});

If the match fails, check throws a Match.Error describing how it failed. If this error gets sent over the wire to the client, it will appear only as Meteor.Error(400, "Match Failed"). The failure details will be written to the server logs but not revealed to the client.

Match.test can be used to identify if a variable has a certain structure.

// will return true for {foo: 1, bar: "hello"} or similar
Match.test(value, {foo: Match.Integer, bar: String});

// will return true if value is a string
Match.test(value, String);

// will return true if value is a String or an array of Numbers
Match.test(value, Match.OneOf(String, [Number]));

This can be useful if you have a function that accepts several different kinds of objects, and you want to determine which was passed in.

Match Patterns

The following patterns can be used as pattern arguments to check and Match.test:

Match.Any

Matches any value.

String, Number, Boolean, undefined, null

Matches a primitive of the given type.

Match.Integer

Matches a signed 32-bit integer. Doesn't match Infinity, -Infinity, or NaN.

[pattern]

A one-element array matches an array of elements, each of which match pattern. For example, [Number] matches a (possibly empty) array of numbers; [Match.Any] matches any array.

{key1: pattern1, key2: pattern2, ...}

Matches an Object with the given keys, with values matching the given patterns. If any pattern is a Match.Maybe or Match.Optional, that key does not need to exist in the object. The value may not contain any keys not listed in the pattern. The value must be a plain Object with no special prototype.

Match.ObjectIncluding({key1: pattern1, key2: pattern2, ...})

Matches an Object with the given keys; the value may also have other keys with arbitrary values.

Object

Matches any plain Object with any keys; equivalent to Match.ObjectIncluding({}).

Match.Maybe(pattern)

Matches either undefined, null, or pattern. If used in an object, matches only if the key is not set as opposed to the value being set to undefined or null. This set of conditions was chosen because undefined arguments to Meteor Methods are converted to null when sent over the wire.

// In an object
var pattern = { name: Match.Maybe(String) };
check({ name: "something" }, pattern) // OK
check({}, pattern) // OK
check({ name: undefined }, pattern) // Throws an exception
check({ name: null }, pattern) // Throws an exception

// Outside an object
check(null, Match.Maybe(String)); // OK
check(undefined, Match.Maybe(String)); // OK

Match.Optional(pattern)

Behaves like Match.Maybe except it doesn't accept null. If used in an object, the behavior is identical to Match.Maybe.

Match.OneOf(pattern1, pattern2, ...)

Matches any value that matches at least one of the provided patterns.

Any constructor function (eg, Date)

Matches any element that is an instance of that type.

Match.Where(condition)

Calls the function condition with the value as the argument. If condition returns true, this matches. If condition throws a Match.Error or returns false, this fails. If condition throws any other error, that error is thrown from the call to check or Match.test. Examples:

check(buffer, Match.Where(EJSON.isBinary));

NonEmptyString = Match.Where(function (x) {
  check(x, String);
  return x.length > 0;
});
check(arg, NonEmptyString);

Server connections

These functions manage and inspect the network connection between the Meteor client and server.

This method returns the status of the connection between the client and the server. The return value is an object with the following fields:

connected Boolean

True if currently connected to the server. If false, changes and method invocations will be queued up until the connection is reestablished.

status String

Describes the current reconnection status. The possible values are connected (the connection is up and running), connecting (disconnected and trying to open a new connection), failed (permanently failed to connect; e.g., the client and server support different versions of DDP), waiting (failed to connect and waiting to try to reconnect) and offline (user has disconnected the connection).

retryCount Number

The number of times the client has tried to reconnect since the connection was lost. 0 when connected.

retryTime Number or undefined

The estimated time of the next reconnection attempt. To turn this into an interval until the next reconnection, use retryTime - (new Date()).getTime(). This key will be set only when status is waiting.

reason String or undefined

If status is failed, a description of why the connection failed.

Instead of using callbacks to notify you on changes, this is a reactive data source. You can use it in a template or computation to get realtime updates.

Call this method to disconnect from the server and stop all live data updates. While the client is disconnected it will not receive updates to collections, method calls will be queued until the connection is reestablished, and hot code push will be disabled.

Call Meteor.reconnect to reestablish the connection and resume data transfer.

This can be used to save battery on mobile devices when real time updates are not required.

onConnection returns an object with a single method stop. Calling stop unregisters the callback, so that this callback will no longer be called on new connections.

The callback is called with a single argument, the server-side connection representing the connection from the client. This object contains the following fields:

id String

A globally unique id for this connection.

close Function

Close this DDP connection. The client is free to reconnect, but will receive a different connection with a new id if it does.

onClose Function

Register a callback to be called when the connection is closed. If the connection is already closed, the callback will be called immediately.

clientAddress String

The IP address of the client in dotted form (such as "127.0.0.1").

If you're running your Meteor server behind a proxy (so that clients are connecting to the proxy instead of to your server directly), you'll need to set the HTTP_FORWARDED_COUNT environment variable for the correct IP address to be reported by clientAddress.

Set HTTP_FORWARDED_COUNT to an integer representing the number of proxies in front of your server. For example, you'd set it to "1" when your server was behind one proxy.

httpHeaders Object

When the connection came in over an HTTP transport (such as with Meteor's default SockJS implementation), this field contains whitelisted HTTP headers.

Cookies are deliberately excluded from the headers as they are a security risk for this transport. For details and alternatives, see the SockJS documentation.

To call methods on another Meteor application or subscribe to its data sets, call DDP.connect with the URL of the application. DDP.connect returns an object which provides:

• subscribe - Subscribe to a record set. See Meteor.subscribe.
• call - Invoke a method. See Meteor.call.
• apply - Invoke a method with an argument array. See Meteor.apply.
• methods - Define client-only stubs for methods defined on the remote server. See Meteor.methods.
• status - Get the current connection status. See Meteor.status.
• reconnect - See Meteor.reconnect.
• disconnect - See Meteor.disconnect.
• onReconnect - Set this to a function to be called as the first step of reconnecting. This function can call methods which will be executed before any other outstanding methods. For example, this can be used to re-establish the appropriate authentication context on the new connection.

By default, clients open a connection to the server from which they're loaded. When you call Meteor.subscribe, Meteor.status, Meteor.call, and Meteor.apply, you are using a connection back to that default server.

Collections

Meteor stores data in collections. To get started, declare a collection with new Mongo.Collection.

Calling this function is analogous to declaring a model in a traditional ORM (Object-Relation Mapper)-centric framework. It sets up a collection (a storage space for records, or "documents") that can be used to store a particular type of information, like users, posts, scores, todo items, or whatever matters to your application. Each document is a EJSON object. It includes an _id property whose value is unique in the collection, which Meteor will set when you first create the document.

// common code on client and server declares a DDP-managed mongo
// collection.
Chatrooms = new Mongo.Collection("chatrooms");
Messages = new Mongo.Collection("messages");

The function returns an object with methods to insert documents in the collection, update their properties, and remove them, and to find the documents in the collection that match arbitrary criteria. The way these methods work is compatible with the popular Mongo database API. The same database API works on both the client and the server (see below).

// return array of my messages
var myMessages = Messages.find({userId: Session.get('myUserId')}).fetch();

// create a new message
Messages.insert({text: "Hello, world!"});

// mark my first message as "important"
Messages.update(myMessages[0]._id, {$set: {important: true}});

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. Client code and server code can both access the same collection using the same API.

Specifically, when you pass a name, here's what happens:

• On the server (if you do not specify a connection), a collection with that name is created on a backend Mongo server. When you call methods on that collection on the server, they translate directly into normal Mongo operations (after checking that they match your access control rules).

• On the client (and on the server if you specify a connection), a Minimongo instance is created. Minimongo is essentially an in-memory, non-persistent implementation of Mongo in pure JavaScript. It serves as a local cache that stores just the subset of the database that this client is working with. Queries (find) on these collections are served directly out of this cache, without talking to the server.

• When you write to the database on the client (insert, update, remove), the command is executed locally immediately, and, simultaneously, it's sent to the server and executed there too. This happens via stubs, because writes are implemented as methods.

If you pass null as the name, then you're creating a local collection. It's not synchronized anywhere; it's just a local scratchpad that supports Mongo-style find, insert, update, and remove operations. (On both the client and the server, this scratchpad is implemented using Minimongo.)

By default, Meteor automatically publishes every document in your collection to each connected client. To turn this behavior off, remove the autopublish package, in your terminal:

meteor remove autopublish

and instead call Meteor.publish to specify which parts of your collection should be published to which users.

// Create a collection called Posts and put a document in it. The
// document will be immediately visible in the local copy of the
// collection. It will be written to the server-side database
// a fraction of a second later, and a fraction of a second
// after that, it will be synchronized down to any other clients
// that are subscribed to a query that includes it (see
// Meteor.subscribe and autopublish)
Posts = new Mongo.Collection("posts");
Posts.insert({title: "Hello world", body: "First post"});

// Changes are visible immediately -- no waiting for a round trip to
// the server.
assert(Posts.find().count() === 1);

// Create a temporary, local collection. It works just like any other
// collection, but it doesn't send changes to the server, and it
// can't receive any data from subscriptions.
Scratchpad = new Mongo.Collection;
for (var i = 0; i < 10; i++)
  Scratchpad.insert({number: i * 2});
assert(Scratchpad.find({number: {$lt: 9}}).count() === 5);

Generally, you'll assign Mongo.Collection objects in your app to global variables. You can only create one Mongo.Collection object for each underlying Mongo collection.

If you specify a transform option to the Collection or any of its retrieval methods, documents are passed through the transform function before being returned or passed to callbacks. This allows you to add methods or otherwise modify the contents of your collection from their database representation. You can also specify transform on a particular find, findOne, allow, or deny call. Transform functions must return an object and they may not change the value of the document's _id field (though it's OK to leave it out).

// An Animal class that takes a document in its constructor
Animal = function (doc) {
  _.extend(this, doc);
};
_.extend(Animal.prototype, {
  makeNoise: function () {
    console.log(this.sound);
  }
});

// Define a Collection that uses Animal as its document
Animals = new Mongo.Collection("Animals", {
  transform: function (doc) { return new Animal(doc); }
});

// Create an Animal and call its makeNoise method
Animals.insert({name: "raptor", sound: "roar"});
Animals.findOne({name: "raptor"}).makeNoise(); // prints "roar"

transform functions are not called reactively. If you want to add a dynamically changing attribute to an object, do it with a function that computes the value at the time it's called, not by computing the attribute at transform time.

Read more about collections and how to use them in the Collections article in the Meteor Guide.

find returns a cursor. It does not immediately access the database or return documents. Cursors provide fetch to return all matching documents, map and forEach to iterate over all matching documents, and observe and observeChanges to register callbacks when the set of matching documents changes.

Cursors are a reactive data source. On the client, the first time you retrieve a cursor's documents with fetch, map, or forEach inside a reactive computation (eg, a template or autorun), Meteor will register a dependency on the underlying data. Any change to the collection that changes the documents in a cursor will trigger a recomputation. To disable this behavior, pass {reactive: false} as an option to find.

Note that when fields are specified, only changes to the included fields will trigger callbacks in observe, observeChanges and invalidations in reactive computations using this cursor. Careful use of fields allows for more fine-grained reactivity for computations that don't depend on an entire document.

Equivalent to find(selector, options).fetch()[0] with options.limit = 1.

Add a document to the collection. A document is just an object, and its fields can contain any combination of EJSON-compatible datatypes (arrays, objects, numbers, strings, null, true, and false).

insert will generate a unique ID for the object you pass, insert it in the database, and return the ID. When insert is called from untrusted client code, it will be allowed only if passes any applicable allow and deny rules.

On the server, if you don't provide a callback, then insert blocks until the database acknowledges the write, or throws an exception if something went wrong. If you do provide a callback, insert still returns the ID immediately. Once the insert completes (or fails), the callback is called with error and result arguments. In an error case, result is undefined. If the insert is successful, error is undefined and result is the new document ID.

On the client, insert never blocks. If you do not provide a callback and the insert fails on the server, then Meteor will log a warning to the console. If you provide a callback, Meteor will call that function with error and result arguments. In an error case, result is undefined. If the insert is successful, error is undefined and result is the new document ID.

Example:

var groceriesId = Lists.insert({name: "Groceries"});
Items.insert({list: groceriesId, name: "Watercress"});
Items.insert({list: groceriesId, name: "Persimmons"});

Modify documents that match selector according to modifier (see modifier documentation).

The behavior of update differs depending on whether it is called by trusted or untrusted code. Trusted code includes server code and method code. Untrusted code includes client-side code such as event handlers and a browser's JavaScript console.

• Trusted code can modify multiple documents at once by setting multi to true, and can use an arbitrary Mongo selector to find the documents to modify. It bypasses any access control rules set up by allow and deny. The number of affected documents will be returned from the update call if you don't pass a callback.

• Untrusted code can only modify a single document at once, specified by its _id. The modification is allowed only after checking any applicable allow and deny rules. The number of affected documents will be returned to the callback. Untrusted code cannot perform upserts, except in insecure mode.

On the server, if you don't provide a callback, then update blocks until the database acknowledges the write, or throws an exception if something went wrong. If you do provide a callback, update returns immediately. Once the update completes, the callback is called with a single error argument in the case of failure, or a second argument indicating the number of affected documents if the update was successful.

On the client, update never blocks. If you do not provide a callback and the update fails on the server, then Meteor will log a warning to the console. If you provide a callback, Meteor will call that function with an error argument if there was an error, or a second argument indicating the number of affected documents if the update was successful.

Client example:

// When the givePoints button in the admin dashboard is pressed,
// give 5 points to the current player. The new score will be
// immediately visible on everyone's screens.
Template.adminDashboard.events({
  'click .givePoints': function () {
    Players.update(Session.get("currentPlayer"), {$inc: {score: 5}});
  }
});

Server example:

// Give the "Winner" badge to each user with a score greater than
// 10. If they are logged in and their badge list is visible on the
// screen, it will update automatically as they watch.
Meteor.methods({
  declareWinners: function () {
    Players.update({score: {$gt: 10}},
                   {$addToSet: {badges: "Winner"}},
                   {multi: true});
  }
});

You can use update to perform a Mongo upsert by setting the upsert option to true. You can also use the upsert method to perform an upsert that returns the _id of the document that was inserted (if there was one) in addition to the number of affected documents.

Modify documents that match selector according to modifier, or insert a document if no documents were modified. upsert is the same as calling update with the upsert option set to true, except that the return value of upsert is an object that contain the keys numberAffected and insertedId. (update returns only the number of affected documents.)

Find all of the documents that match selector and delete them from the collection.

The behavior of remove differs depending on whether it is called by trusted or untrusted code. Trusted code includes server code and method code. Untrusted code includes client-side code such as event handlers and a browser's JavaScript console.

• Trusted code can use an arbitrary Mongo selector to find the documents to remove, and can remove more than one document at once by passing a selector that matches multiple documents. It bypasses any access control rules set up by allow and deny. The number of removed documents will be returned from remove if you don't pass a callback.

  As a safety measure, if selector is omitted (or is undefined), no documents will be removed. Set selector to {} if you really want to remove all documents from your collection.

• Untrusted code can only remove a single document at a time, specified by its _id. The document is removed only after checking any applicable allow and deny rules. The number of removed documents will be returned to the callback.

On the server, if you don't provide a callback, then remove blocks until the database acknowledges the write and then returns the number of removed documents, or throws an exception if something went wrong. If you do provide a callback, remove returns immediately. Once the remove completes, the callback is called with a single error argument in the case of failure, or a second argument indicating the number of removed documents if the remove was successful.

On the client, remove never blocks. If you do not provide a callback and the remove fails on the server, then Meteor will log a warning to the console. If you provide a callback, Meteor will call that function with an error argument if there was an error, or a second argument indicating the number of removed documents if the remove was successful.

Client example:

// When the remove button is clicked on a chat message, delete
// that message.
Template.chat.events({
  'click .remove': function () {
    Messages.remove(this._id);
  }
});

Server example:

// When the server starts, clear the log, and delete all players
// with a karma of less than -2.
Meteor.startup(function () {
  if (Meteor.isServer) {
    Logs.remove({});
    Players.remove({karma: {$lt: -2}});
  }
});

When a client calls insert, update, or remove on a collection, the collection's allow and deny callbacks are called on the server to determine if the write should be allowed. If at least one allow callback allows the write, and no deny callbacks deny the write, then the write is allowed to proceed.

These checks are run only when a client tries to write to the database directly, for example by calling update from inside an event handler. Server code is trusted and isn't subject to allow and deny restrictions. That includes methods that are called with Meteor.call — they are expected to do their own access checking rather than relying on allow and deny.

You can call allow as many times as you like, and each call can include any combination of insert, update, and remove functions. The functions should return true if they think the operation should be allowed. Otherwise they should return false, or nothing at all (undefined). In that case Meteor will continue searching through any other allow rules on the collection.

The available callbacks are:

insert(userId, doc)

The user userId wants to insert the document doc into the collection. Return true if this should be allowed.

doc will contain the _id field if one was explicitly set by the client, or if there is an active transform. You can use this to prevent users from specifying arbitrary _id fields.

update(userId, doc, fieldNames, modifier)

The user userId wants to update a document doc. (doc is the current version of the document from the database, without the proposed update.) Return true to permit the change.

fieldNames is an array of the (top-level) fields in doc that the client wants to modify, for example ['name', 'score'].

modifier is the raw Mongo modifier that the client wants to execute; for example, {$set: {'name.first': "Alice"}, $inc: {score: 1}}.

Only Mongo modifiers are supported (operations like $set and $push). If the user tries to replace the entire document rather than use $-modifiers, the request will be denied without checking the allow functions.

remove(userId, doc)

The user userId wants to remove doc from the database. Return true to permit this.

When calling update or remove Meteor will by default fetch the entire document doc from the database. If you have large documents you may wish to fetch only the fields that are actually used by your functions. Accomplish this by setting fetch to an array of field names to retrieve.

Example:

// Create a collection where users can only modify documents that
// they own. Ownership is tracked by an 'owner' field on each
// document. All documents must be owned by the user that created
// them and ownership can't be changed. Only a document's owner
// is allowed to delete it, and the 'locked' attribute can be
// set on a document to prevent its accidental deletion.

Posts = new Mongo.Collection("posts");

Posts.allow({
  insert: function (userId, doc) {
    // the user must be logged in, and the document must be owned by the user
    return (userId && doc.owner === userId);
  },
  update: function (userId, doc, fields, modifier) {
    // can only change your own documents
    return doc.owner === userId;
  },
  remove: function (userId, doc) {
    // can only remove your own documents
    return doc.owner === userId;
  },
  fetch: ['owner']
});

Posts.deny({
  update: function (userId, doc, fields, modifier) {
    // can't change owners
    return _.contains(fields, 'owner');
  },
  remove: function (userId, doc) {
    // can't remove locked documents
    return doc.locked;
  },
  fetch: ['locked'] // no need to fetch 'owner'
});

If you never set up any allow rules on a collection then all client writes to the collection will be denied, and it will only be possible to write to the collection from server-side code. In this case you will have to create a method for each possible write that clients are allowed to do. You'll then call these methods with Meteor.call rather than having the clients call insert, update, and remove directly on the collection.

Meteor also has a special "insecure mode" for quickly prototyping new applications. In insecure mode, if you haven't set up any allow or deny rules on a collection, then all users have full write access to the collection. This is the only effect of insecure mode. If you call allow or deny at all on a collection, even Posts.allow({}), then access is checked just like normal on that collection. New Meteor projects start in insecure mode by default. To turn it off just run in your terminal:

meteor remove insecure

This works just like allow, except it lets you make sure that certain writes are definitely denied, even if there is an allow rule that says that they should be permitted.

When a client tries to write to a collection, the Meteor server first checks the collection's deny rules. If none of them return true then it checks the collection's allow rules. Meteor allows the write only if no deny rules return true and at least one allow rule returns true.

Cursors

To create a cursor, use find. To access the documents in a cursor, use forEach, map, or fetch.

This interface is compatible with Array.forEach.

When called from a reactive computation, forEach registers dependencies on the matching documents.

Examples:

// Print the titles of the five top-scoring posts
var topPosts = Posts.find({}, {sort: {score: -1}, limit: 5});
var count = 0;
topPosts.forEach(function (post) {
  console.log("Title of post " + count + ": " + post.title);
  count += 1;
});

This interface is compatible with Array.map.

When called from a reactive computation, map registers dependencies on the matching documents.

On the server, if callback yields, other calls to callback may occur while the first call is waiting. If strict sequential execution is necessary, use forEach instead.

When called from a reactive computation, fetch registers dependencies on the matching documents.

Unlike the other functions, count registers a dependency only on the number of matching documents. (Updates that just change or reorder the documents in the result set will not trigger a recomputation.)

Establishes a live query that invokes callbacks when the result of the query changes. The callbacks receive the entire contents of the document that was affected, as well as its old contents, if applicable. If you only need to receive the fields that changed, see observeChanges.

callbacks may have the following functions as properties:

added(document) or

addedAt(document, atIndex, before)

A new document document entered the result set. The new document appears at position atIndex. It is immediately before the document whose _id is before. before will be null if the new document is at the end of the results.

changed(newDocument, oldDocument) or

changedAt(newDocument, oldDocument, atIndex)

The contents of a document were previously oldDocument and are now newDocument. The position of the changed document is atIndex.

removed(oldDocument) or

removedAt(oldDocument, atIndex)

The document oldDocument is no longer in the result set. It used to be at position atIndex.

movedTo(document, fromIndex, toIndex, before)

A document changed its position in the result set, from fromIndex to toIndex (which is before the document with id before). Its current contents is document.

Use added, changed, and removed when you don't care about the order of the documents in the result set. They are more efficient than addedAt, changedAt, and removedAt.

Before observe returns, added (or addedAt) will be called zero or more times to deliver the initial results of the query.

observe returns a live query handle, which is an object with a stop method. Call stop with no arguments to stop calling the callback functions and tear down the query. The query will run forever until you call this. If observe is called from a Tracker.autorun computation, it is automatically stopped when the computation is rerun or stopped. (If the cursor was created with the option reactive set to false, it will only deliver the initial results and will not call any further callbacks; it is not necessary to call stop on the handle.)

Establishes a live query that invokes callbacks when the result of the query changes. In contrast to observe, observeChanges provides only the difference between the old and new result set, not the entire contents of the document that changed.

callbacks may have the following functions as properties:

added(id, fields) or

addedBefore(id, fields, before)

A new document entered the result set. It has the id and fields specified. fields contains all fields of the document excluding the _id field. The new document is before the document identified by before, or at the end if before is null.

changed(id, fields)

The document identified by id has changed. fields contains the changed fields with their new values. If a field was removed from the document then it will be present in fields with a value of undefined.

movedBefore(id, before)

The document identified by id changed its position in the ordered result set, and now appears before the document identified by before.

removed(id)

The document identified by id was removed from the result set.

observeChanges is significantly more efficient if you do not use addedBefore or movedBefore.

Before observeChanges returns, added (or addedBefore) will be called zero or more times to deliver the initial results of the query.

observeChanges returns a live query handle, which is an object with a stop method. Call stop with no arguments to stop calling the callback functions and tear down the query. The query will run forever until you call this. If observeChanges is called from a Tracker.autorun computation, it is automatically stopped when the computation is rerun or stopped. (If the cursor was created with the option reactive set to false, it will only deliver the initial results and will not call any further callbacks; it is not necessary to call stop on the handle.)

Example:

// Keep track of how many administrators are online.
var count = 0;
var query = Users.find({admin: true, onlineNow: true});
var handle = query.observeChanges({
  added: function (id, user) {
    count++;
    console.log(user.name + " brings the total to " + count + " admins.");
  },
  removed: function () {
    count--;
    console.log("Lost one. We're now down to " + count + " admins.");
  }
});

// After five seconds, stop keeping the count.
setTimeout(function () {handle.stop();}, 5000);

Mongo.ObjectID follows the same API as the Node MongoDB driver ObjectID class. Note that you must use the equals method (or EJSON.equals) to compare them; the === operator will not work. If you are writing generic code that needs to deal with _id fields that may be either strings or ObjectIDs, use EJSON.equals instead of === to compare them.

Mongo-Style Selectors

The simplest selectors are just a string or Mongo.ObjectID. These selectors match the document with that value in its _id field.

A slightly more complex form of selector is an object containing a set of keys that must match in a document:

// Matches all documents where deleted is false
{deleted: false}

// Matches all documents where the name and cognomen are as given
{name: "Rhialto", cognomen: "the Marvelous"}

// Matches every document
{}

But they can also contain more complicated tests:

// Matches documents where age is greater than 18
{age: {$gt: 18}}

// Also matches documents where tags is an array containing "popular"
{tags: "popular"}

// Matches documents where fruit is one of three possibilities
{fruit: {$in: ["peach", "plum", "pear"]}}

See the complete documentation.

Mongo-Style Modifiers

A modifier is an object that describes how to update a document in place by changing some of its fields. Some examples:

// Set the 'admin' property on the document to true
{$set: {admin: true}}

// Add 2 to the 'votes' property, and add "Traz"
// to the end of the 'supporters' array
{$inc: {votes: 2}, $push: {supporters: "Traz"}}

But if a modifier doesn't contain any $-operators, then it is instead interpreted as a literal document, and completely replaces whatever was previously in the database. (Literal document modifiers are not currently supported by validated updates.)

// Find the document with id "123", and completely replace it.
Users.update({_id: "123"}, {name: "Alice", friends: ["Bob"]});

See the full list of modifiers.

Sort Specifiers

Sorts may be specified using your choice of several syntaxes:

// All of these do the same thing (sort in ascending order by
// key "a", breaking ties in descending order of key "b")

[["a", "asc"], ["b", "desc"]]
["a", ["b", "desc"]]
{a: 1, b: -1}

The last form will only work if your JavaScript implementation preserves the order of keys in objects. Most do, most of the time, but it's up to you to be sure.

For local collections you can pass a comparator function which receives two document objects, and returns -1 if the first document comes first in order, 1 if the second document comes first, or 0 if neither document comes before the other. This is a Minimongo extension to MongoDB.

Field Specifiers

Queries can specify a particular set of fields to include or exclude from the result object.

To exclude specific fields from the result objects, the field specifier is a dictionary whose keys are field names and whose values are 0. All unspecified fields are included.

Users.find({}, {fields: {password: 0, hash: 0}})

To include only specific fields in the result documents, use 1 as the value. The _id field is still included in the result.

Users.find({}, {fields: {firstname: 1, lastname: 1}})

With one exception, it is not possible to mix inclusion and exclusion styles: the keys must either be all 1 or all 0. The exception is that you may specify _id: 0 in an inclusion specifier, which will leave _id out of the result object as well. However, such field specifiers can not be used with observeChanges, observe, cursors returned from a publish function, or cursors used in {{#each}} in a template. They may be used with fetch, findOne, forEach, and map.

Field operators such as $ and $elemMatch are not available on the client side yet.

A more advanced example:

Users.insert({ alterEgos: [{ name: "Kira", alliance: "murderer" },
                           { name: "L", alliance: "police" }],
               name: "Yagami Light" });

Users.findOne({}, { fields: { 'alterEgos.name': 1, _id: 0 } });

// returns { alterEgos: [{ name: "Kira" }, { name: "L" }] }

See the MongoDB docs for details of the nested field rules and array behavior.

Session

Session provides a global object on the client that you can use to store an arbitrary set of key-value pairs. Use it to store things like the currently selected item in a list.

What's special about Session is that it's reactive. If you call Session.get("currentList") from inside a template, the template will automatically be rerendered whenever Session.set("currentList", x) is called.

Example:

Tracker.autorun(function () {
  Meteor.subscribe("chat-history", {room: Session.get("currentRoomId")});
});

// Causes the function passed to Tracker.autorun to be re-run, so
// that the chat-history subscription is moved to the room "home".
Session.set("currentRoomId", "home");

Session.set can also be called with an object of keys and values, which is equivalent to calling Session.set individually on each key/value pair.

Session.set({
  a: "foo",
  b: "bar"
});

This is useful in initialization code, to avoid re-initializing a session variable every time a new version of your app is loaded.

Example:

<!-- in main.html -->
<template name="main">
  <p>We've always been at war with {{theEnemy}}.</p>
</template>

// in main.js
Template.main.helpers({
  theEnemy: function () {
    return Session.get("enemy");
  }
});

Session.set("enemy", "Eastasia");
// Page will say "We've always been at war with Eastasia"

Session.set("enemy", "Eurasia");
// Page will change to say "We've always been at war with Eurasia"

If value is a scalar, then these two expressions do the same thing:

(1) Session.get("key") === value
(2) Session.equals("key", value)

... but the second one is always better. It triggers fewer invalidations (template redraws), making your program more efficient.

Example:

<template name="postsView">
{{! Show a dynamically updating list of items. Let the user click on an
    item to select it. The selected item is given a CSS class so it
    can be rendered differently. }}

{{#each posts}}
  {{> postItem }}
{{/each}}
</template>

<template name="postItem">
  <div class="{{postClass}}">{{title}}</div>
</template>

// in JS file
Template.postsView.helpers({
  posts: function() {
    return Posts.find();
  }
});

Template.postItem.helpers({
  postClass: function() {
    return Session.equals("selectedPost", this._id) ?
      "selected" : "";
  }
});

Template.postItem.events({
  'click': function() {
    Session.set("selectedPost", this._id);
  }
});

Using Session.equals here means that when the user clicks on an item and changes the selection, only the newly selected and the newly unselected items are re-rendered.

If Session.get had been used instead of Session.equals, then when the selection changed, all the items would be re-rendered.

For object and array session values, you cannot use Session.equals; instead, you need to use the underscore package and write _.isEqual(Session.get(key), value).

Accounts

The Meteor Accounts system builds on top of the userId support in publish and methods. The core packages add the concept of user documents stored in the database, and additional packages add secure password authentication, integration with third party login services, and a pre-built user interface.

The basic Accounts system is in the accounts-base package, but applications typically include this automatically by adding one of the login provider packages: accounts-password, accounts-facebook, accounts-github, accounts-google, accounts-meetup, accounts-twitter, or accounts-weibo.

Read more about customizing user accounts in the Accounts article in the Meteor Guide.

Retrieves the user record for the current user from the Meteor.users collection.

On the client, this will be the subset of the fields in the document that are published from the server (other fields won't be available on the client). By default the server publishes username, emails, and profile (writable by user). See Meteor.users for more on the fields used in user documents.

This collection contains one document per registered user. Here's an example user document:

{
  _id: "bbca5d6a-2156-41c4-89da-0329e8c99a4f",  // Meteor.userId()
  username: "cool_kid_13", // unique name
  emails: [
    // each email address can only belong to one user.
    { address: "cool@example.com", verified: true },
    { address: "another@different.com", verified: false }
  ],
  createdAt: Wed Aug 21 2013 15:16:52 GMT-0700 (PDT),
  profile: {
    // The profile is writable by the user by default.
    name: "Joe Schmoe"
  },
  services: {
    facebook: {
      id: "709050", // facebook id
      accessToken: "AAACCgdX7G2...AbV9AZDZD"
    },
    resume: {
      loginTokens: [
        { token: "97e8c205-c7e4-47c9-9bea-8e2ccc0694cd",
          when: 1349761684048 }
      ]
    }
  }
}

A user document can contain any data you want to store about a user. Meteor treats the following fields specially:

• username: a unique String identifying the user.
• emails: an Array of Objects with keys address and verified; an email address may belong to at most one user. verified is a Boolean which is true if the user has verified the address with a token sent over email.
• createdAt: the Date at which the user document was created.
• profile: an Object which the user can create and update with any data. Do not store anything on profile that you wouldn't want the user to edit unless you have a deny rule on the Meteor.users collection.
• services: an Object containing data used by particular login services. For example, its reset field contains tokens used by forgot password links, and its resume field contains tokens used to keep you logged in between sessions.

Like all Mongo.Collections, you can access all documents on the server, but only those specifically published by the server are available on the client.

By default, the current user's username, emails and profile are published to the client. You can publish additional fields for the current user with:

// server
Meteor.publish("userData", function () {
  if (this.userId) {
    return Meteor.users.find({_id: this.userId},
                             {fields: {'other': 1, 'things': 1}});
  } else {
    this.ready();
  }
});

// client
Meteor.subscribe("userData");

If the autopublish package is installed, information about all users on the system is published to all clients. This includes username, profile, and any fields in services that are meant to be public (eg services.facebook.id, services.twitter.screenName). Additionally, when using autopublish more information is published for the currently logged in user, including access tokens. This allows making API calls directly from the client for services that allow this.

Users are by default allowed to specify their own profile field with Accounts.createUser and modify it with Meteor.users.update. To allow users to edit additional fields, use Meteor.users.allow. To forbid users from making any modifications to their user document:

Meteor.users.deny({update: function () { return true; }});

For example, the accounts-ui package uses this to display an animation while the login request is being processed.

For example, when called in a user's browser, connections in that browser remain logged in, but any other browsers or DDP clients logged in as that user will be logged out.

If there are multiple users with a username or email only differing in case, a case sensitive match is required. Although createUser won't let you create users with ambiguous usernames or emails, this could happen with existing databases or if you modify the users collection directly.

This function is provided by the accounts-password package. See the Passwords section below.

Available functions are:

• Meteor.loginWithMeteorDeveloperAccount
• Meteor.loginWithFacebook
• Meteor.loginWithGithub
• Meteor.loginWithGoogle
• Meteor.loginWithMeetup
• Meteor.loginWithTwitter
• Meteor.loginWithWeibo

These functions initiate the login process with an external service (eg: Facebook, Google, etc), using OAuth. When called they open a new pop-up window that loads the provider's login page. Once the user has logged in with the provider, the pop-up window is closed and the Meteor client logs in to the Meteor server with the information provided by the external service.

In addition to identifying the user to your application, some services have APIs that allow you to take action on behalf of the user. To request specific permissions from the user, pass the requestPermissions option the login function. This will cause the user to be presented with an additional page in the pop-up dialog to permit access to their data. The user's accessToken — with permissions to access the service's API — is stored in the services field of the user document. The supported values for requestPermissions differ for each login service and are documented on their respective developer sites:

• Facebook: http://developers.facebook.com/docs/authentication/permissions/
• GitHub: http://developer.github.com/v3/oauth/#scopes
• Google: https://developers.google.com/accounts/docs/OAuth2Login#scopeparameter
• Meetup: http://www.meetup.com/meetup_api/auth/#oauth2-scopes
• Twitter, Weibo, Meteor developer accounts: requestPermissions currently not supported

External login services typically require registering and configuring your application before use. The easiest way to do this is with the accounts-ui package which presents a step-by-step guide to configuring each service. However, the data can be also be entered manually in the ServiceConfiguration.configurations collection, which is exported by the service-configuration package.

First, add the service configuration package:

meteor add service-configuration

Then, in your app:

ServiceConfiguration.configurations.upsert(
  { service: "weibo" },
  {
    $set: {
      clientId: "1292962797",
      loginStyle: "popup",
      secret: "75a730b58f5691de5522789070c319bc"
    }
  }
);

Each external service has its own login provider package and login function. For example, to support GitHub login, run in your terminal:

meteor add accounts-github

and use the Meteor.loginWithGithub function:

Meteor.loginWithGithub({
  requestPermissions: ['user', 'public_repo']
}, function (err) {
  if (err)
    Session.set('errorMessage', err.reason || 'Unknown error');
});

Login service configuration is sent from the server to the client over DDP when your app starts up; you may not call the login function until the configuration is loaded. The function Accounts.loginServicesConfigured() is a reactive data source that will return true once the login service is configured; you should not make login buttons visible or active until it is true.

Ensure that your $ROOT_URL matches the authorized domain and callback URL that you configure with the external service (for instance, if you are running Meteor behind a proxy server, $ROOT_URL should be the externally-accessible URL, not the URL inside your proxy).

Example:

Accounts.ui.config({
  requestPermissions: {
    facebook: ['user_likes'],
    github: ['user', 'repo']
  },
  requestOfflineToken: {
    google: true
  },
  passwordSignupFields: 'USERNAME_AND_OPTIONAL_EMAIL'
});

Accounts (multi-server)

The accounts-base package exports two constructors, called AccountsClient and AccountsServer, which are used to create the Accounts object that is available on the client and the server, respectively.

This predefined Accounts object (along with similar convenience methods of Meteor, such as Meteor.logout) is sufficient to implement most accounts-related logic in Meteor apps. Nevertheless, these two constructors can be instantiated more than once, to create multiple independent connections between different accounts servers and their clients, in more complicated authentication situations.

At most one of options.connection and options.ddpUrl should be provided in any instantiation of AccountsClient. If neither is provided, Meteor.connection will be used as the .connection property of the AccountsClient instance.

Note that AccountsClient is currently available only on the client, due to its use of browser APIs such as window.localStorage. In principle, though, it might make sense to establish a client connection from one server to another remote accounts server. Please let us know if you find yourself needing this server-to-server functionality.

The AccountsClient and AccountsServer classes share a common superclass, AccountsCommon. Methods defined on AccountsCommon.prototype will be available on both the client and the server, via the predefined Accounts object (most common) or any custom accountsClientOrServer object created using the AccountsClient or AccountsServer constructors (less common).

Here are a few of those methods:

These methods are defined on AccountsClient.prototype, and are thus available only on the client:

These methods are defined on AccountsServer.prototype, and are thus available only on the server:

This can be called multiple times. If any of the functions return false or throw an error, the new user creation is aborted. To set a specific error message (which will be displayed by accounts-ui), throw a new Meteor.Error.

Example:

// Validate username, sending a specific error message on failure.
Accounts.validateNewUser(function (user) {
  if (user.username && user.username.length >= 3)
    return true;
  throw new Meteor.Error(403, "Username must have at least 3 characters");
});
// Validate username, without a specific error message.
Accounts.validateNewUser(function (user) {
  return user.username !== "root";
});

If the user is being created as part of a login attempt from a client (eg, calling Accounts.createUser from the client, or logging in for the first time with an external service), these callbacks are called before the Accounts.validateLoginAttempt callbacks. If these callbacks succeed but those fail, the user will still be created but the connection will not be logged in as that user.

Use this when you need to do more than simply accept or reject new user creation. With this function you can programatically control the contents of new user documents.

The function you pass will be called with two arguments: options and user. The options argument comes from Accounts.createUser for password-based users or from an external service login flow. options may come from an untrusted client so make sure to validate any values you read from it. The user argument is created on the server and contains a proposed user object with all the automatically generated fields required for the user to log in, including the _id.

The function should return the user document (either the one passed in or a newly-created object) with whatever modifications are desired. The returned document is inserted directly into the Meteor.users collection.

The default create user function simply copies options.profile into the new user document. Calling onCreateUser overrides the default hook. This can only be called once.

Example:

// Support for playing D&D: Roll 3d6 for dexterity
Accounts.onCreateUser(function(options, user) {
  var d6 = function () { return Math.floor(Random.fraction() * 6) + 1; };
  user.dexterity = d6() + d6() + d6();
  // We still want the default hook's 'profile' behavior.
  if (options.profile)
    user.profile = options.profile;
  return user;
});

Call validateLoginAttempt with a callback to be called on login attempts. It returns an object with a single method, stop. Calling stop() unregisters the callback.

When a login attempt is made, the registered validate login callbacks are called with a single argument, the attempt info object:

type String

The service name, such as "password" or "twitter".

allowed Boolean

Whether this login is allowed and will be successful (if not aborted by any of the validateLoginAttempt callbacks). False if the login will not succeed (for example, an invalid password or the login was aborted by a previous validateLoginAttempt callback).

error Exception

When allowed is false, the exception describing why the login failed. It will be a Meteor.Error for failures reported to the user (such as invalid password), and can be a another kind of exception for internal errors.

user Object

When it is known which user was attempting to login, the Meteor user object. This will always be present for successful logins.

connection Object

The connection object the request came in on. See Meteor.onConnection for details.

methodName String

The name of the Meteor method being used to login.

methodArguments Array

An array of the arguments passed to the login method.

A validate login callback must return a truthy value for the login to proceed. If the callback returns a falsy value or throws an exception, the login is aborted. Throwing a Meteor.Error will report the error reason to the user.

All registered validate login callbacks are called, even if one of the callbacks aborts the login. The later callbacks will see the allowed field set to false since the login will now not be successful. This allows later callbacks to override an error from a previous callback; for example, you could override the "Incorrect password" error with a different message.

Validate login callbacks that aren't explicitly trying to override a previous error generally have no need to run if the attempt has already been determined to fail, and should start with

if (!attempt.allowed)
  return false;

See description of AccountsCommon#onLoginFailure for details.

Either the onLogin or the onLoginFailure callbacks will be called for each login attempt. The onLogin callbacks are called after the user has been successfully logged in. The onLoginFailure callbacks are called after a login attempt is denied.

These functions return an object with a single method, stop. Calling stop() unregisters the callback.

On the server, the callbacks get a single argument, the same attempt info object as validateLoginAttempt. On the client, no arguments are passed.

Rate Limiting

By default, there are rules added to the DDPRateLimiter that rate limit logins, new user registration and password reset calls to a limit of 5 requests per 10 seconds per session. These are a basic solution to dictionary attacks where a malicious user attempts to guess the passwords of legitimate users by attempting all possible passwords.

These rate limiting rules can be removed by calling Accounts.removeDefaultRateLimit(). Please see the DDPRateLimiter docs for more information.

Passwords

The accounts-password package contains a full system for password-based authentication. In addition to the basic username and password-based sign-in process, it also supports email-based sign-in including address verification and password recovery emails.

The Meteor server stores passwords using the bcrypt algorithm. This helps protect against embarrassing password leaks if the server's database is compromised.

To add password support to your application, run this command in your terminal:

meteor add accounts-password

You can construct your own user interface using the functions below, or use the accounts-ui package to include a turn-key user interface for password-based sign-in.

On the client, this function logs in as the newly created user on successful completion. On the server, it returns the newly created user id.

On the client, you must pass password and at least one of username or email — enough information for the user to be able to log in again later. If there are existing users with a username or email only differing in case, createUser will fail. On the server, you do not need to specify password, but the user will not be able to log in until it has a password (eg, set with Accounts.setPassword).

To create an account without a password on the server and still let the user pick their own password, call createUser with the email option and then call Accounts.sendEnrollmentEmail. This will send the user an email with a link to set their initial password.

By default the profile option is added directly to the new user document. To override this behavior, use Accounts.onCreateUser.

This function is only used for creating users with passwords. The external service login flows do not use this function.

Managing usernames and emails

Instead of modifying documents in the Meteor.users collection directly, use these convenience functions which correctly check for case insensitive duplicates before updates.

By default, an email address is added with { verified: false }. Use Accounts.sendVerificationEmail to send an email with a link the user can use verify their email address.

This function accepts tokens passed into the callback registered with Accounts.onEmailVerificationLink.

Managing passwords

Use the below functions to initiate password changes or resets from the server or the client.

This triggers a call to Accounts.sendResetPasswordEmail on the server. When the user visits the link in this email, the callback registered with Accounts.onResetPasswordLink will be called.

If you are using the accounts-ui package, this is handled automatically. Otherwise, it is your responsibility to prompt the user for the new password and call resetPassword.

This function accepts tokens passed into the callbacks registered with AccountsClient#onResetPasswordLink and Accounts.onEnrollmentLink.

Sending emails

When the user visits the link in this email, the callback registered with AccountsClient#onResetPasswordLink will be called.

To customize the contents of the email, see Accounts.emailTemplates.

When the user visits the link in this email, the callback registered with Accounts.onEnrollmentLink will be called.

To customize the contents of the email, see Accounts.emailTemplates.

When the user visits the link in this email, the callback registered with Accounts.onEmailVerificationLink will be called.

To customize the contents of the email, see Accounts.emailTemplates.

This is an Object with several fields that are used to generate text/html for the emails sent by sendResetPasswordEmail, sendEnrollmentEmail, and sendVerificationEmail.

Override fields of the object by assigning to them:

• from: A String with an RFC5322 From address. By default, the email is sent from no-reply@meteor.com. If you wish to receive email from users asking for help with their account, be sure to set this to an email address that you can receive email at.
• siteName: The public name of your application. Defaults to the DNS name of the application (eg: awesome.meteor.com).
• headers: An Object for custom email headers as described in Email.send.
• resetPassword: An Object with the fields:
  • from: A Function used to override the from address defined by the emailTemplates.from field.
  • subject: A Function that takes a user object and returns a String for the subject line of a reset password email.
  • text: An optional Function that takes a user object and a url, and returns the body text for a reset password email.
  • html: An optional Function that takes a user object and a url, and returns the body html for a reset password email.
• enrollAccount: Same as resetPassword, but for initial password setup for new accounts.
• verifyEmail: Same as resetPassword, but for verifying the users email address.

Example:

Accounts.emailTemplates.siteName = "AwesomeSite";
Accounts.emailTemplates.from = "AwesomeSite Admin <accounts@example.com>";
Accounts.emailTemplates.enrollAccount.subject = function (user) {
    return "Welcome to Awesome Town, " + user.profile.name;
};
Accounts.emailTemplates.enrollAccount.text = function (user, url) {
   return "You have been selected to participate in building a better future!"
     + " To activate your account, simply click the link below:\n\n"
     + url;
};

Templates

When you write a template as <template name="foo"> ... </template> in an HTML file in your app, Meteor generates a "template object" named Template.foo. Note that template name cannot contain hyphens and other special characters.

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 you, including determining when a template instance has been removed 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.

Read more about templates and how to use them in the Spacebars package README and the Blaze article in the Meteor Guide.

Declare event handlers for instances of this template. Multiple calls add new event handlers in addition to the existing ones.

See Event Maps for a detailed description of the event map format and how event handling works in Meteor.

Each template has a local dictionary of helpers that are made available to it, and this call specifies helpers to add to the template's dictionary.

Example:

Template.myTemplate.helpers({
  foo: function () {
    return Session.get("foo");
  }
});

Now you can invoke this helper with {{foo}} in the template defined with <template name="myTemplate">.

Helpers can accept positional and keyword arguments:

Template.myTemplate.helpers({
  displayName: function (firstName, lastName, keyword) {
    var prefix = keyword.hash.title ? keyword.hash.title + " " : "";
    return prefix + firstName + " " + lastName;
  }
});

Then you can call this helper from template like this:

{{displayName "John" "Doe" title="President"}}

You can learn more about arguments to helpers in Spacebars Readme.

Under the hood, each helper starts a new Tracker.autorun. When its reactive dependencies change, the helper is rerun. Helpers depend on their data context, passed arguments and other reactive data sources accessed during execution.

To create a helper that can be used in any template, use Template.registerHelper.

Callbacks added with this method are 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 a callback, this is a template instance object that is unique to this occurrence of the template and persists across re-renderings. Use the onCreated and onDestroyed 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.

This can be a good place to apply any DOM manipulations you want, after the template is rendered for the first time.

<template name="myPictures">
  <div class="container">
    {{#each pictures}}
      <img class="item" src="/{{.}}"/>
    {{/each}}
  </div>
</template>

Template.myPictures.onRendered(function () {
  // Use the Packery jQuery plugin
  this.$('.container').packery({
    itemSelector: '.item',
    gutter: 10
  });
});

Callbacks added with this method are called before your template's logic is evaluated for the first time. Inside a callback, this is the new template instance object. Properties you set on this object will be visible from the callbacks added with onRendered and onDestroyed methods and from event handlers.

These callbacks fire once and are the first group of callbacks to fire. Handling the created event is a useful way to set up values on template instance that are read from template helpers using Template.instance().

Template.myPictures.onCreated(function () {
  // set up local reactive variables
  this.highlightedPicture = new ReactiveVar(null);

  // register this template within some central store
  GalleryTemplates.push(this);
});

These callbacks are called when an occurrence of a template is taken off the page for any reason and not replaced with a re-rendering. Inside a callback, this is the template instance object being destroyed.

This group of callbacks is most useful for cleaning up or undoing any external effects of created or rendered groups. This group fires once and is the last callback to fire.

Template.myPictures.onDestroyed(function () {
  // deregister from some central store
  GalleryTemplates = _.without(GalleryTemplates, this);
});

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 as the template is reactively updated.

Template instance objects are found as the value of this in the onCreated, onRendered, and onDestroyed template callbacks, and as an argument to event handlers. You can access the current template instance from helpers using Template.instance().

In addition to the properties and functions described below, you can assign additional properties of your choice to the object. Use the onCreated and onDestroyed methods to add callbacks performing initialization or clean-up on the object.

You can only access findAll, find, firstNode, and lastNode from the onRendered callback and event handlers, not from onCreated and onDestroyed, because they require the template instance to be in the DOM.

Template instance objects are instanceof Blaze.TemplateInstance.

template.findAll returns an array of DOM elements matching selector.

template.$ returns a jQuery object of those same elements. jQuery objects are similar to arrays, with additional methods defined by the jQuery library.

The template instance serves as the document root for the selector. Only elements inside the template and its sub-templates can match parts of the selector.

Returns one DOM element matching selector, or null if there are no such elements.

The template instance serves as the document root for the selector. Only elements inside the template and its sub-templates can match parts of the selector.

The two nodes firstNode and lastNode indicate the extent of the rendered template in the DOM. The rendered template includes these nodes, their intervening siblings, and their descendents. These two nodes are siblings (they have the same parent), and lastNode comes after firstNode, or else they are the same node.

This property provides access to the data context at the top level of the template. It is updated each time the template is re-rendered. Access is read-only and non-reactive.

You can use this.autorun from an onCreated or onRendered callback to reactively update the DOM or the template instance. You can use Template.currentData() inside of this callback to access reactive data context of the template instance. The Computation is automatically stopped when the template is destroyed.

Alias for template.view.autorun.

You can use this.subscribe from an onCreated callback to specify which data publications this template depends on. The subscription is automatically stopped when the template is destroyed.

There is a complementary function Template.instance().subscriptionsReady() which returns true when all of the subscriptions called with this.subscribe are ready.

Inside the template's HTML, you can use the built-in helper Template.subscriptionsReady, which is an easy pattern for showing loading indicators in your templates when they depend on data loaded from subscriptions.

Example:

Template.notifications.onCreated(function () {
  // Use this.subscribe inside onCreated callback
  this.subscribe("notifications");
});

<template name="notifications">
  {{#if Template.subscriptionsReady}}
    <!-- This is displayed when all data is ready. -->
    {{#each notifications}}
      {{> notification}}
    {{/each}}
  {{else}}
    Loading...
  {{/if}}
</template>

Another example where the subscription depends on the data context:

Template.comments.onCreated(function () {
  var self = this;

  // Use self.subscribe with the data context reactively
  self.autorun(function () {
    var dataContext = Template.currentData();
    self.subscribe("comments", dataContext.postId);
  });
});

{{#with post}}
  {{> comments postId=_id}}
{{/with}}

Another example where you want to initialize a plugin when the subscription is done:

Template.listing.onRendered(function () {
  var template = this;

  template.subscribe('listOfThings', function () {
    // Wait for the data to load using the callback
    Tracker.afterFlush(function () {
      // Use Tracker.afterFlush to wait for the UI to re-render
      // then use highlight.js to highlight a code snippet
      highlightBlock(template.find('.code'));
    });
  });
});

For example, Template.parentData(0) is equivalent to Template.currentData(). Template.parentData(2) is equivalent to {{../..}} in a template.

You can define helpers and event maps on Template.body just like on any Template.myTemplate object.

Helpers on Template.body are only available in the <body> tags of your app. To register a global helper, use Template.registerHelper. Event maps on Template.body don't apply to elements added to the body via Blaze.render, jQuery, or the DOM API, or to the body element itself. To handle events on the body, window, or document, use jQuery or the DOM API.

Template.dynamic allows you to include a template by name, where the name may be calculated by a helper and may change reactively. The data argument is optional, and if it is omitted, the current data context is used. It's also possible, to use Template.dynamic as a block helper ({{#Template.dynamic}} ... {{/Template.dynamic}})

For example, if there is a template named "foo", {{> Template.dynamic template="foo"}} is equivalent to {{> foo}} and {{#Template.dynamic template="foo"}} ... {{/Template.dynamic}} is equivalent to {{#foo}} ... {{/foo}}.

Event Maps

An event map is an object where the properties specify a set of events to handle, and the values are the handlers for those events. The property can be in one of several forms:

eventtype

Matches a particular type of event, such as 'click'.

eventtype selector

Matches a particular type of event, but only when it appears on an element that matches a certain CSS selector.

event1, event2

To handle more than one type of event with the same function, use a comma-separated list.

The handler function receives two arguments: event, an object with information about the event, and template, a template instance 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 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:

{
  // Fires when any element is clicked
  'click': function (event) { ... },

  // Fires when any element with the 'accept' class is clicked
  'click .accept': function (event) { ... },

  // Fires when 'accept' is clicked or focused, or a key is pressed
  'click .accept, focus .accept, keypress': function (event) { ... }
}

Most events bubble up the document tree from their originating element. For example, 'click p' catches a click anywhere in a paragraph, even if the click originated on a link, span, or some other element inside the paragraph. The originating element of the event is available as the target property, while the element that matched the selector and is currently handling it is called currentTarget.

{
  'click p': function (event) {
    var paragraph = event.currentTarget; // always a P
    var clickedElement = event.target; // could be the P or a child element
  }
}

If a selector matches multiple elements that an event bubbles to, it will be called multiple times, for example in the case of 'click div' or 'click *'. If no selector is given, the handler will only be called once, on the original target element.

The following properties and methods are available on the event object passed to handlers:

type String

The event's type, such as "click", "blur" or "keypress".

target DOM Element

The element that originated the event.

currentTarget DOM Element

The element currently handling the event. This is the element that matched the selector in the event map. For events that bubble, it may be target or an ancestor of target, and its value changes as the event bubbles.

which Number

For mouse events, the number of the mouse button (1=left, 2=middle, 3=right). For key events, a character or key code.

stopPropagation()

Prevent the event from propagating (bubbling) up to other elements. Other event handlers matching the same element are still fired, in this and other event maps.

stopImmediatePropagation()

Prevent all additional event handlers from being run on this event, including other handlers in this event map, handlers reached by bubbling, and handlers in other event maps.

preventDefault()

Prevents the action the browser would normally take in response to this event, such as following a link or submitting a form. Further handlers are still called, but cannot reverse the effect.

isPropagationStopped()

Returns whether stopPropagation() has been called for this event.

isImmediatePropagationStopped()

Returns whether stopImmediatePropagation() has been called for this event.

isDefaultPrevented()

Returns whether preventDefault() has been called for this event.

Returning false from a handler is the same as calling both stopImmediatePropagation and preventDefault on the event.

Event types and their uses include:

click

Mouse click on any element, including a link, button, form control, or div. Use preventDefault() to prevent a clicked link from being followed. Some ways of activating an element from the keyboard also fire click.

dblclick

Double-click.

focus, blur

A text input field or other form control gains or loses focus. You can make any element focusable by giving it a tabindex property. Browsers differ on whether links, checkboxes, and radio buttons are natively focusable. These events do not bubble.

change

A checkbox or radio button changes state. For text fields, use blur or key events to respond to changes.

mouseenter, mouseleave

The pointer enters or leaves the bounds of an element. These events do not bubble.

mousedown, mouseup

The mouse button is newly down or up.

keydown, keypress, keyup

The user presses a keyboard key. keypress is most useful for catching typing in text fields, while keydown and keyup can be used for arrow keys or modifier keys.

Other DOM events are available as well, but for the events above, Meteor has taken some care to ensure that they work uniformly in all browsers.

Spacebars

Spacebars is the language used to write Meteor templates. It is inspired by Handlebars. It shares some of the spirit and syntax of Handlebars, but has been tailored to produce reactive Meteor templates when compiled.

For more information about Spacebars, see the Spacebars README.

Blaze

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. For more information, check out the Blaze project page.

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.

Blaze.renderWithData(Template.myTemplate, data) is essentially the same as Blaze.render(Blaze.With(data, function () { return Template.myTemplate; })).

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.

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

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:

name String

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

parentView View or null

The enclosing View that caused this View to be rendered, if any.

isCreated Boolean

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.

isRendered Boolean

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.

isDestroyed Boolean

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.

renderCount Integer

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.

autorun(runFunc)

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.

onViewCreated(func)

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.

onViewReady(func)

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.

onViewDestroyed(func)

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.

firstNode() DOM node

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.

lastNode() DOM node

The last node of the View's rendered content.

See firstNode().

template Template

For Views created by invoking templates, the original Template object. For example, Blaze.render(Template.foo).template === Template.foo.

templateInstance() Template instance

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.

The "current view" is used by Template.currentData() and Template.instance() to determine the contextually relevant data context and template instance.

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.

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.

Returns an unrendered View object you can pass to Blaze.render.

Matches the behavior of {{#if}} in templates.

Returns an unrendered View object you can pass to Blaze.render.

Matches the behavior of {{#unless}} in templates.

Returns an unrendered View object you can pass to Blaze.render.

Matches the behavior of {{#each}} in templates.

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:

viewName String

Same as the constructor argument.

renderFunction Function

Same as the constructor argument.

constructView()

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.

Renderable Content

A value is renderable content if it is one of the following:

• A template object like Template.myTemplate
• An unrendered View object, like the return value of Blaze.With
• null or undefined

Timers

Meteor uses global environment variables to keep track of things like the current request's user. To make sure these variables have the right values, you need to use Meteor.setTimeout instead of setTimeout and Meteor.setInterval instead of setInterval.

These functions work just like their native JavaScript equivalents. If you call the native function, you'll get an error stating that Meteor code must always run within a Fiber, and advising to use Meteor.bindEnvironment.

Returns a handle that can be used by Meteor.clearTimeout.

Returns a handle that can be used by Meteor.clearInterval.

Tracker

Meteor has a simple dependency tracking system which allows it to automatically rerun templates and other computations whenever 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. When you call a function that supports reactive updates (such as a database query), it automatically saves the current Computation object, if any (representing, for example, the current template being rendered). Later, when the data changes, the function can "invalidate" the Computation, causing it to rerun (rerendering the template).

Applications will find Tracker.autorun useful, while more advanced facilities such as Tracker.Dependency and onInvalidate callbacks are intended primarily for package authors implementing new reactive data sources.

Tracker.autorun allows you to run a function that depends on reactive data sources, in such a way that if there are changes to the data later, the function will be rerun.

For example, you can monitor a cursor (which is a reactive data source) and aggregate it into a session variable:

Tracker.autorun(function () {
  var oldest = _.max(Monkeys.find().fetch(), function (monkey) {
    return monkey.age;
  });
  if (oldest)
    Session.set("oldest", oldest.name);
});

Or you can wait for a session variable to have a certain value, and do something the first time it does, calling stop on the computation to prevent further rerunning:

Tracker.autorun(function (c) {
  if (! Session.equals("shouldAlert", true))
    return;

  c.stop();
  alert("Oh no!");
});

The function is invoked immediately, at which point it may alert and stop right away if shouldAlert is already true. If not, the function is run again when shouldAlert becomes true.

A change to a data dependency does not cause an immediate rerun, but rather "invalidates" the computation, causing it to rerun the next time a flush occurs. A flush will occur automatically as soon as the system is idle if there are invalidated computations. You can also use Tracker.flush to cause an immediate flush of all pending reruns.

If you nest calls to Tracker.autorun, then when the outer call stops or reruns, the inner call will stop automatically. Subscriptions and observers are also automatically stopped when used as part of a computation that is rerun, allowing new ones to be established. See Meteor.subscribe for more information about subscriptions and reactivity.

If the initial run of an autorun throws an exception, the computation is automatically stopped and won't be rerun.

Normally, when you make changes (like writing to the database), their impact (like updating the DOM) is delayed until the system is idle. This keeps things predictable — you can know that the DOM won't go changing out from under your code as it runs. It's also one of the things that makes Meteor fast.

Tracker.flush forces all of the pending reactive updates to complete. For example, if an event handler changes a Session variable that will cause part of the user interface to rerender, the handler can call flush to perform the rerender immediately and then access the resulting DOM.

An automatic flush occurs whenever the system is idle which performs exactly the same work as Tracker.flush. The flushing process consists of rerunning any invalidated computations. If additional invalidations happen while flushing, they are processed as part of the same flush until there is no more work to be done. Callbacks registered with Tracker.afterFlush are called after processing outstanding invalidations.

It is illegal to call flush from inside a flush or from a running computation.

The Meteor Manual describes the motivation for the flush cycle and the guarantees made by Tracker.flush and Tracker.afterFlush.

Calls func with Tracker.currentComputation temporarily set to null and returns func's own return value. If func accesses reactive data sources, these data sources will never cause a rerun of the enclosing computation.

This value is useful for data source implementations to determine whether they are being accessed reactively or not.

It's very rare to need to access currentComputation directly. The current computation is used implicitly by Tracker.active (which tests whether there is one), dependency.depend() (which registers that it depends on a dependency), and Tracker.onInvalidate (which registers a callback with it).

See computation.onInvalidate for more details.

Functions scheduled by multiple calls to afterFlush are guaranteed to run in the order that afterFlush was called. Functions are guaranteed to be called at a time when there are no invalidated computations that need rerunning. This means that if an afterFlush function invalidates a computation, that computation will be rerun before any other afterFlush functions are called.

Tracker.Computation

A Computation object represents code that is repeatedly rerun in response to reactive data changes. Computations don't have return values; they just perform actions, such as rerendering a template on the screen. Computations are created using Tracker.autorun. Use stop to prevent further rerunning of a computation.

Each time a computation runs, it may access various reactive data sources that serve as inputs to the computation, which are called its dependencies. At some future time, one of these dependencies may trigger the computation to be rerun by invalidating it. When this happens, the dependencies are cleared, and the computation is scheduled to be rerun at flush time.

The current computation (Tracker.currentComputation) is the computation that is currently being run or rerun (computed), and the one that gains a dependency when a reactive data source is accessed. Data sources are responsible for tracking these dependencies using Tracker.Dependency objects.

Invalidating a computation sets its invalidated property to true and immediately calls all of the computation's onInvalidate callbacks. When a flush occurs, if the computation has been invalidated and not stopped, then the computation is rerun by setting the invalidated property to false and calling the original function that was passed to Tracker.autorun. A flush will occur when the current code finishes running, or sooner if Tracker.flush is called.

Stopping a computation invalidates it (if it is valid) for the purpose of calling callbacks, but ensures that it will never be rerun.

Example:

// if we're in a computation, then perform some clean-up
// when the current computation is invalidated (rerun or
// stopped)
if (Tracker.active) {
  Tracker.onInvalidate(function () {
    x.destroy();
    y.finalize();
  });
}

Stopping a computation is irreversible and guarantees that it will never be rerun. You can stop a computation at any time, including from the computation's own run function. Stopping a computation that is already stopped has no effect.

Stopping a computation causes its onInvalidate callbacks to run immediately if it is not currently invalidated, as well as its stop callbacks.

Nested computations are stopped automatically when their enclosing computation is rerun.

Invalidating a computation marks it to be rerun at flush time, at which point the computation becomes valid again. It is rare to invalidate a computation manually, because reactive data sources invalidate their calling computations when they change. Reactive data sources in turn perform this invalidation using one or more Tracker.Dependency objects.

Invalidating a computation immediately calls all onInvalidate callbacks registered on it. Invalidating a computation that is currently invalidated or is stopped has no effect. A computation can invalidate itself, but if it continues to do so indefinitely, the result will be an infinite loop.

onInvalidate registers a one-time callback that either fires immediately or as soon as the computation is next invalidated or stopped. It is used by reactive data sources to clean up resources or break dependencies when a computation is rerun or stopped.

To get a callback after a computation has been recomputed, you can call Tracker.afterFlush from onInvalidate.

This property is initially false. It is set to true by stop() and invalidate(). It is reset to false when the computation is recomputed at flush time.

This property is a convenience to support the common pattern where a computation has logic specific to the first run.

Tracker.Dependency

A Dependency represents an atomic unit of reactive data that a computation might depend on. Reactive data sources such as Session or Minimongo internally create different Dependency objects for different pieces of data, each of which may be depended on by multiple computations. When the data changes, the computations are invalidated.

Dependencies don't store data, they just track the set of computations to invalidate if something changes. Typically, a data value will be accompanied by a Dependency object that tracks the computations that depend on it, as in this example:

var weather = "sunny";
var weatherDep = new Tracker.Dependency;

var getWeather = function () {
  weatherDep.depend()
  return weather;
};

var setWeather = function (w) {
  weather = w;
  // (could add logic here to only call changed()
  // if the new value is different from the old)
  weatherDep.changed();
};

This example implements a weather data source with a simple getter and setter. The getter records that the current computation depends on the weatherDep dependency using depend(), while the setter signals the dependency to invalidate all dependent computations by calling changed().

The reason Dependencies do not store data themselves is that it can be useful to associate multiple Dependencies with the same piece of data. For example, one Dependency might represent the result of a database query, while another might represent just the number of documents in the result. A Dependency could represent whether the weather is sunny or not, or whether the temperature is above freezing. Session.equals is implemented this way for efficiency. When you call Session.equals("weather", "sunny"), the current computation is made to depend on an internal Dependency that does not change if the weather goes from, say, "rainy" to "cloudy".

Conceptually, the only two things a Dependency can do are gain a dependent and change.

A Dependency's dependent computations are always valid (they have invalidated === false). If a dependent is invalidated at any time, either by the Dependency itself or some other way, it is immediately removed.

See the Meteor Manual to learn how to create a reactive data source using Tracker.Dependency.

dep.depend() is used in reactive data source implementations to record the fact that dep is being accessed from the current computation.

For reactive data sources that create many internal Dependencies, this function is useful to determine whether a particular Dependency is still tracking any dependency relationships or if it can be cleaned up to save memory.

ReactiveVar

To use ReactiveVar, add the reactive-var package to your project by running in your terminal:

meteor add reactive-var

A ReactiveVar holds a single value that can be get and set, such that calling set will invalidate any Computations that called get, according to the usual contract for reactive data sources.

A ReactiveVar is similar to a Session variable, with a few differences:

• ReactiveVars don't have global names, like the "foo" in Session.get("foo"). Instead, they may be created and used locally, for example attached to a template instance, as in: this.foo.get().

• ReactiveVars are not automatically migrated across hot code pushes, whereas Session state is.

• ReactiveVars can hold any value, while Session variables are limited to JSON or EJSON.

An important property of ReactiveVars — which is sometimes a reason for using one — is that setting the value to the same value as before has no effect; it does not trigger any invalidations. So if one autorun sets a ReactiveVar, and another autorun gets the ReactiveVar, a re-run of the first autorun won't necessarily trigger the second. By default, only primitive values are compared this way, while calling set on an argument that is an object (not a primitive) always counts as a change. You can configure this behavior using the equalsFunc argument.

EJSON

EJSON is an extension of JSON to support more types. It supports all JSON-safe types, as well as:

• Date (JavaScript Date)
• Binary (JavaScript Uint8Array or the result of EJSON.newBinary)
• User-defined types (see EJSON.addType. For example, Mongo.ObjectID is implemented this way.)

All EJSON serializations are also valid JSON. For example an object with a date and a binary buffer would be serialized in EJSON as:

{
  "d": {"$date": 1358205756553},
  "b": {"$binary": "c3VyZS4="}
}

Meteor supports all built-in EJSON data types in publishers, method arguments and results, Mongo databases, and Session variables.

Buffers of binary data are represented by Uint8Array instances on JavaScript platforms that support them. On implementations of JavaScript that do not support Uint8Array, binary data buffers are represented by standard arrays containing numbers ranging from 0 to 255, and the $Uint8ArrayPolyfill key set to true.

When you add a type to EJSON, Meteor will be able to use that type in:

• publishing objects of your type if you pass them to publish handlers.
• allowing your type in the return values or arguments to methods.
• storing your type client-side in Minimongo.
• allowing your type in Session variables.

Instances of your type must implement typeName and toJSONValue methods, and may implement clone and equals methods if the default implementations are not sufficient.

For example, the toJSONValue method for Mongo.ObjectID could be:

function () {
  return this.toHexString();
};

If your type does not have a clone method, EJSON.clone will use toJSONValue and the factory instead.

The equals method should define an equivalence relation. It should have the following properties:

• Reflexivity - for any instance a: a.equals(a) must be true.
• Symmetry - for any two instances a and b: a.equals(b) if and only if b.equals(a).
• Transitivity - for any three instances a, b, and c: a.equals(b) and b.equals(c) implies a.equals(c).

If your type does not have an equals method, EJSON.equals will compare the result of calling toJSONValue instead.

HTTP

HTTP provides an HTTP request API on the client and server. To use these functions, add the HTTP package to your project by running in your terminal:

meteor add http

This function initiates an HTTP request to a remote server.

On the server, this function can be run either synchronously or asynchronously. If the callback is omitted, it runs synchronously and the results are returned once the request completes successfully. If the request was not successful, an error is thrown. This is useful when making server-to-server HTTP API calls from within Meteor methods, as the method can succeed or fail based on the results of the synchronous HTTP call. In this case, consider using this.unblock() to allow other methods on the same connection to run in the mean time. On the client, this function must be used asynchronously by passing a callback.

Both HTTP and HTTPS protocols are supported. The url argument must be an absolute URL including protocol and host name on the server, but may be relative to the current host on the client. The query option replaces the query string of url. Parameters specified in params that are put in the URL are appended to any query string. For example, with a url of "/path?query" and params of {foo:"bar"}, the final URL will be "/path?query&foo=bar".

The params are put in the URL or the request body, depending on the type of request. In the case of request with no bodies, like GET and HEAD, the parameters will always go in the URL. For a POST or other type of request, the parameters will be encoded into the body with a standard x-www-form-urlencoded content type, unless the content or data option is used to specify a body, in which case the parameters will be appended to the URL instead.

When run in asynchronous mode, the callback receives two arguments, error and result. The error argument will contain an Error if the request fails in any way, including a network error, time-out, or an HTTP status code in the 400 or 500 range. In case of a 4xx/5xx HTTP status code, the response property on error matches the contents of the result object. When run in synchronous mode, either result is returned from the function, or error is thrown.

Contents of the result object:

statusCode Number

Numeric HTTP result status code, or null on error.

content String

The body of the HTTP response as a string.

data Object or null

If the response headers indicate JSON content, this contains the body of the document parsed as a JSON object.

headers Object

A dictionary of HTTP headers from the response.

Example server method:

Meteor.methods({checkTwitter: function (userId) {
  check(userId, String);
  this.unblock();
  try {
    var result = HTTP.call("GET", "http://api.twitter.com/xyz",
                           {params: {user: userId}});
    return true;
  } catch (e) {
    // Got a network error, time-out or HTTP error in the 400 or 500 range.
    return false;
  }
}});

Example asynchronous HTTP call:

HTTP.call("POST", "http://api.twitter.com/xyz",
          {data: {some: "json", stuff: 1}},
          function (error, result) {
            if (!error) {
              Session.set("twizzled", true);
            }
          });

Email

The email package allows sending email from a Meteor app. To use it, add the package to your project by running in your terminal:

meteor add email

The server reads from the MAIL_URL environment variable to determine how to send mail. Currently, Meteor supports sending mail over SMTP; the MAIL_URL environment variable should be of the form smtp://USERNAME:PASSWORD@HOST:PORT/.

If MAIL_URL is not set, Email.send outputs the message to standard output instead.

You must provide the from option and at least one of to, cc, and bcc; all other options are optional.

Email.send only works on the server. Here is an example of how a client could use a server method call to send an email. (In an actual application, you'd need to be careful to limit the emails that a client could send, to prevent your server from being used as a relay by spammers.)

// In your server code: define a method that the client can call
Meteor.methods({
  sendEmail: function (to, from, subject, text) {
    check([to, from, subject, text], [String]);

    // Let other method calls from the same client start running,
    // without waiting for the email sending to complete.
    this.unblock();

    Email.send({
      to: to,
      from: from,
      subject: subject,
      text: text
    });
  }
});

// In your client code: asynchronously send an email
Meteor.call('sendEmail',
            'alice@example.com',
            'bob@example.com',
            'Hello from Meteor!',
            'This is a test of Email.send.');

Assets

Assets allows server code in a Meteor application to access static server assets, which are located in the private subdirectory of an application's tree. Assets are not processed as source files and are copied directly into your application's bundle.

Static server assets are included by placing them in the application's private subdirectory. For example, if an application's private subdirectory includes a directory called nested with a file called data.txt inside it, then server code can read data.txt by running:

var data = Assets.getText('nested/data.txt');

Note: Packages can only access their own assets. If you need to read the assets of a different package, or of the enclosing app, you need to get a reference to that package's Assets object.

Package.js

A package is a directory containing a package.js file, which contains roughly three major sections: a basic description, a package definition, and a test definition. By default, the directory name is the name of the package.

The package.js file below is an example of how to use the packaging API. The rest of this section will explain the specific API commands in greater detail.

/* Information about this package */
Package.describe({
  // Short two-sentence summary.
  summary: "What this does",
  // Version number.
  version: "1.0.0",
  // Optional.  Default is package directory name.
  name: "username:package-name",
  // Optional github URL to your source repository.
  git: "https://github.com/something/something.git",
});

/* This defines your actual package */
Package.onUse(function (api) {
  // If no version is specified for an 'api.use' dependency, use the
  // one defined in Meteor 0.9.0.
  api.versionsFrom('0.9.0');
  // Use Underscore package, but only on the server.
  // Version not specified, so it will be as of Meteor 0.9.0.
  api.use('underscore', 'server');
  // Use iron:router package, version 1.0.0 or newer.
  api.use('iron:router@1.0.0');
  // Give users of this package access to the Templating package.
  api.imply('templating')
  // Export the object 'Email' to packages or apps that use this package.
  api.export('Email', 'server');
  // Specify the source code for the package.
  api.addFiles('email.js', 'server');
});

/* This defines the tests for the package */
Package.onTest(function (api) {
  // Sets up a dependency on this package
  api.use('username:package-name');
  // Allows you to use the 'tinytest' framework
  api.use('tinytest@1.0.0');
  // Specify the source code for the package tests
  api.addFiles('email_tests.js', 'server');
});

/* This lets you use npm packages in your package*/
Npm.depends({
  simplesmtp: "0.3.10",
  "stream-buffers": "0.2.5"});

Build plugins are created with Package.registerBuildPlugin. See the coffeescript package for an example. Build plugins are fully-fledged Meteor programs in their own right and have their own namespace, package dependencies, source files and npm requirements.

Package Description

Provide basic package information with Package.describe(options). To publish a package, you must define summary and version.

Package Definition

Define dependencies and expose package methods with the Package.onUse handler. This section lets you define what packages your package depends on, what packages are implied by your package, and what object your package is exported to.

Unit Tests

Set up your tests with the Package.onTest handler, which has an interface that's parallel to that of the onUse handler. The tests will need to depend on the package that you have just created. For example, if your package is the email package, you have to call api.use('email') in order to test the package.

If you used meteor create to set up your package, Meteor will create the required scaffolding in package.js, and you'll only need to add unit test code in the _test.js file that was created.

External Packages and Plugins

Meteor packages can include NPM packages and Cordova plugins by using Npm.depends and Cordova.depends in the package.js file.

Mobile Config File

If your Meteor application targets mobile platforms such as iOS or Android, you can configure your app's metadata and build process in a special top-level file called mobile-config.js which is not included in your application and is used only for this configuration.

The code snippet below is an example mobile-config.js file. The rest of this section will explain the specific API commands in greater detail.

// This section sets up some basic app metadata,
// the entire section is optional.
App.info({
  id: 'com.example.matt.uber',
  name: 'über',
  description: 'Get über power in one button click',
  author: 'Matt Development Group',
  email: 'contact@example.com',
  website: 'http://example.com'
});

// Set up resources such as icons and launch screens.
App.icons({
  'iphone': 'icons/icon-60.png',
  'iphone_2x': 'icons/icon-60@2x.png',
  // ... more screen sizes and platforms ...
});

App.launchScreens({
  'iphone': 'splash/Default~iphone.png',
  'iphone_2x': 'splash/Default@2x~iphone.png',
  // ... more screen sizes and platforms ...
});

// Set PhoneGap/Cordova preferences
App.setPreference('BackgroundColor', '0xff0000ff');
App.setPreference('HideKeyboardFormAccessoryBar', true);
App.setPreference('Orientation', 'default');
App.setPreference('Orientation', 'all', 'ios');

// Pass preferences for a particular PhoneGap/Cordova plugin
App.configurePlugin('com.phonegap.plugins.facebookconnect', {
  APP_ID: '1234567890',
  API_KEY: 'supersecretapikey'
});

Meteor supports a variety of add-on packages and third party libraries. While you can build great applications using only the Meteor core functionality, optional packages can make development even faster and better.

Packages can be added to a Meteor project with:

meteor add <package_name>

and removed with:

meteor remove <package_name>

Some of the packages that Meteor Development Group maintains include:

appcache

The appcache package stores the static parts of a Meteor application (the client side Javascript, HTML, CSS, and images) in the browser's application cache. To enable caching simply add the appcache package to your project.

• Once a user has visited a Meteor application for the first time and the application has been cached, on subsequent visits the web page loads faster because the browser can load the application out of the cache without contacting the server first.

• Hot code pushes are loaded by the browser in the background while the app continues to run. Once the new code has been fully loaded the browser is able to switch over to the new code quickly.

• The application cache allows the application to be loaded even when the browser doesn't have an Internet connection, and so enables using the app offline.

(Note however that the appcache package by itself doesn't make data available offline: in an application loaded offline, a Meteor Collection will appear to be empty in the client until the Internet becomes available and the browser is able to establish a DDP connection).

To turn AppCache off for specific browsers use:

Meteor.AppCache.config({
  chrome: false,
  firefox: false
});

The supported browsers that can be enabled or disabled include, but are not limited to, android, chrome, chromium, chromeMobileIOS, firefox, ie, mobileSafari and safari.

Browsers limit the amount of data they will put in the application cache, which can vary due to factors such as how much disk space is free. Unfortunately if your application goes over the limit rather than disabling the application cache altogether and running the application online, the browser will instead fail that particular update of the cache, leaving your users running old code.

Thus it's best to keep the size of the cache below 5MB. The appcache package will print a warning on the Meteor server console if the total size of the resources being cached is over 5MB.

If you have files too large to fit in the cache you can disable caching by URL prefix. For example,

Meteor.AppCache.config({onlineOnly: ['/online/']});

causes files in your public/online directory to not be cached, and so they will only be available online. You can then move your large files into that directory and refer to them at the new URL:

<img src="/online/bigimage.jpg">

If you'd prefer not to move your files, you can use the file names themselves as the URL prefix:

Meteor.AppCache.config({
  onlineOnly: [
    '/bigimage.jpg',
    '/largedata.json'
  ]
});

though keep in mind that since the exclusion is by prefix (this is a limitation of the application cache manifest), excluding /largedata.json will also exclude such URLs as /largedata.json.orig and /largedata.json/file1.

For more information about how Meteor interacts with the application cache, see the AppCache page in the Meteor wiki.

accounts-ui

A turn-key user interface for Meteor Accounts.

To add Accounts and a set of login controls to an application, add the accounts-ui package and at least one login provider package: accounts-password, accounts-facebook, accounts-github, accounts-google, accounts-twitter, or accounts-weibo.

Then simply add the {{> loginButtons}} helper to an HTML file. This will place a login widget on the page. If there is only one provider configured and it is an external service, this will add a login/logout button. If you use accounts-password or use multiple external login services, this will add a "Sign in" link which opens a dropdown menu with login options. If you plan to position the login dropdown in the right edge of the screen, use {{> loginButtons align="right"}} in order to get the dropdown to lay itself out without expanding off the edge of the screen.

To configure the behavior of {{> loginButtons}}, use Accounts.ui.config.

accounts-ui also includes modal popup dialogs to handle links from sendResetPasswordEmail, sendVerificationEmail, and sendEnrollmentEmail. These do not have to be manually placed in HTML: they are automatically activated when the URLs are loaded.

If you want to control the look and feel of your accounts system a little more, we recommend reading the useraccounts section of the Meteor Guide.

audit-argument-checks

This package causes Meteor to require that all arguments passed to methods and publish functions are checked. Any method that does not pass each one of its arguments to check will throw an error, which will be logged on the server and which will appear to the client as a 500 Internal server error. This is a simple way to help ensure that your app has complete check coverage.

Methods and publish functions that do not need to validate their arguments can simply run check(arguments, [Match.Any]) to satisfy the audit-argument-checks coverage checker.

coffeescript

CoffeeScript is a little language that compiles into JavaScript. It provides a simple syntax without lots of braces and parentheses. The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime.

CoffeeScript is supported on both the client and the server. Files ending with .coffee, .litcoffee, or .coffee.md are automatically compiled to JavaScript.

Namespacing and CoffeeScript

Here's how CoffeeScript works with Meteor's namespacing.

• Per the usual CoffeeScript convention, CoffeeScript variables are file-scoped by default (visible only in the .coffee file where they are defined.)

• When writing a package, CoffeeScript-defined variables can be exported like any other variable (see Writing Packages). Exporting a variable pulls it up to package scope, meaning that it will be visible to all of the code in your app or package (both .js and .coffee files).

• Package-scope variables declared in .js files are visible in any .coffee files in the same app or project.

• There is no way to make a package-scope variable from a .coffee file other than exporting it. We couldn't figure out a way to make this fit naturally inside the CoffeeScript language. If you want to use package-scope variables with CoffeeScript, one way is to make a short .js file that declares all of your package-scope variables. They can then be used and assigned to from .coffee files.

• If you want to share variables between .coffee files in the same package, and don't want to separately declare them in a .js file, we have an experimental feature that you may like. An object called share is visible in CoffeeScript code and is shared across all .coffee files in the same package. So, you can write share.foo for a value that is shared between all CoffeeScript code in a package, but doesn't escape that package.

Heavy CoffeeScript users, please let us know how this arrangement works for you, whether share is helpful for you, and anything else you'd like to see changed.

ecmascript

This package lets you use new JavaScript language features that are part of the ECMAScript 2015 specification but are not yet supported by all engines or browsers. Unsupported syntax is automatically translated into standard JavaScript that behaves the same way.

This video from the July 2015 Meteor Devshop gives an overview of how the package works, and what it provides.

Usage

The ecmascript package registers a compiler plugin that transpiles ECMAScript 2015+ to ECMAScript 5 (standard JS) in all .js files. By default, this package is pre-installed for all new apps and packages.

To add this package to an existing app, run the following command from your app directory:

meteor add ecmascript

To add the ecmascript package to an existing package, include the statement api.use('ecmascript'); in the Package.onUse callback in your package.js file:

Package.onUse(function (api) {
  api.use('ecmascript');
});

Supported ES2015 Features

Syntax

The ecmascript package uses Babel to compile ES2015 syntax to ES5 syntax. Many but not all ES2015 features can be simulated by Babel, and ecmascript enables most of the features supported by Babel.

Here is a list of the Babel transformers that are currently enabled:

• es3.propertyLiterals
  Makes it safe to use reserved keywords like catch as unquoted keys in object literals. For example, { catch: 123 } is translated to { "catch": 123 }.

• es3.memberExpressionLiterals
  Makes it safe to use reserved keywords as property names. For example, object.catch is translated to object["catch"].

• es6.arrowFunctions
  Provides a shorthand for function expressions. For example, [1, 2, 3].map(x => x + 1) evaluates to [2, 3, 4]. If this is used in the body of the arrow function, it will be automatically bound to the value of this in the enclosing scope.

• es6.literals
  Adds support for binary and octal numeric literals. For example, 0b111110111 === 503 and 0o767 === 503.

• es6.templateLiterals
  Enables multi-line strings delimited by backticks instead of quotation marks, with variable interpolation: js var name = "Ben"; var message = `My name is: ${name}`;

• es6.classes
  Enables class syntax:

  class Base {
  constructor(a, b) {
    this.value = a * b;
  }
  }</p>
  
  <p>class Derived extends Base {
  constructor(a, b) {
    super(a + 1, b + 1);
  }
  }</p>
  
  <p>var d = new Derived(2, 3);
  d.value; // 12
  

• es6.constants
  Allows defining block-scoped variables that are not allowed to be redefined:

  const GOLDEN_RATIO = (1 + Math.sqrt(5)) / 2;</p>
  
  <p>// This reassignment will be forbidden by the compiler:
  GOLDEN_RATIO = "new value";
  

• es6.blockScoping
  Enables the let and const keywords as alternatives to var. The key difference is that variables defined using let or const are visible only within the block where they are declared, rather than being visible anywhere in the enclosing function. For example:

  function example(condition) {
  let x = 0;
  if (condition) {
    let x = 1;
    console.log(x);
  } else {
    console.log(x);
    x = 2;
  }
  return x;
  }</p>
  
  <p>example(true); // logs 1, returns 0
  example(false); // logs 0, returns 2
  

• es6.properties.shorthand
  Allows omitting the value of an object literal property when the desired value is held by a variable that has the same name as the property key. For example, instead of writing { x: x, y: y, z: "asdf" } you can just write { x, y, z: "asdf" }. Methods can also be written without the : function property syntax: js var obj = { oldWay: function (a, b) { ... }, newWay(a, b) { ... } };

• es6.properties.computed
  Allows object literal properties with dynamically computed keys:

  var counter = 0;
  function getKeyName() {
  return "key" + counter++;
  }</p>
  
  <p>var obj = {
  [getKeyName()]: "zero",
  [getKeyName()]: "one",
  };</p>
  
  <p>obj.key0; // "zero"
  obj.key1; // "one"
  

• es6.parameters
  Default expressions for function parameters, evaluated whenever the parameter is undefined, ...rest parameters for capturing remaining arguments without using the arguments object:

  function add(a = 0, ...rest) {
  rest.forEach(n => a += n);
  return a;
  }</p>
  
  <p>add(); // 0
  add(1, 2, 3); // 6
  

• es6.spread
  Allows an array of arguments to be interpolated into a list of arguments to a function call, new expression, or array literal, without using Function.prototype.apply: js add(1, ...[2, 3, 4], 5); // 15 new Node("name", ...children); [1, ...[2, 3, 4], 5]; // [1, 2, 3, 4, 5]

• es6.forOf
  Provides an easy way to iterate over the elements of a collection: js let sum = 0; for (var x of [1, 2, 3]) { sum += x; } x; // 6

• es6.destructuring
  Destructuring is the technique of using an array or object pattern on the left-hand side of an assignment or declaration, in place of the usual variable or parameter, so that certain sub-properties of the value on the right-hand side will be bound to identifiers that appear within the pattern. Perhaps the simplest example is swapping two variables without using a temporary variable: js [a, b] = [b, a]; Extracting a specific property from an object: js let { username: name } = user; // is equivalent to let name = user.username; Instead of taking a single opaque options parameter, a function can use an object destructuring pattern to name the expected options:

  function run({ command, args, callback }) { ... }</p>
  
  <p>run({
  command: "git",
  args: ["status", "."],
  callback(error, status) { ... },
  unused: "whatever"
  });
  

• es7.objectRestSpread
  Supports catch-all ...rest properties in object literal declarations and assignments: js let { x, y, ...rest } = { x: 1, y: 2, a: 3, b: 4 }; x; // 1 y; // 2 rest; // { a: 3, b: 4 } Also enables ...spread properties in object literal expressions: js let n = { x, y, ...rest }; n; // { x: 1, y: 2, a: 3, b: 4 }

• es7.trailingFunctionCommas
  Allows the final parameter of a function to be followed by a comma, provided that parameter is not a ...rest parameter.

• flow
  Permits the use of Flow type annotations. These annotations are simply stripped from the code, so they have no effect on the code's behavior, but you can run the flow tool over your code to check the types if desired.

Polyfills

The ECMAScript 2015 standard library has grown to include new APIs and data structures, some of which can be implemented ("polyfilled") using JavaScript that runs in all engines and browsers today. Here are three new constructors that are guaranteed to be available when the ecmascript package is installed:

• Promise
  A Promise allows its owner to wait for a value that might not be available yet. See this tutorial for more details about the API and motivation. The Meteor Promise implementation is especially useful because it runs all callback functions in recycled Fibers, so you can use any Meteor API, including those that yield (e.g. HTTP.get, Meteor.call, or MongoCollection), and you never have to call Meteor.bindEnvironment.

• Map
  An associative key-value data structure where the keys can be any JavaScript value (not just strings). Lookup and insertion take constant time.

• Set
  A collection of unique JavaScript values of any type. Lookup and insertion take constant time.

• Symbol
  An implementation of the global Symbols namespace that enables a number of other ES2015 features, such as for-of loops and Symbol.iterator methods: [1,2,3][Symbol.iterator]().

• Polyfills for the following Object-related methods:

  • Object.assign
  • Object.is
  • Object.setPrototypeOf
  • Object.prototype.toString (fixes @@toStringTag support)
    

  Complete reference here.

• Polyfills for the following String-related methods:

  • String.fromCodePoint
  • String.raw
  • String.prototype.includes
  • String.prototype.startsWith
  • String.prototype.endsWith
  • String.prototype.repeat
  • String.prototype.codePointAt
  • String.prototype.trim
    

  Complete reference here.

• Polyfills for the following Array-related methods:

  • Array.from
  • Array.of
  • Array.prototype.copyWithin
  • Array.prototype.fill
  • Array.prototype.find
  • Array.prototype.findIndex

  Complete reference here.

• Polyfills for the following Function-related properties:

  • Function.prototype.name (fixes IE9+)
  • Function.prototype[Symbol.hasInstance] (fixes IE9+)

  Complete reference here.

jquery

jQuery is a fast and concise JavaScript Library that simplifies HTML document traversing, event handling, animating, and Ajax interactions for rapid web development.

The jquery package adds the jQuery library to the client JavaScript bundle. It has no effect on the server.

In addition to the jquery package, Meteor provides several jQuery plugins as separate packages. These include:

• jquery-history
• jquery-layout
• jquery-waypoints

less

LESS extends CSS with dynamic behavior such as variables, mixins, operations and functions. It allows for more compact stylesheets and helps reduce code duplication in CSS files.

With the less package installed, .less files in your application are automatically compiled to CSS and the results are included in the client CSS bundle.

markdown

This package lets you use Markdown in your templates. It's easy: just put your markdown inside {{#markdown}} ... {{/markdown}} tags. You can still use all of the usual Meteor template features inside a Markdown block, such as {{#each}}, and you still get reactivity.

Example:

{{#markdown}}I am using __markdown__.{{/markdown}}

outputs

<p>I am using <strong>markdown</strong>.</p>

modules

Though Meteor 1.2 introduced support for many new ECMAScript 2015 features, one of the most notable omissions was ES2015 import and export syntax. Meteor 1.3 fills that gap with a fully standards-compliant module system that works on both the client and the server, solves multiple long-standing problems for Meteor applications (such as controlling file load order), and yet maintains full backwards compatibility with existing Meteor code. This document explains the usage and key features of the new module system.

Enabling modules

We think you’re going to love the new module system, and that's why it will be installed by default for all new apps and packages. Nevertheless, the modules package is totally optional, and it will be up to you to add it to existing apps and/or packages.

For apps, this is as easy as meteor add modules, or (even better) meteor add ecmascript, since the ecmascript package implies the modules package.

For packages, you can enable modules by adding api.use("modules") to the Package.onUse or Package.onTest sections of your package.js file.

Now, you might be wondering what good the modules package is without the ecmascript package, since ecmascript enables import and export syntax. By itself, the modules package provides the CommonJS require and exports primitives that may be familiar if you’ve ever written Node code, and the ecmascript package simply compiles import and export statements to CommonJS. The require and export primitives also allow Node modules to run within Meteor application code without modification. Furthermore, keeping modules separate allows us to use require and exports in places where using ecmascript is tricky, such as the implementation of the ecmascript package itself.

While the modules package is useful by itself, we very much encourage using the ecmascript package (and thus import and export) instead of using require and exports directly. If you need convincing, here’s a presentation that explains the differences: http://benjamn.github.io/empirenode-2015

Basic syntax

Although there are a number of different variations of import and export syntax, this section describes the essential forms that everyone should know.

First, you can export any named declaration on the same line where it was declared:

// exporter.js
export var a = ...;
export let b = ...;
export const c = ...;
export function d() {...}
export function* e() {...}
export class F {...}

These declarations make the variables a, b, c (and so on) available not only within the scope of the exporter.js module, but also to other modules that import from exporter.js.

If you prefer, you can export variables by name, rather than prefixing their declarations with the export keyword:

// exporter.js
function g() {...}
let h = g();

// at the end of the file
export {g, h};

All of these exports are named, which means other modules can import them using those names:

// importer.js
import {a, c, F, h} from "./exporter";
new F(a, c).method(h);

If you’d rather use different names, you’ll be glad to know export and import statements can rename their arguments:

// exporter.js
export {g as x};
g(); // same as calling y() in importer.js

// importer.js
import {x as y} from "./exporter";
y(); // same as calling g() in exporter.js

As with CommonJS module.exports, it is possible to define a single default export:

// exporter.js
export default any.arbitrary(expression);

This default export may then be imported without curly braces, using any name the importing module chooses:

// importer.js
import Value from "./exporter";
// Value is identical to the exported expression

Unlike CommonJS module.exports, the use of default exports does not prevent the simultaneous use of named exports. Here is how you can combine them:

// importer.js
import Value, {a, F} from "./exporter";

In fact, the default export is conceptually just another named export whose name happens to be "default":

// importer.js
import {default as Value, a, F} from "./exporter";

These examples should get you started with import and export syntax. For further reading, here is a very detailed explanation by Axel Rauschmayer of every variation of import and export syntax.

Modular application structure

Before the release of Meteor 1.3, the only way to share values between files in an application was to assign them to global variables or communicate through shared variables like Session (variables which, while not technically global, sure do feel syntactically identical to global variables). With the introduction of modules, one module can refer precisely to the exports of any other specific module, so global variables are no longer necessary.

If you are familiar with modules in Node, you might expect modules not to be evaluated until the first time you import them. However, because earlier versions of Meteor evaluated all of your code when the application started, and we care about backwards compatibility, eager evaluation is still the default behavior.

If you would like a module to be evaluated lazily (in other words: on demand, the first time you import it, just like Node does it), then you should put that module in an imports/ directory (anywhere in your app, not just the root directory), and include that directory when you import the module: import {stuff} from "./imports/lazy". Note: files contained by node_modules/ directories will also be evaluated lazily (more on that below).

Lazy evaluation will very likely become the default behavior in a future version of Meteor, but if you want to embrace it as fully as possible in the meantime, we recommend putting all your modules inside either client/imports/ or server/imports/ directories, with just a single entry point for each architecture: client/main.js and server/main.js. The main.js files will be evaluated eagerly, giving your application a chance to import modules from the imports/ directories.

Modular package structure

If you are a package author, in addition to putting api.use("modules") or api.use("ecmascript") in the Package.onUse section of your package.js file, you can also use a new API called api.mainModule to specify the main entry point for your package:

Package.describe({
  name: "my-modular-package"
});

Npm.depends({
  moment: "2.10.6"
});

Package.onUse(function (api) {
  api.use("modules");
  api.mainModule("server.js", "server");
  api.mainModule("client.js", "client");
  api.export("Foo");
});

Now server.js and client.js can import other files from the package source directory, even if those files have not been added using the api.addFiles function.

When you use api.mainModule, the exports of the main module are exposed globally as Package["my-modular-package"], along with any symbols exported by api.export, and thus become available to any code that imports the package. In other words, the main module gets to decide what value of Foo will be exported by api.export, as well as providing other properties that can be explicitly imported from the package:

// In an application that uses my-modular-package:
import {Foo as ExplicitFoo, bar} from "meteor/my-modular-package";
console.log(Foo); // Auto-imported because of api.export.
console.log(ExplicitFoo); // Explicitly imported, but identical to Foo.
console.log(bar); // Exported by server.js or client.js, but not auto-imported.

Note that the import is from "meteor/my-modular-package", not from "my-modular-package". Meteor package identifier strings must include the prefix meteor/... to disambiguate them from npm packages.

Finally, since this package is using the new modules package, and the package Npm.depends on the "moment" npm package, modules within the package can import moment from "moment" on both the client and the server. This is great news, because previous versions of Meteor allowed npm imports only on the server, via Npm.require.

Local node_modules

Before Meteor 1.3, the contents of node_modules directories in Meteor application code were completely ignored. When you enable modules, those useless node_modules directories suddenly become infinitely more useful:

meteor create modular-app
cd modular-app
mkdir node_modules
npm install moment
echo 'import moment from "moment";' >> modular-app.js
echo 'console.log(moment().calendar());' >> modular-app.js
meteor

When you run this app, the moment library will be imported on both the client and the server, and both consoles will log output similar to: Today at 7:51 PM. Our hope is that the possibility of installing Node modules directly within an app will reduce the need for npm wrapper packages such as https://atmospherejs.com/momentjs/moment.

A version of the npm command comes bundled with every Meteor installation, and (as of Meteor 1.3) it's quite easy to use: meteor npm ... is synonymous with npm ..., so meteor npm install moment will work in the example above. (Likewise, if you don't have a version of node installed, or you want to be sure you're using the exact same version of node that Meteor uses, meteor node ... is a convenient shortcut.) That said, you can use any version of npm that you happen to have available. Meteor's module system only cares about the files installed by npm, not the details of how npm installs those files.

File load order

Before Meteor 1.3, the order in which application files were evaluated was dictated by a set of rules described in the Structuring Your Application section of the docs (see File Load Order subheading). These rules could become frustrating when one file depended on a variable defined by another file, particularly when the first file was evaluated after the second file.

Thanks to modules, any load-order dependency you might imagine can be resolved by adding an import statement. So if a.js loads before b.js because of their file names, but a.js needs something defined by b.js, then a.js can simply import that value from b.js:

// a.js
import {bThing} from "./b";
console.log(bThing, "in a.js");

// b.js
export var bThing = "a thing defined in b.js";
console.log(bThing, "in b.js");

Sometimes a module doesn’t actually need to import anything from another module, but you still want to be sure the other module gets evaluated first. In such situations, you can use an even simpler import syntax:

// c.js
import "./a";
console.log("in c.js");

No matter which of these modules is imported first, the order of the console.log calls will always be:

console.log(bThing, "in b.js");
console.log(bThing, "in a.js");
console.log("in c.js");

oauth-encryption

Encrypts sensitive login secrets stored in the database such as a login service's application secret key and users' access tokens.

Generating a Key

The encryption key is 16 bytes, encoded in base64.

To generate a key:

$ ~/.meteor/tools/latest/bin/node -e 'console.log(require("crypto").randomBytes(16).toString("base64"))'

Using oauth-encryption with accounts

On the server only, use the oauthSecretKey option to Accounts.config:

Accounts.config({oauthSecretKey: "onsqJ+1e4iGFlV0nhZYobg=="});

This call to Accounts.config should be made at load time (place at the top level of your source file), not called from inside of a Meteor.startup block.

To avoid storing the secret key in your application's source code, you can use Meteor.settings:

Accounts.config({oauthSecretKey: Meteor.settings.oauthSecretKey});

Migrating unencrypted user tokens

This example for Twitter shows how existing unencrypted user tokens can be encrypted. The query finds user documents which have a Twitter access token but not the algorithm field which is created when the token is encrypted. The relevant fields in the service data are then encrypted.

Meteor.users.find({ $and: [
    { 'services.twitter.accessToken': {$exists: true} },
    { 'services.twitter.accessToken.algorithm': {$exists: false} }
  ] }).
forEach(function (userDoc) {
  var set = {};
  _.each(['accessToken', 'accessTokenSecret', 'refreshToken'], function (field) {
    var plaintext = userDoc.services.twitter[field];
    if (!_.isString(plaintext))
      return;
    set['services.twitter.' + field] = OAuthEncryption.seal(
      userDoc.services.twitter[field],
      userDoc._id
    );
  });
  Meteor.users.update(userDoc._id, {$set: set});
});

Using oauth-encryption without accounts

If you're using the oauth packages directly instead of through the Meteor accounts packages, you can load the OAuth encryption key directly using OAuthEncryption.loadKey:

OAuthEncryption.loadKey("onsqJ+1e4iGFlV0nhZYobg==");

If you call retrieveCredential (such as Twitter.retrieveCredential) as part of your process, you'll find when using oauth-encryption that the sensitive service data fields will be encrypted.

You can decrypt them using OAuth.openSecrets:

var credentials = Twitter.retrieveCredential(token);
var serviceData = OAuth.openSecrets(credentials.serviceData);

Using oauth-encryption on Windows

This package depends on npm-node-aes-gcm, which requires you to have OpenSSL installed on your system to run. To install OpenSSL on Windows, use one of the binaries on this page. Don't forget to install the Visual Studio 2008 redistributables if you don't have them yet.

random

The random package provides several functions for generating random numbers. It uses a cryptographically strong pseudorandom number generator when possible, but falls back to a weaker random number generator when cryptographically strong randomness is not available (on older browsers or on servers that don't have enough entropy to seed the cryptographically strong generator).

Random.id([n])

Returns a unique identifier, such as "Jjwjg6gouWLXhMGKW", that is likely to be unique in the whole world. The optional argument n specifies the length of the identifier in characters and defaults to 17.

Random.secret([n])

Returns a random string of printable characters with 6 bits of entropy per character. The optional argument n specifies the length of the secret string and defaults to 43 characters, or 256 bits of entropy. Use Random.secret for security-critical secrets that are intended for machine, rather than human, consumption.

Random.fraction()

Returns a number between 0 and 1, like Math.random.

Random.choice(arrayOrString)

Returns a random element of the given array or string.

Random.hexString(n)

Returns a random string of n hexadecimal digits.

spacebars

Spacebars is a Meteor template language inspired by Handlebars. It shares some of the spirit and syntax of Handlebars, but it has been tailored to produce reactive Meteor templates when compiled.

Getting Started

A Spacebars template consists of HTML interspersed with template tags, which are delimited by {{ and }} (two curly braces).

<template name="myPage">
  <h1>{{pageTitle}}</h1>

  {{> nav}}

  {{#each posts}}
    <div class="post">
      <h3>{{title}}</h3>
      <div class="post-content">
        {{{content}}}
      </div>
    </div>
  {{/each}}
</template>

As illustrated by the above example, there are four major types of template tags:

• {{pageTitle}} - Double-braced template tags are used to insert a string of text. The text is automatically made safe. It may contain any characters (like <) and will never produce HTML tags.

• {{> nav}} - Inclusion template tags are used to insert another template by name.

• {{#each}} - Block template tags are notable for having a block of content. The block tags #if, #each, #with, and #unless are built in, and it is also possible define custom ones. Some block tags, like #each and #with, establish a new data context for evaluating their contents. In the above example, {{title}} and {{content}} most likely refer to properties of the current post (though they could also refer to template helpers).

• {{{content}}} - Triple-braced template tags are used to insert raw HTML. Be careful with these! It's your job to make sure the HTML is safe, either by generating it yourself or sanitizing it if it came from a user input.

Reactivity Model

Spacebars templates update reactively at a fine-grained level in response to changing data.

Each template tag's DOM is updated automatically when it evaluates to a new value, while avoiding unnecessary re-rendering as much as possible. For example, a double-braced tag replace its text node when its text value changes. An #if re-renders its contents only when the condition changes from truthy to falsy or vice versa.

Identifiers and Paths

A Spacebars identifier is either a JavaScript identifier name or any string enclosed in square brackets ([ and ]). There are also the special identifiers this (or equivalently, .) and ... Brackets are required to use one of the following as the first element of a path: else, this, true, false, and null. Brackets are not required around JavaScript keywords and reserved words like var and for.

A Spacebars path is a series of one or more identifiers separated by either . or /, such as foo, foo.bar, this.name, ../title, or foo.[0] (numeric indices must be enclosed in brackets).

Name Resolution

The first identifier in a path is resolved in one of two ways:

• Indexing the current data context. The identifier foo refers to the foo property of the current data context object.

• As a template helper. The identifier foo refers to a helper function (or constant value) that is accessible from the current template.

Template helpers take priority over properties of the data context.

If a path starts with .., then the enclosing data context is used instead of the current one. The enclosing data context might be the one outside the current #each, #with, or template inclusion.

Path Evaluation

When evaluating a path, identifiers after the first are used to index into the object so far, like JavaScript's .. However, an error is never thrown when trying to index into a non-object or an undefined value.

In addition, Spacebars will call functions for you, so {{foo.bar}} may be taken to mean foo().bar, foo.bar(), or foo().bar() as appropriate.

Helper Arguments

An argument to a helper can be any path or identifier, or a string, boolean, or number literal, or null.

Double-braced and triple-braced template tags take any number of positional and keyword arguments:

{{frob a b c verily=true}}

calls:

frob(a, b, c, Spacebars.kw({verily: true}))

Spacebars.kw constructs an object that is instanceof Spacebars.kw and whose .hash property is equal to its argument.

The helper's implementation can access the current data context as this.

Inclusion and Block Arguments

Inclusion tags ({{> foo}}) and block tags ({{#foo}}) take a single data argument, or no argument. Any other form of arguments will be interpreted as an object specification or a nested helper:

• Object specification: If there are only keyword arguments, as in {{#with x=1 y=2}} or {{> prettyBox color=red}}, the keyword arguments will be assembled into a data object with properties named after the keywords.

• Nested Helper: If there is a positional argument followed by other (positional or keyword arguments), the first argument is called on the others using the normal helper argument calling convention.

Template Tag Placement Limitations

Unlike purely string-based template systems, Spacebars is HTML-aware and designed to update the DOM automatically. As a result, you can't use a template tag to insert strings of HTML that don't stand on their own, such as a lone HTML start tag or end tag, or that can't be easily modified, such as the name of an HTML element.

There are three main locations in the HTML where template tags are allowed:

• At element level (i.e. anywhere an HTML tag could go)
• In an attribute value
• In a start tag in place of an attribute name/value pair

The behavior of a template tag is affected by where it is located in the HTML, and not all tags are allowed at all locations.

Double-braced Tags

A double-braced tag at element level or in an attribute value typically evalutes to a string. If it evalutes to something else, the value will be cast to a string, unless the value is null, undefined, or false, which results in nothing being displayed.

Values returned from helpers must be pure text, not HTML. (That is, strings should have <, not <.) Spacebars will perform any necessary escaping if a template is rendered to HTML.

SafeString

If a double-braced tag at element level evalutes to an object created with Spacebars.SafeString("<span>Some HTML</span>"), the HTML is inserted at the current location. The code that calls SafeString is asserting that this HTML is safe to insert.

In Attribute Values

A double-braced tag may be part of, or all of, an HTML attribute value:

<input type="checkbox" class="checky {{moreClasses}}" checked={{isChecked}}>

An attribute value that consists entirely of template tags that return null, undefined, or false is considered absent; otherwise, the attribute is considered present, even if its value is empty.

Dynamic Attributes

A double-braced tag can be used in an HTML start tag to specify an arbitrary set of attributes:

<div {{attrs}}>...</div>

<input type=checkbox {{isChecked}}>

The tag must evaluate to an object that serves as a dictionary of attribute name and value strings. For convenience, the value may also be a string or null. An empty string or null expands to {}. A non-empty string must be an attribute name, and expands to an attribute with an empty value; for example, "checked" expands to {checked: ""} (which, as far as HTML is concerned, means the checkbox is checked).

To summarize:

You can combine multiple dynamic attributes tags with other attributes:

<div id=foo class={{myClass}} {{attrs1}} {{attrs2}}>...</div>

Attributes from dynamic attribute tags are combined from left to right, after normal attributes, with later attribute values overwriting previous ones. Multiple values for the same attribute are not merged in any way, so if attrs1 specifies a value for the class attribute, it will overwrite {{myClass}}. As always, Spacebars takes care of recalculating the element's attributes if any of myClass, attrs1, or attrs2 changes reactively.

Triple-braced Tags

Triple-braced tags are used to insert raw HTML into a template:

<div class="snippet">
  {{{snippetBody}}}
</div>

The inserted HTML must consist of balanced HTML tags. You can't, for example, insert "</div><div>" to close an existing div and open a new one.

This template tag cannot be used in attributes or in an HTML start tag.

Inclusion Tags

An inclusion tag takes the form {{> templateName}} or {{> templateName dataObj}}. Other argument forms are syntactic sugar for constructing a data object (see Inclusion and Block Arguments).

An inclusion tag inserts an instantiation of the given template at the current location. If there is an argument, it becomes the data context, much as if the following code were used:

{{#with dataObj}}
  {{> templateName}}
{{/with}}

Instead of simply naming a template, an inclusion tag can also specify a path that evalutes to a template object, or to a function that returns a template object.

Note that the above two points interact in a way that can be surprising! If foo is a template helper function that returns another template, then {{>foo bar}} will first push bar onto the data context stack then call foo(), due to the way this line is expanded as shown above. You will need to use Template.parentData(1) to access the original context. This differs from regular helper calls like {{foo bar}}, in which bar is passed as a parameter rather than pushed onto the data context stack.

Function Returning a Template

If an inclusion tag resolves to a function, the function must return a template object or null. The function is reactively re-run, and if its return value changes, the template will be replaced.

Block Tags

Block tags invoke built-in directives or custom block helpers, passing a block of template content that may be instantiated once, more than once, or not at all by the directive or helper.

{{#block}}
  <p>Hello</p>
{{/block}}

Block tags may also specify "else" content, separated from the main content by the special template tag {{else}}.

A block tag's content must consist of HTML with balanced tags.

Block tags can be used inside attribute values:

<div class="{{#if done}}done{{else}}notdone{{/if}}">
  ...
</div>

If/Unless

An #if template tag renders either its main content or its "else" content, depending on the value of its data argument. Any falsy JavaScript value (including null, undefined, 0, "", and false) is considered false, as well as the empty array, while any other value is considered true.

{{#if something}}
  <p>It's true</p>
{{else}}
  <p>It's false</p>
{{/if}}

#unless is just #if with the condition inverted.

With

A #with template tag establishes a new data context object for its contents. The properties of the data context object are where Spacebars looks when resolving template tag names.

{{#with employee}}
  <div>Name: {{name}}</div>
  <div>Age: {{age}}</div>
{{/with}}

We can take advantage of the object specification form of a block tag to define an object with properties we name:

{{#with x=1 y=2}}
  {{{getHTMLForPoint this}}}
{{/with}}

If the argument to #with is falsy (by the same rules as for #if), the content is not rendered. An "else" block may be provided, which will be rendered instead.

If the argument to #with is a string or other non-object value, it may be promoted to a JavaScript wrapper object (also known as a boxed value) when passed to helpers, because JavaScript traditionally only allows an object for this. Use String(this) to get an unboxed string value or Number(this) to get an unboxed number value.

Each

An #each template tag takes a sequence argument and inserts its content for each item in the sequence, setting the data context to the value of that item:

<ul>
{{#each people}}
  <li>{{name}}</li>
{{/each}}
</ul>

The newer variant of #each doesn't change the data context but introduces a new variable that can be used in the body to refer to the current item:

<ul>
{{#each person in people}}
  <li>{{person.name}}</li>
{{/each}}
</ul>

The argument is typically a Meteor cursor (the result of collection.find(), for example), but it may also be a plain JavaScript array, null, or undefined.

An "else" section may be provided, which is used (with no new data context) if there are zero items in the sequence at any time.

You can use a special variable @index in the body of #each to get the 0-based index of the currently rendered value in the sequence.

Reactivity Model for Each

When the argument to #each changes, the DOM is always updated to reflect the new sequence, but it's sometimes significant exactly how that is achieved. When the argument is a Meteor live cursor, the #each has access to fine-grained updates to the sequence -- add, remove, move, and change callbacks -- and the items are all documents identified by unique ids. As long as the cursor itself remains constant (i.e. the query doesn't change), it is very easy to reason about how the DOM will be updated as the contents of the cursor change. The rendered content for each document persists as long as the document is in the cursor, and when documents are re-ordered, the DOM is re-ordered.

Things are more complicated if the argument to the #each reactively changes between different cursor objects, or between arrays of plain JavaScript objects that may not be identified clearly. The implementation of #each tries to be intelligent without doing too much expensive work. Specifically, it tries to identify items between the old and new array or cursor with the following strategy:

1. For objects with an _id field, use that field as the identification key
2. For objects with no _id field, use the array index as the identification key. In this case, appends are fast but prepends are slower.
3. For numbers or strings, use their value as the identification key.

In case of duplicate identification keys, all duplicates after the first are replaced with random ones. Using objects with unique _id fields is the way to get full control over the identity of rendered elements.

Let

The #let tag creates a new alias variable for a given expression. While it doesn't change the data context, it allows to refer to an expression (helper, data context, another variable) with a short-hand within the template:

{{#let name=person.bio.firstName color=generateColor}}
  <div>{{name}} gets a {{color}} card!</div>
{{/let}}

Variables introduced this way take precedence over names of templates, global helpers, fields of the current data context and previously introduced variables with the same name.

Custom Block Helpers

To define your own block helper, simply declare a template, and then invoke it using {{#someTemplate}} (block) instead of {{> someTemplate}} (inclusion) syntax.

When a template is invoked as a block helper, it can use {{> Template.contentBlock}} and {{> Template.elseBlock}} to include the block content it was passed.

Here is a simple block helper that wraps its content in a div:

<template name="note">
  <div class="note">
    {{> Template.contentBlock}}
  </div>
</template>

You would invoke it as:

{{#note}}
  Any content here
{{/note}}

Here is an example of implementing #unless in terms of #if (ignoring for the moment that unless is a built-in directive):

<template name="unless">
  {{#if this}}
    {{> Template.elseBlock}}
  {{else}}
    {{> Template.contentBlock}}
  {{/if}}
</template>

Note that the argument to #unless (the condition) becomes the data context in the unless template and is accessed via this. However, it would not work very well if this data context was visible to Template.contentBlock, which is supplied by the user of unless.

Therefore, when you include {{> Template.contentBlock}}, Spacebars hides the data context of the calling template, and any data contexts established in the template by #each and #with. They are not visible to the content block, even via ... Put another way, it's as if the {{> Template.contentBlock}} inclusion occurred at the location where {{#unless}} was invoked, as far as the data context stack is concerned.

You can pass an argument to {{> Template.contentBlock}} or {{> Template.elseBlock}} to invoke it with a data context of your choice. You can also use {{#if Template.contentBlock}} to see if the current template was invoked as a block helper rather than an inclusion.

Comment Tags

Comment template tags begin with {{! and can contain any characters except for }}. Comments are removed upon compilation and never appear in the compiled template code or the generated HTML.

{{! Start of a section}}
<div class="section">
  ...
</div>

Comment tags also come in a "block comment" form. Block comments may contain {{ and }}:

{{!-- This is a block comment.
We can write {{foo}} and it doesn't matter.
{{#with x}}This code is commented out.{{/with}}
--}}

Comment tags can be used wherever other template tags are allowed.

Nested sub-expressions

Sometimes an argument to a helper call is best expressed as a return value of some other expression. For this and other cases, one can use parentheses to express the evaluation order of nested expressions.

{{capitalize (getSummary post)}}

In this example, the result of the getSummary helper call will be passed to the capitalize helper.

Sub-expressions can be used to calculate key-word arguments, too:

{{> tmpl arg=(helper post)}}

HTML Dialect

Spacebars templates are written in standard HTML extended with additional syntax (i.e. template tags).

Spacebars validates your HTML as it goes and will throw a compile-time error if you violate basic HTML syntax in a way that prevents it from determining the structure of your code.

Spacebars is not lenient about malformed markup the way a web browser is. While the latest HTML spec standardizes how browsers should recover from parse errors, these cases are still not valid HTML. For example, a browser may recover from a bare < that does not begin a well-formed HTML tag, while Spacebars will not. However, gone are the restrictions of the XHTML days; attribute values do not have to quoted, and tags are not case-sensitive, for example.

You must close all HTML tags except the ones specified to have no end tag, like BR, HR, IMG and INPUT. You can write these tags as <br> or equivalently <br/>.

The HTML spec allows omitting some additional end tags, such as P and LI, but Spacebars doesn't currently support this.

Top-level Elements in a .html file

Technically speaking, the <template> element is not part of the Spacebars language. A foo.html template file in Meteor consists of one or more of the following elements:

• <template name="myName"> - The <template> element contains a Spacebars template (as defined in the rest of this file) which will be compiled to the Template.myName component.

• <head> - Static HTML that will be inserted into the <head> element of the default HTML boilerplate page. Cannot contain template tags. If <head> is used multiple times (perhaps in different files), the contents of all of the <head> elements are concatenated.

• <body> - A template that will be inserted into the <body> of the main page. It will be compiled to the Template.body component. If <body> is used multiple times (perhaps in different files), the contents of all of the <body> elements are concatenated.

Escaping Curly Braces

To insert a literal {{, {{{, or any number of curly braces, put a vertical bar after it. So {{| will show up as {{, {{{| will show up as {{{, and so on.

underscore

Underscore is a utility-belt library for JavaScript that provides support for functional programming. It is invaluable for writing clear, concise JavaScript in a functional style.

The underscore package defines the _ namespace on both the client and the server.

webapp

The webapp package is what lets your Meteor app serve content to a web browser. It is included in the meteor-base set of packages that is automatically added when you run meteor create. You can easily build a Meteor app without it - for example if you wanted to make a command-line tool that still used the Meteor package system and DDP.

This package also allows you to add handlers for HTTP requests. This lets other services access your app's data through an HTTP API, allowing it to easily interoperate with tools and frameworks that don't yet support DDP.

webapp exposes the connect API for handling requests through WebApp.connectHandlers. Here's an example that will let you handle a specific URL:

// Listen to incoming HTTP requests, can only be used on the server
WebApp.connectHandlers.use("/hello", function(req, res, next) {
  res.writeHead(200);
  res.end("Hello world from: " + Meteor.release);
});

WebApp.connectHandlers.use([path], handler) has two arguments:

path - an optional path field. This handler will only be called on paths that match this string. The match has to border on a / or a .. For example, /hello will match /hello/world and /hello.world, but not /hello_world.

handler - this is a function that takes three arguments:

• req - a Node.js IncomingMessage object with some extra properties. This argument can be used to get information about the incoming request.
• res - a Node.js ServerResponse object. Use this to write data that should be sent in response to the request, and call res.end() when you are done.
• next - a function. Calling this function will pass on the handling of this request to the next relevant handler.