Eco: Embedded CoffeeScript templates
Eco lets you embed CoffeeScript logic in your markup. It's like EJS and ERB, but with CoffeeScript inside the <% ... %>
. Use it from Node.js to render your application's views on the server side, or compile your templates to JavaScript with the eco
command-line utility and use them to dynamically render views in the browser.
Here's how an Eco template looks:
<% if @projects.length: %>
<% for project in @projects: %>
<a href="<%= project.url %>"><%= project.name %></a>
<p><%= project.description %></p>
<% end %>
<% else: %>
No projects
<% end %>
Usage
Use eco.render()
to render your templates. The first argument is the template source as a string. The second argument is the context object which contains your view state and any helper methods you want to call.
eco = require "eco"
fs = require "fs"
template = fs.readFileSync __dirname + "/views/projects.html.eco", "utf-8"
console.log eco.render template, projects: [
{ name: "Mobile app", url: "/projects/1", description: "Iteration 1" },
{ name: "Home page redesign", url: "/projects/2" }
]
Eco is fully synchronous. If your template needs to access data from asynchronous operations, perform those first before calling render
.
Language reference
Eco's syntax is simple:
<% expression %>
: Evaluate a CoffeeScript expression without printing its return value.<%= expression %>
: Evaluate a CoffeeScript expression, escape its return value, and print it.<%- expression %>
: Evaluate a CoffeeScript expression and print its return value without escaping it.<%= @property %>
: Print the escaped value of the propertyproperty
from the context object passed torender
.<%= @helper() %>
: Call the helper methodhelper
from the context object passed torender
, then print its escaped return value.<% @helper -> %>...<% end %>
: Call the helper methodhelper
with a function as its first argument. When invoked, the function will capture and return the content...
inside the tag.<%%
and%%>
will result in a literal<%
and%>
in the rendered template, respectively.
A note about whitespace
CoffeeScript is whitespace-sensitive, but your templates aren't. Therefore, Eco code tags that begin an indented CoffeeScript block must be suffixed with a colon. To indicate the end of an indented block, use the special tag <% end %>
. For example:
<% if @project.isOnHold(): %>
On Hold
<% end %>
You don't need to write the if
and end
tags on separate lines:
<% if @project.isOnHold(): %> On Hold <% end %>
And you can use the single-line postfix form of if
as you'd expect:
<%= "On Hold" if @project.isOnHold() %>
Certain forms in CoffeeScript, such as else
, must be unindented first. Eco handles that for you automatically:
<% if @project.isOnHold(): %>
On Hold
<% else if @project.isArchived(): %>
Archived
<% end %>
The context object
The context object you pass to eco.render()
becomes the value of this
inside your template. You can use CoffeeScript's @
sigil to easily access properties and call helper methods on the context object.
eco.render "<p><%= @description %></p>",
description: "HTML 5 mobile app"
Helpers
Helper methods on your context object can access other properties on the context object in the same way they're accessed in the template: through this
, or with the @
sigil.
translations = require "translations"
eco.render "<span><%= @translate 'common.welcomeText' %></span>",
language: "en"
translate: (key) ->
translations[@language][key]
Escaping and unescaping
When you print an expression in a template with <%= ... %>
, its value is HTML-escaped. For example,
eco.render "<%= @description %>",
description: "<strong>HTML 5</strong> mobile app"
would render:
<strong>HTML 5</strong> mobile app
You can use the <%- ... %>
tag to print the value of an expression without escaping it. So this code:
eco.render "<%- @description %>",
description: "<strong>HTML 5</strong> mobile app"
would produce:
<strong>HTML 5</strong> mobile app
It is sometimes useful to generate markup in helper methods. The special safe
method on the context object tells Eco that the string can be printed in <%= ... %>
tags without being escaped. You can use this in conjunction with the context object's escape
method to selectively sanitize parts of the string. For example,
eco.render "<%= @linkTo @project %>",
project: { id: 4, name: "Crate & Barrel" }
linkTo: (project) ->
url = "/projects/#{project.id}"
name = @escape project.name
@safe "<a href='#{url}'>#{name}</a>"
would render:
<a href='/projects/4'>Crate & Barrel</a>
Custom escape helpers
By default, Eco's escape
method takes a string and returns an HTML-escaped string. You can override this behavior to escape for formats other than HTML, or to bypass escaping entirely. For example,
eco.render "From: <%= @address %>",
address: "Sam Stephenson <[email protected]>"
escape: (string) -> string
would return:
From: Sam Stephenson <[email protected]>
Blocks and capturing
You can capture blocks of a template by wrapping them in a function definition. For example, rendering this template:
<% div = (contents) => %>
<div><%- contents %></div>
<% end %>
<%= div "Hello" %>
would produce:
<div>Hello</div>
Captured blocks can be passed to helper methods too. In this example, the capture body is passed to the formFor
helper as its last argument. Then the formFor
helper calls this argument to produce a value.
template = """
<%= @formFor @project, (form) => %>
<label>Name:</label>
<%= form.textField "name" %>
<% end %>
"""
eco.render template,
project: { id: 1, name: "Mobile app" }
formFor: (project, yield_to) ->
form =
textField: (attribute) =>
name = @escape attribute
value = @escape @project[attribute]
@safe "<input type='text' name='#{name}' value='#{value}'>"
url = "/projects/#{@project.id}"
body = yield_to form
@safe "<form action='#{url}' method='post'>#{body}</form>"
Note: In general, you should use CoffeeScript's fat arrow (=>
) to define capturing functions, so that you have access to the context object inside the captured block. Treat the plain arrow (->
) as an optimization, for when you are certain the capture body will not need to reference properties or helper methods on the context object.
Contributing
You can check out the Eco source code from GitHub:
$ git clone http://github.com/sstephenson/eco.git
To run Eco's test suite, install nodeunit and run cake test
.
Report bugs on the GitHub issue tracker.
License (MIT)
Copyright (c) 2010 Sam Stephenson [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Special thanks
- Jeremy Ashkenas [email protected]
- Josh Peek [email protected]