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.
