README.md

Isotope - Ruby Hybrid Template Engine for Client Side and Server Side

The problem:

In Ajax-based sites, there's a constant dilemma: How to get objects rendered in templates? In server side (and output full HTML)? Client side (and mess with JSON objects and HTML strings/DOM generation)?
What should be the role division between server and client?

Common Approaches, Pros & Cons:

A few approaches to output a rendered template evaluated with an object are:

Approach #1: Regular ERB Partial

Evaluate a simple ERB partial with a local object, and server it as a string to the client, simply by

Query the server for a JSON article and evaluate the template with this object into a string, and place it inside a container, using a technique as mentioned:

var results = document.getElementById("results"); // some container on the page
results.innerHTML = tmpl("article-template", article); // article is an object, probably a result of an AJAX JSON request

Pros

Fast - requires the server to send only the JSON object and the HTML is downloaded only once as a template

Cons

SEO and accessibility - HTML code isn't in the source of the page but being rendered after load

This approach tries to combine server side and client side but requires a lot of work. It contains a regular ERB template and place holder markers like class names on elements.
The template can be first evaluated on the server with a Ruby object and on the client side it can be evaluated with a different JS object (probably from a JSON request).

Pros

One template for both client and server (not really, see Cons)

SEO and accessibility - HTML code is downloaded into the source

Cons

On the client side - Must mimic the Ruby functionality with JS when it comes to loops, conditions etc. However, text values are pretty easy to embed. This code should probably written manually for everything that is not a simple textual content.

Must maintain data place holder markers

So...

In these three approaches, the developer needs to choose according to the task and the project requirements, or worse, maintain two templates, ERB and EJS.

Each approach is written in a totally different way, and switching between the approaches means a lot of work.

Introducing: Isotope - Ruby Hybrid Template Engine for Client Side and Server Side

So why not combining all the pros of the approaches together?

The biggest constraints to be considered are:

Client side doesn't understand Ruby

Ruby can't be translated fully into JavaScript

And the most important one: Template should be maintained in one single file for both client and server uses

Isotope is from greek - "Equal Place". An equal place of editing a template for both client and server (Thanks @yuvalraz for the name!).

This code reads the source of the EJS file, uses Johnson and John Resig's technique and serves a string as an output.

Configuration

External JS files can be included in order to have special functionality in the EJS templates, on both client and server.
To include files, create a config/isotope.yml file and fill this array, relatively to the app root:

include_scripts:
- /public/javascripts/isotope_functions.js

And in order to have it available on client side, put this line before the