The goal of this blog post is to give you a brief introduction to Meteor which is a framework for building Single Page Apps. In this blog entry, I provide a walkthrough of building a simple Movie database app.

What is special about Meteor? Meteor has two jaw-dropping features:

Live HTML – If you make any changes to the HTML, CSS, JavaScript, or data on the server then every client shows the changes automatically without a browser refresh. For example, if you change the background color of a page to yellow then every open browser will show the new yellow background color without a refresh. Or, if you add a new movie to a collection of movies, then every open browser will display the new movie automatically.

With Live HTML, users no longer need a refresh button. Changes to an application happen everywhere automatically without any effort. The Meteor framework handles all of the messy details of keeping all of the clients in sync with the server for you.

Latency Compensation – When you modify data on the client, these modifications appear as if they happened on the server without any delay. For example, if you create a new movie then the movie appears instantly. However, that is all an illusion. In the background, Meteor updates the database with the new movie. If, for whatever reason, the movie cannot be added to the database then Meteor removes the movie from the client automatically.

Latency compensation is extremely important for creating a responsive web application. You want the user to be able to make instant modifications in the browser and the framework to handle the details of updating the database without slowing down the user.

Installing Meteor

Meteor is licensed under the open-source MIT license and you can start building production apps with the framework right now. Be warned that Meteor is still in the “early preview” stage. It has not reached a 1.0 release. According to the Meteor FAQ, Meteor will reach version 1.0 in “More than a month, less than a year.”

Don’t be scared away by that. You should be aware that, unlike most open source projects, Meteor has financial backing. The Meteor project received an $11.2 million round of financing from Andreessen Horowitz. So, it would be a good bet that this project will reach the 1.0 mark. And, if it doesn’t, the framework as it exists right now is still very powerful.

Meteor runs on top of Node.js. You write Meteor apps by writing JavaScript which runs both on the client and on the server. You can build Meteor apps on Windows, Mac, or Linux (Although the support for Windows is still officially unofficial).

If you want to install Meteor on Windows then download the MSI from the following URL:

http://win.meteor.com/

If you want to install Meteor on Mac/Linux then run the following CURL command from your terminal:

curl https://install.meteor.com | /bin/sh

Meteor will install all of its dependencies automatically including Node.js. However, I recommend that you install Node.js before installing Meteor by installing Node.js from the following address:

http://nodejs.org/

If you let Meteor install Node.js then Meteor won’t install NPM which is the standard package manager for Node.js. If you install Node.js and then you install Meteor then you get NPM automatically.

Creating a New Meteor App

To get a sense of how Meteor works, I am going to walk through the steps required to create a simple Movie database app. Our app will display a list of movies and contain a form for creating a new movie.

The first thing that we need to do is create our new Meteor app. Open a command prompt/terminal window and execute the following command:

Meteor create MovieApp

After you execute this command, you should see something like the following:

Follow the instructions: execute cd MovieApp to change to your MovieApp directory, and run the meteor command.

Executing the meteor command starts Meteor on port 3000. Open up your favorite web browser and navigate to http://localhost:3000 and you should see the default Meteor Hello World page:

Open up your favorite development environment to see what the Meteor app looks like. Open the MovieApp folder which we just created. Here’s what the MovieApp looks like in Visual Studio 2012:

Notice that our MovieApp contains three files named MovieApp.css, MovieApp.html, and MovieApp.js. In other words, it contains a Cascading Style Sheet file, an HTML file, and a JavaScript file.

Just for fun, let’s see how the Live HTML feature works. Open up multiple browsers and point each browser at http://localhost:3000. Now, open the MovieApp.html page and modify the text “Hello World!” to “Hello Cruel World!” and save the change. The text in all of the browsers should update automatically without a browser refresh. Pretty amazing, right?

Controlling Where JavaScript Executes

You write a Meteor app using JavaScript. Some of the JavaScript executes on the client (the browser) and some of the JavaScript executes on the server and some of the JavaScript executes in both places.

For a super simple app, you can use the Meteor.isServer and Meteor.isClient properties to control where your JavaScript code executes. For example, the following JavaScript contains a section of code which executes on the server and a section of code which executes in the browser:

if (Meteor.isClient) {
    console.log("Hello Browser!");
}

if (Meteor.isServer) {
    console.log("Hello Server!");
}

console.log("Hello Browser and Server!");

When you run the app, the message “Hello Browser!” is written to the browser JavaScript console. The message “Hello Server!” is written to the command/terminal window where you ran Meteor. Finally, the message “Hello Browser and Server!” is execute on both the browser and server and the message appears in both places.

For simple apps, using Meteor.isClient and Meteor.isServer to control where JavaScript executes is fine. For more complex apps, you should create separate folders for your server and client code. Here are the folders which you can use in a Meteor app:

· client – This folder contains any JavaScript which executes only on the client.

· server – This folder contains any JavaScript which executes only on the server.

· common – This folder contains any JavaScript code which executes on both the client and server.

· lib – This folder contains any JavaScript files which you want to execute before any other JavaScript files.

· public – This folder contains static application assets such as images.

For the Movie App, we need the client, server, and common folders.

Delete the existing MovieApp.js, MovieApp.html, and MovieApp.css files. We will create new files in the right locations later in this walkthrough.

Combining HTML, CSS, and JavaScript Files

Meteor combines all of your JavaScript files, and all of your Cascading Style Sheet files, and all of your HTML files automatically. If you want to create one humongous JavaScript file which contains all of the code for your app then that is your business. However, if you want to build a more maintainable application, then you should break your JavaScript files into many separate JavaScript files and let Meteor combine them for you.

Meteor also combines all of your HTML files into a single file. HTML files are allowed to have the following top-level elements:

<head> — All <head> files are combined into a single <head> and served with the initial page load.

<body> — All <body> files are combined into a single <body> and served with the initial page load.

<template> — All <template> files are compiled into JavaScript templates.

Because you are creating a single page app, a Meteor app typically will contain a single HTML file for the <head> and <body> content. However, a Meteor app typically will contain several template files. In other words, all of the interesting stuff happens within the <template> files.

Displaying a List of Movies

Let me start building the Movie App by displaying a list of movies.

In order to display a list of movies, we need to create the following four files:

· client\movies.html – Contains the HTML for the <head> and <body> of the page for the Movie app.

· client\moviesTemplate.html – Contains the HTML template for displaying the list of movies.

· client\movies.js – Contains the JavaScript for supplying data to the moviesTemplate.

· server\movies.js – Contains the JavaScript for seeding the database with movies.

After you create these files, your folder structure should looks like this:

Here’s what the client\movies.html file looks like:

<head>
    <title>My Movie App</title>
</head>

<body>
    <h1>Movies</h1>
    {{> moviesTemplate }}
</body>

Notice that it contains <head> and <body> top-level elements. The <body> element includes the moviesTemplate with the syntax {{> moviesTemplate }}.

The moviesTemplate is defined in the client/moviesTemplate.html file:

<template name="moviesTemplate">
    <ul>
    {{#each movies}}
    <li>
        {{title}}
    </li>
    {{/each}}
    </ul>
</template>

By default, Meteor uses the Handlebars templating library. In the moviesTemplate above, Handlebars is used to loop through each of the movies using {{#each}}…{{/each}} and display the title for each movie using {{title}}.

The client\movies.js JavaScript file is used to bind the moviesTemplate to the Movies collection on the client. Here’s what this JavaScript file looks like:

// Declare client Movies collection
Movies = new Meteor.Collection("movies");

// Bind moviesTemplate to Movies collection
Template.moviesTemplate.movies = function () {
    return Movies.find();
};

The Movies collection is a client-side proxy for the server-side Movies database collection. Whenever you want to interact with the collection of Movies stored in the database, you use the Movies collection instead of communicating back to the server.

The moviesTemplate is bound to the Movies collection by assigning a function to the Template.moviesTemplate.movies property. The function simply returns all of the movies from the Movies collection.

The final file which we need is the server-side server\movies.js file:

// Declare server Movies collection
Movies = new Meteor.Collection("movies");

// Seed the movie database with a few movies
Meteor.startup(function () {
    if (Movies.find().count() == 0) {
        Movies.insert({ title: "Star Wars", director: "Lucas" });
        Movies.insert({ title: "Memento", director: "Nolan" });
        Movies.insert({ title: "King Kong", director: "Jackson" });
    }
});

The server\movies.js file does two things. First, it declares the server-side Meteor Movies collection. When you declare a server-side Meteor collection, a collection is created in the MongoDB database associated with your Meteor app automatically (Meteor uses MongoDB as its database automatically).

Second, the server\movies.js file seeds the Movies collection (MongoDB collection) with three movies. Seeding the database gives us some movies to look at when we open the Movies app in a browser.

Creating New Movies

Let me modify the Movies Database App so that we can add new movies to the database of movies. First, I need to create a new template file – named client\movieForm.html – which contains an HTML form for creating a new movie:

<template name="movieForm">
    <fieldset>
    <legend>Add New Movie</legend>
    <form>
        <div>
            <label>
                Title:
                <input id="title" />
            </label>
        </div>
        <div>
            <label>
                Director:
                <input id="director" />
            </label>
        </div>
        <div>
            <input type="submit" value="Add Movie" />
        </div>
    </form>
    </fieldset>
</template>

In order for the new form to show up, I need to modify the client\movies.html file to include the movieForm.html template. Notice that I added {{> movieForm }} to the client\movies.html file:

<head>
    <title>My Movie App</title>
</head>

<body>
    <h1>Movies</h1>
    {{> moviesTemplate }}
    {{> movieForm }}
</body>

After I make these modifications, our Movie app will display the form:

The next step is to handle the submit event for the movie form. Below, I’ve modified the client\movies.js file so that it contains a handler for the submit event raised when you submit the form contained in the movieForm.html template:

// Declare client Movies collection
Movies = new Meteor.Collection("movies");

// Bind moviesTemplate to Movies collection
Template.moviesTemplate.movies = function () {
    return Movies.find();
};

// Handle movieForm events
Template.movieForm.events = {
    'submit': function (e, tmpl) {
        // Don't postback
        e.preventDefault();

        // create the new movie
        var newMovie = {
            title: tmpl.find("#title").value,
            director: tmpl.find("#director").value
        };

        // add the movie to the db
        Movies.insert(newMovie);
    }
};

The Template.movieForm.events property contains an event map which maps event names to handlers. In this case, I am mapping the form submit event to an anonymous function which handles the event.

In the event handler, I am first preventing a postback by calling e.preventDefault(). This is a single page app, no postbacks are allowed!

Next, I am grabbing the new movie from the HTML form. I’m taking advantage of the template find() method to retrieve the form field values.

Finally, I am calling Movies.insert() to insert the new movie into the Movies collection. Here, I am explicitly inserting the new movie into the client-side Movies collection. Meteor inserts the new movie into the server-side Movies collection behind the scenes. When Meteor inserts the movie into the server-side collection, the new movie is added to the MongoDB database associated with the Movies app automatically.

If server-side insertion fails for whatever reasons – for example, your internet connection is lost – then Meteor will remove the movie from the client-side Movies collection automatically. In other words, Meteor takes care of keeping the client Movies collection and the server Movies collection in sync.

If you open multiple browsers, and add movies, then you should notice that all of the movies appear on all of the open browser automatically. You don’t need to refresh individual browsers to update the client-side Movies collection. Meteor keeps everything synchronized between the browsers and server for you.

Removing the Insecure Module

To make it easier to develop and debug a new Meteor app, by default, you can modify the database directly from the client. For example, you can delete all of the data in the database by opening up your browser console window and executing multiple Movies.remove() commands.

Obviously, enabling anyone to modify your database from the browser is not a good idea in a production application. Before you make a Meteor app public, you should first run the meteor remove insecure command from a command/terminal window:

Running meteor remove insecure removes the insecure package from the Movie app. Unfortunately, it also breaks our Movie app. We’ll get an “Access denied” error in our browser console whenever we try to insert a new movie. No worries. I’ll fix this issue in the next section.

Creating Meteor Methods

By taking advantage of Meteor Methods, you can create methods which can be invoked on both the client and the server. By taking advantage of Meteor Methods you can:

1. Perform form validation on both the client and the server. For example, even if an evil hacker bypasses your client code, you can still prevent the hacker from submitting an invalid value for a form field by enforcing validation on the server.

2. Simulate database operations on the client but actually perform the operations on the server.

Let me show you how we can modify our Movie app so it uses Meteor Methods to insert a new movie. First, we need to create a new file named common\methods.js which contains the definition of our Meteor Methods:

Meteor.methods({
    addMovie: function (newMovie) {
        // Perform form validation
        if (newMovie.title == "") {
            throw new Meteor.Error(413, "Missing title!");
        }
        if (newMovie.director == "") {
            throw new Meteor.Error(413, "Missing director!");
        }

        // Insert movie (simulate on client, do it on server)
        return Movies.insert(newMovie);
    }

});

The addMovie() method is called from both the client and the server. This method does two things. First, it performs some basic validation. If you don’t enter a title or you don’t enter a director then an error is thrown.

Second, the addMovie() method inserts the new movie into the Movies collection. When called on the client, inserting the new movie into the Movies collection just updates the collection. When called on the server, inserting the new movie into the Movies collection causes the database (MongoDB) to be updated with the new movie.

You must add the common\methods.js file to the common folder so it will get executed on both the client and the server. Our folder structure now looks like this:

We actually call the addMovie() method within our client code in the client\movies.js file. Here’s what the updated file looks like:

// Declare client Movies collection
Movies = new Meteor.Collection("movies");

// Bind moviesTemplate to Movies collection
Template.moviesTemplate.movies = function () {
    return Movies.find();
};

// Handle movieForm events
Template.movieForm.events = {
    'submit': function (e, tmpl) {
        // Don't postback
        e.preventDefault();

        // create the new movie
        var newMovie = {
            title: tmpl.find("#title").value,
            director: tmpl.find("#director").value
        };

        // add the movie to the db
        Meteor.call(
            "addMovie",
            newMovie,
            function (err, result) {
                if (err) {
                    alert("Could not add movie " + err.reason);
                }
            }
       );

    }
};

The addMovie() method is called – on both the client and the server – by calling the Meteor.call() method. This method accepts the following parameters:

· The string name of the method to call.

· The data to pass to the method (You can actually pass multiple params for the data if you like).

· A callback function to invoke after the method completes.

In the JavaScript code above, the addMovie() method is called with the new movie retrieved from the HTML form. The callback checks for an error. If there is an error then the error reason is displayed in an alert (please don’t use alerts for validation errors in a production app because they are ugly!).

Summary

The goal of this blog post was to provide you with a brief walk through of a simple Meteor app. I showed you how you can create a simple Movie Database app which enables you to display a list of movies and create new movies.

I also explained why it is important to remove the Meteor insecure package from a production app. I showed you how to use Meteor Methods to insert data into the database instead of doing it directly from the client.

I’m very impressed with the Meteor framework. The support for Live HTML and Latency Compensation are required features for many real world Single Page Apps but implementing these features by hand is not easy. Meteor makes it easy.