isotope 1.0.1

data.tar.gz.sig

@@ -0,0 +1 @@
+j�v�

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+== 1.0.0 Initial release, 2010-10-28
+
+* Initial release

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygemss
+source :gemcutter
+source "http://gems.github.com"
+
+gem "johnson"

data/Gemfile.lock

@@ -0,0 +1,11 @@
+GEM
+  remote: http://rubygems.org/
+  remote: http://gems.github.com/
+  specs:
+    johnson (1.2.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  johnson

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2010 Elad Ossadon
+
+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.

data/Manifest

@@ -0,0 +1,65 @@
+CHANGELOG.rdoc
+Gemfile
+Gemfile.lock
+LICENSE
+Manifest
+README.md
+Rakefile
+examples/rails3-example/Gemfile
+examples/rails3-example/Gemfile.lock
+examples/rails3-example/README
+examples/rails3-example/Rakefile
+examples/rails3-example/app/controllers/application_controller.rb
+examples/rails3-example/app/controllers/articles_controller.rb
+examples/rails3-example/app/helpers/application_helper.rb
+examples/rails3-example/app/helpers/articles_helper.rb
+examples/rails3-example/app/views/articles/article.html.ejs
+examples/rails3-example/app/views/articles/show_client.html.erb
+examples/rails3-example/app/views/articles/show_server_template_in_view.html.erb
+examples/rails3-example/app/views/layouts/application.html.erb
+examples/rails3-example/config.ru
+examples/rails3-example/config/application.rb
+examples/rails3-example/config/boot.rb
+examples/rails3-example/config/database.yml
+examples/rails3-example/config/environment.rb
+examples/rails3-example/config/environments/development.rb
+examples/rails3-example/config/environments/production.rb
+examples/rails3-example/config/environments/test.rb
+examples/rails3-example/config/initializers/backtrace_silencers.rb
+examples/rails3-example/config/initializers/inflections.rb
+examples/rails3-example/config/initializers/mime_types.rb
+examples/rails3-example/config/initializers/secret_token.rb
+examples/rails3-example/config/initializers/session_store.rb
+examples/rails3-example/config/locales/en.yml
+examples/rails3-example/config/routes.rb
+examples/rails3-example/db/development.sqlite3
+examples/rails3-example/db/seeds.rb
+examples/rails3-example/doc/README_FOR_APP
+examples/rails3-example/public/404.html
+examples/rails3-example/public/422.html
+examples/rails3-example/public/500.html
+examples/rails3-example/public/favicon.ico
+examples/rails3-example/public/images/rails.png
+examples/rails3-example/public/index.html
+examples/rails3-example/public/javascripts/application.js
+examples/rails3-example/public/javascripts/controls.js
+examples/rails3-example/public/javascripts/dragdrop.js
+examples/rails3-example/public/javascripts/effects.js
+examples/rails3-example/public/javascripts/isotope.js
+examples/rails3-example/public/javascripts/prototype.js
+examples/rails3-example/public/javascripts/rails.js
+examples/rails3-example/public/robots.txt
+examples/rails3-example/script/rails
+examples/rails3-example/test/functional/articles_controller_test.rb
+examples/rails3-example/test/performance/browsing_test.rb
+examples/rails3-example/test/test_helper.rb
+examples/rails3-example/test/unit/helpers/article_helper_test.rb
+examples/rails3-example/test/unit/helpers/articles_helper_test.rb
+examples/rails3-example/tmp/pids/server.pid
+examples/sinatra-example/server.rb
+isotope.gemspec
+lib/isotope.js
+lib/isotope.rb
+lib/version.rb
+test/article.ejs
+test/isotope_spec.rb

data/README.md

@@ -0,0 +1,289 @@
+# 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)?
+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
+
+	<%= render :partial => "article", :object => @article %>
+
+in a view, or from a controller and request it by Ajax.
+
+This partial can look like:
+	
+	<h2><%=article.title%></h2>
+	<div class="content">
+	<%=article.content%>
+	</div>
+	<ul class="tags">
+		<%article.tags.each { |tag|%>
+		<li><%=tag.name%></li>
+		<%}%>
+	</ul>
+		
+#### Pros
+
+* Simple, readable and well known ERB for Rails/Sinatra
+* SEO and accessibility - HTML code is downloaded into the source
+
+#### Cons
+
+* Server side only
+* Requires download of the whole HTML code, can cause performance issues
+* Cannot bind easily to a different object on client side. Must re-rendered in the server-side and be downloaded
+
+
+### Approach #2: Client Side EJS Template with JSON Objects
+
+Having an EJS template in the HTML code, with techniques such as John Resig's [JavaScript Micro-Templating](http://ejohn.org/blog/javascript-micro-templating/)
+
+	<script type="text/html" id="article-template">
+	<h2><%=item.title%></h2>
+
+	<div class="content">
+	<%=item.content%>
+	</div>
+
+	<ul class="tags">
+		<%item.tags.forEach(function (tag) {%>
+		<li><%=tag.name%></li>
+		<%});%>
+	</ul>
+	</script>
+
+Ask the server for a JSON article and evaluate the template with this object into a string, and place it inside a container, using a techniques 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
+
+
+### Approach #3: Regular ERB Partial With Marked Spots for Data Place Holders
+
+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).
+
+Template file should look like:
+
+	<h2 class="data-title"><%=article.title%></h2>
+	<div class="content data-content">
+	<%=article.content%>
+	</div>
+	<ul class="tags data-tags">
+		<%article.tags.each { |tag|%>
+		<li><%=tag.name%></li>
+		<%}%>
+	</ul>
+
+And then, from a JS function, doing something like:
+
+	// article is an object probably from a JSON request
+	container.querySelector('.data-title').textContent=article.title;
+	container.querySelector('.data-content').textContent=article.content;
+	var tags=container.querySelector('.data-tags');
+	tags.innerHTML="";
+	article.tags.forEach(function (tag) {
+		tags.appendChild(document.createElement("li")).textContent=tag.name;
+	});
+
+#### 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!).
+
+Using [**jbarnette**](http://github.com/jbarnette/)'s AWESOME [**Johnson**](http://github.com/jbarnette/johnson/) gem, Ruby and JavaScript can interact together!
+
+That means, that ruby code can handle EJS templates and JSON objects. A **great and very inspiring article** is [Write your Rails view in… JavaScript?](http://tenderlovemaking.com/2008/05/06/write-your-rails-view-in-javascript/) by [Aaron Patterson](http://tenderlovemaking.com/).
+
+In this approach, only **one template is written and maintained in an EJS format**, for both client side and server side.
+
+## Usage
+
+Isotope gives the ability to have a single template file, and easily switch between the approaches:
+
+	# article.ejs
+	
+	<h2><%=item.title%></h2>
+
+	<div class="content">
+	<%=item.content%>
+	</div>
+
+	<ul class="tags">
+		<%item.tags.forEach(function (tag) {%>
+		<li><%=tag.name%></li>
+		<%});%>
+	</ul>
+
+### On the Client Side
+
+Outputting from the server side (controller or view)
+	
+	<%= Isotope.render_template("full/path/to/article.ejs", :id => "article-template") %>
+	
+*Notice: a full path should be sent as the first variable, so either use `File.join(File.dirname(__FILE__), '../relative/path/to/article.ejs')` or with `Rails.root.join('app/views/articles/article.ejs')`*
+
+The above code will output:
+
+	<script type="text/x-isotope" id="article-template">
+	<h2><%=item.title%></h2>
+
+	<div class="content">
+	<%=item.content%>
+	</div>
+
+	<ul class="tags">
+		<%item.tags.forEach(function (tag) {%>
+		<li><%=tag.name%></li>
+		<%});%>
+	</ul>
+	</script>
+
+which is easy to evaluate with any JS object using the [mentioned technique](http://ejohn.org/blog/javascript-micro-templating/).
+
+### On the Server Side (The Holy Grail)
+
+Using [Johnson](http://github.com/jbarnette/johnson/), the famous [micro-templating technique](http://ejohn.org/blog/javascript-micro-templating/) and JSONed Ruby objects, this library provides the following functionality:
+
+	<%= Isotope.render_partial("full/path/to/article.js", :locals => { :item => @article }) %>
+
+*Notice: a full path should be sent as the first variable, so either use `File.join(File.dirname(__FILE__), '../relative/path/to/article.ejs')` or with `Rails.root.join('app/views/articles/article.ejs')`*
+
+This code reads the source of the EJS file, uses Johnson and John Resig's technique and serves a **string** as an output.
+
+
+### Installation:
+
+	gem install isotope
+
+Or
+	# Rails 3.x
+	ruby script/rails plugin install git@github.com:elado/isotope.git
+	
+	# Rails 2.3.x
+	ruby script/plugin install git@github.com:elado/isotope.git
+
+
+#### Rails
+
+##### Rails 3.x
+
+Add to your Gemfile
+
+	gem 'json'
+	gem 'johnson'
+	gem 'isotope'
+
+and run `bundle install`
+
+##### Rails 2.3.x
+
+Add to config/environment.rb
+
+	config.gem 'json'
+	config.gem 'johnson'
+	config.gem 'isotope'
+
+and run `rake gems:install`
+
+##### Server Side Example:
+
+	# ArticlesController
+	
+	def show
+		@article = {
+			:title => "Hello!",
+			:content => "World!",
+			:tags => [
+				{:name => "tag 1"},
+				{:name => "tag 2"},
+				{:name => "tag 3"},
+				{:name => "tag 4"}
+			]
+		} # Or an ActiveRecord fetch
+		
+		render :text => Isotope.render_partial(Rails.root.join('app/views/articles/article.ejs'), :locals => { :item => @article })
+	end
+
+Or, with a view:
+
+	# ArticlesController
+
+	def show
+		@article = {
+			:title => "Hello!",
+			:content => "World!",
+			:tags => [
+				{:name => "tag 1"},
+				{:name => "tag 2"},
+				{:name => "tag 3"},
+				{:name => "tag 4"}
+			]
+		} # Or an ActiveRecord fetch
+	end
+	
+	# views/articles/show.html.erb
+	
+	<%= Isotope.render_partial(Rails.root.join('app/views/articles/article.ejs'), :locals => { :item => @article }) %>
+	
+##### Client Side Example:
+
+	# views/articles/show.html.erb
+	
+	<%= Isotope.render_template(Rails.root.join('app/views/articles/article.ejs'), :id => "article") %>
+	
+
+#### Sinatra
+
+Actually the same usage, more or less.
+
+
+---
+
+Would love to hear your comments!
+
+Elad Ossadon
+
+* [http://devign.me](http://devign.me)
+* [http://elad.ossadon.com](http://elad.ossadon.com)
+* [elad@ossadon.com](mailto:elad@ossadon.com)

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('isotope', '1.0.1') do |p|
+  p.summary    = "Ruby Hybrid (Server and Client sides) templates"
+  p.description = "Isotope provides an easy way to use a signle EJS template on both server and client side"
+  p.url            = "http://github.com/elado/isotope"
+  p.author         = "Elad Ossadon"
+  p.email          = "elad@ossadon.com"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+end

data/examples/rails3-example/Gemfile

@@ -0,0 +1,34 @@
+source 'http://rubygems.org'
+
+gem 'rails', '>=3.0.0'
+
+# gem 'isotope'
+gem 'json'
+gem 'johnson'
+
+# Bundle edge Rails instead:
+# gem 'rails', :git => 'git://github.com/rails/rails.git'
+
+gem 'sqlite3-ruby', :require => 'sqlite3'
+
+# Use unicorn as the web server
+# gem 'unicorn'
+
+# Deploy with Capistrano
+# gem 'capistrano'
+
+# To use debugger
+# gem 'ruby-debug'
+
+# Bundle the extra gems:
+# gem 'bj'
+# gem 'nokogiri'
+# gem 'sqlite3-ruby', :require => 'sqlite3'
+# gem 'aws-s3', :require => 'aws/s3'
+
+# Bundle gems for the local environment. Make sure to
+# put test-only gems in this group so their generators
+# and rake tasks are available in development mode:
+# group :development, :test do
+#   gem 'webrat'
+# end