<%=

EJS

<% Embedded JavaScript %>

Getting Started with EJS

Are you ever faced with a mess of HTML string concatenations like this?

var html = "<h1>"+data.title+"</h1>"
html += "<ul>"
for(var i=0; i<data.supplies.length; i++) {
    html += "<li><a href='supplies/"+data.supplies[i]+"'>"
    html += data.supplies[i]+"</a></li>"
}
html += "</ul>"

If you're a web developer, the answer is probably yes. Beyond being ugly, the structure of your HTML is lost in the JavaScript. Adding to this layout would be difficult. How can we clean it up?

In this tutorial, we'll show you how to improve the above code that produces a list of supply links. We'll use Embedded JavaScript (EJS) to return this code to a straightforward, maintainable HTML structure.

EJS is a JavaScript templating library. It is commonly used for building html strings from JSON data. Typically, EJS works like this:

This tutorial walks you through:

Include EJS

Before we put on the rubber gloves and get to the heavy scrubbing, lets get set up a bit.

Your page needs to include EJS so your JavaScript can use it. Start by downloading ejs_production.js from Google Code or the subversion repository.

Next add EJS to your HTML like this:

<script type="text/javascript" src="ejs_production.js"></script>

Create a Template

The first step towards cleaner code is separating your presentation markup (HTML) from your application logic (JavaScript). We'll do this by separating our presentation markup into a separate file called a template. Create a file called cleaning.ejs and insert the following code:

<h1><%= title %></h1>
<ul>
    <% for(var i=0; i<supplies.length; i++) { %>
        <li>
            <a href='supplies/<%= supplies[i] %>'>
                <%= supplies[i] %>
            </a>
        </li>
    <% } %>
</ul>

You'll notice everything inside <% %> tags is executed and everything inside <%= %> tags inserts itself into the returned HTML string.

We need to add JavaScript to control the loading and rendering of the template. We'll replace the original string concatenation code with the following:

// load the template file, then render it with data
var html = new EJS({url: 'cleaning.ejs'}).render(data);

Doesn't that feel better? The template code restores HTML to its intended structure and the JavaScript code is short and unambiguous. The dust is clear, now its time to mop.

View Helpers

EJS is packaged with view helpers. View helpers are shortcuts to commonly used display code, like links and forms. Similar to those found in the Ruby on Rails framework, they keep view code as short, simple, and to the point as possible.

The links in our template are being constructed using something resembling string concatenation.

<li>
    <a href='supplies/<%= supplies[i] %>'>
        <%= supplies[i] %>
    </a>
</li>

This code is still quite messy. There are enough nested tags to make you lightheaded. Let's tidy that up using a view helper.

<li>
    <%= link_to(supplies[i], 'supplies/'+supplies[i]) %>
</li>

This code is much cleaner and more straightforward. Remember what building the links used to look like?

html += "<li><a href='supplies/"+data.supplies[i]+"'>"
html += data.supplies[i]+"</a></li>"

Compared to the original JavaScript, someone with little knowledge of your code would have a much easier time understanding the EJS template snippet.

Now you can relax and enjoy the tingly clean sensation.

Error Handling

A good maid always admits her mistakes. If you have an error in an EJS template, EJS will point out the exact line number the error occurred on. All you have to do is include ejs_jslint.js, which you can download at Google Code. If you're using Firebug, the Firefox JavaScript debugger plugin, the error will appear right in your console.

Example broken template code:

<ul>
	<% foor(var i=0; i<supplies.length; i++) { %>
	<li>
	    <%= link_to(supplies[i], 'supplies/'+supplies[i]) %>
	</li>
	<% } %>
</ul>

Firebug console:

When is it a good time to clean?

Some would say cleaning should be a daily habit, but we feel EJS is a perfect assistant if you find yourself in one of these binds:

  1. Building HTML strings with JavaScript.
  2. As we discussed in this tutorial, the downside of HTML string concatenation in JavaScript is maintainability. When you’re adding together HTML in JavaScript strings, its difficult to see the big picture of what you’re creating - a representation of the layout for your page. Using templates makes layout easier because you can see the HTML and preserve linebreaks and spacing.

  3. AJAX web development with web services.
  4. EJS accepts JSON coming in asynchronously from a web service, passes this data into a template of your choosing, and inserts the resulting HTML into the page for you. All you have to do is write one line of code:

    new EJS({url: 'comments.ejs'}).update('element_id', '/comments.json')

    Pretty sweet, eh?

  5. Application skinning.
  6. If you want to give users the power to customize their own look and feel, EJS provides the perfect mechanism. EJS templates execute in the browser only, so there is no security risk to your server. Allowing users to upload EJS templates and associated stylesheets is the easiest and fastest way to skin your site.

More tips

Wax on, wax off. You've learned some good techniques, but cleaning up your messy HTML isn't simple enough to teach in one tutorial. For more info, check out these resources.