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.
