cells 2.3.0

data/CHANGES

@@ -0,0 +1,30 @@
+- 2.3
+  * Cell::Base#new(controller, opts={})
+    We got rid of the second argument cell_name, since it was completely useless.
+  * when a state view couldn't be found there's no longer a warning message, but an exception.
+  * moved Cell::Base to lib/cell/base.rb
+  * moved Rails extension code to lib/rails_extensions.rb
+  * removed all the boot code since we don't need it anymore
+  
+
+- trunk
+  * Remove dependency on Engines
+  * Improved support for helpers
+
+- cells-1.0
+  * view rendering rewritten, we now use a separate ActionView::Base instance 
+    that fixes bug #1
+  * introduced view inheritance, so derived cells inherit view files from their
+    superclass
+  * introduced automatic view file finding, Cell::Base#path is no longer needed
+  * added support for helpers in cell views
+  * removed Cell::Registry in favor or a new cells autoloading mechanism
+  
+- zells-0.1
+  * partly fixed bug #1 where cell instance variables could not be accessed 
+    when calling #render_cell under special circumstances
+  * added lots of tests
+  * tests use #assert_select now
+
+- zells-0.1-rc1
+  * first release into an unsuspecting world

data/README

@@ -0,0 +1,150 @@
+= Overview
+
+Cells are like controllers in Rails - they have methods and corresponding views.
+However, their big advantage to controllers is their <em>modularity</em>: you can have
+as many cells on a page as you want. That's as if you had multiple controllers in one 
+page, where each "controller" renders only a certain part of the page.
+As if this wasn't enough, cells are superfast and lightweight.
+
+They perfectly work together with AJAX/JavaScript, but also run fine without it,
+Michael.
+
+== Give me code!
+
+To quickly create the necessary files for an example cell run the generator:
+  
+  script/generate cell Article newest top_article
+
+
+The generated cell class located in <tt>app/cells/article_cell.rb</tt> could look like
+this, after some editing:
+
+  class ArticleCell < Cell::Base
+    helper :my_formatting_and_escaping_helper   # you can use helpers in cell views!
+    
+    def newest
+      @articles = Article.get_newest
+      render   # will render the view named newest.html.[erb|haml|...]".
+    end
+    
+    def top_article
+      @article = Article.top_article
+      render  :view   => :top_article_v2, # renders top_article_v2.html.[erb|haml|...]
+              :layout => :box             # and put it in the layout "box.html".
+    end
+  end
+
+The corresponding views are in <tt>app/cells/article/newest.html.erb</tt>:
+
+  <h2>Hot stuff!</h2>
+  <ul>
+  <% @articles.each do |article| %>
+    <li><%= article.title %></li>
+  <% end %>
+  </ul>
+
+The other view would be in <tt>app/cells/article/top_article_v2.html.haml</tt>:
+
+  %h2
+    = @article.title
+    = format_and_escape(@article.text)
+
+You already know that from controllers, don't you? Speaking of controllers, here's
+how you could plug the cells into the page. In <tt>app/controllers/blog_controller.rb</tt>
+there could be an action
+  
+  class BlogController < ApplicationController
+    def top_page
+      ...
+    end
+  end
+
+where the rendered action view could be <tt>app/views/blog/top_page.html.erb</tt>:
+  
+  <%= yield %>
+  
+  <div><%= render_cell(:article, :newest) %></div>
+  <div><%= render_cell(:article, :top_article) %></div>
+    
+The "top page" would consist of the controller action's content, and two additional 
+independent boxes with interesting content. These two boxes are <em>cells</em> and could
+be used on another page, too.
+
+= Caching
+
+To improve performance rendered state views can be cached using Rails' caching mechanism.
+If this it configured (e.g. using our fast friend memcached) all you have to do is to 
+tell Cells which state you want to cache. You can further attach a proc for deciding
+versions or to instruct re-rendering.
+
+  cache :my_cached_state, Proc.new{|cell| Version.for(User.find(1)}
+
+This would result in re-rendering the state <tt>:my_cached_state</tt> only if the
+version of the user instance changes. 
+
+= Compatibility with other rails plugins
+
+Cells uses the rails rendering code and thus stays completely compatible with (most?) plugins.
+
+=== I18N
+
+All of Rails' new i18n features work with Cells. For example
+
+  t("Translate me, I'm a lonesome string in a cell state view!")
+  
+from the i18n helper can also be used in cell views. 
+
+=== Haml
+
+Alternative templating engines will work seamlessly with Cells, too. Usem the markup language 
+of your choice (.erb, .haml, ...) to write your cell views.
+
+=== Engines
+
+You can even put cells in plugins and thus maximize the modularity of your code.
+As soon as the plugin has an app/cells/ directory your cells will be added automatically
+and can be used everywhere in your application.
+
+= Installation
+
+To install, simply cd to your rails app directory and run
+
+  script/plugin install git://github.com/apotonick/cells.git
+  
+This release is tested and runs with Rails 2.3.
+
+
+= Documentation
+
+Reference documentation is found in the documentation of the Cell::Base class.
+
+See http://cells.rubyforge.org for documentation targeted at cells
+newbies, including an overview of what you can do with cells and a
+tutorial.
+
+= LICENSE
+
+Copyright (c) 2007-2009, Nick Sutterer
+
+Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers
+
+The MIT License
+
+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/README.rdoc

@@ -0,0 +1,150 @@
+= Overview
+
+Cells are like controllers in Rails - they have methods and corresponding views.
+However, their big advantage to controllers is their <em>modularity</em>: you can have
+as many cells on a page as you want. That's as if you had multiple controllers in one 
+page, where each "controller" renders only a certain part of the page.
+As if this wasn't enough, cells are superfast and lightweight.
+
+They perfectly work together with AJAX/JavaScript, but also run fine without it,
+Michael.
+
+== Give me code!
+
+To quickly create the necessary files for an example cell run the generator:
+  
+  script/generate cell Article newest top_article
+
+
+The generated cell class located in <tt>app/cells/article_cell.rb</tt> could look like
+this, after some editing:
+
+  class ArticleCell < Cell::Base
+    helper :my_formatting_and_escaping_helper   # you can use helpers in cell views!
+    
+    def newest
+      @articles = Article.get_newest
+      render   # will render the view named newest.html.[erb|haml|...]".
+    end
+    
+    def top_article
+      @article = Article.top_article
+      render  :view   => :top_article_v2, # renders top_article_v2.html.[erb|haml|...]
+              :layout => :box             # and put it in the layout "box.html".
+    end
+  end
+
+The corresponding views are in <tt>app/cells/article/newest.html.erb</tt>:
+
+  <h2>Hot stuff!</h2>
+  <ul>
+  <% @articles.each do |article| %>
+    <li><%= article.title %></li>
+  <% end %>
+  </ul>
+
+The other view would be in <tt>app/cells/article/top_article_v2.html.haml</tt>:
+
+  %h2
+    = @article.title
+    = format_and_escape(@article.text)
+
+You already know that from controllers, don't you? Speaking of controllers, here's
+how you could plug the cells into the page. In <tt>app/controllers/blog_controller.rb</tt>
+there could be an action
+  
+  class BlogController < ApplicationController
+    def top_page
+      ...
+    end
+  end
+
+where the rendered action view could be <tt>app/views/blog/top_page.html.erb</tt>:
+  
+  <%= yield %>
+  
+  <div><%= render_cell(:article, :newest) %></div>
+  <div><%= render_cell(:article, :top_article) %></div>
+    
+The "top page" would consist of the controller action's content, and two additional 
+independent boxes with interesting content. These two boxes are <em>cells</em> and could
+be used on another page, too.
+
+= Caching
+
+To improve performance rendered state views can be cached using Rails' caching mechanism.
+If this it configured (e.g. using our fast friend memcached) all you have to do is to 
+tell Cells which state you want to cache. You can further attach a proc for deciding
+versions or to instruct re-rendering.
+
+  cache :my_cached_state, Proc.new{|cell| Version.for(User.find(1)}
+
+This would result in re-rendering the state <tt>:my_cached_state</tt> only if the
+version of the user instance changes. 
+
+= Compatibility with other rails plugins
+
+Cells uses the rails rendering code and thus stays completely compatible with (most?) plugins.
+
+=== I18N
+
+All of Rails' new i18n features work with Cells. For example
+
+  t("Translate me, I'm a lonesome string in a cell state view!")
+  
+from the i18n helper can also be used in cell views. 
+
+=== Haml
+
+Alternative templating engines will work seamlessly with Cells, too. Usem the markup language 
+of your choice (.erb, .haml, ...) to write your cell views.
+
+=== Engines
+
+You can even put cells in plugins and thus maximize the modularity of your code.
+As soon as the plugin has an app/cells/ directory your cells will be added automatically
+and can be used everywhere in your application.
+
+= Installation
+
+To install, simply cd to your rails app directory and run
+
+  script/plugin install git://github.com/apotonick/cells.git
+  
+This release is tested and runs with Rails 2.3.
+
+
+= Documentation
+
+Reference documentation is found in the documentation of the Cell::Base class.
+
+See http://cells.rubyforge.org for documentation targeted at cells
+newbies, including an overview of what you can do with cells and a
+tutorial.
+
+= LICENSE
+
+Copyright (c) 2007-2009, Nick Sutterer
+
+Copyright (c) 2007-2008, Solide ICT by Peter Bex and Bob Leers
+
+The MIT License
+
+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/Rakefile

@@ -0,0 +1,77 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+NAME = "cells"
+SUMMARY = %{Cells are lightweight controllers for Rails and can be rendered in controllers and views, providing an elegant and fast way for encapsulation and component-orientation.}
+HOMEPAGE = "http://cells.rubyforge.org"
+AUTHORS = ["Nick Sutterer"]
+EMAIL = "apotonick@gmail.com"
+SUPPORT_FILES = %w[README CHANGES]
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the cells plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the cells plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Cells Documentation'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('init.rb')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# rdoc -m "README.rdoc" init.rb lib/ generators/ README.rdoc
+
+# Gem managment tasks.
+#
+# == Bump gem version (any):
+#
+#   rake version:bump:major
+#   rake version:bump:minor
+#   rake version:bump:patch
+#
+# == Generate gemspec, build & install locally:
+#
+#   rake gemspec
+#   rake build
+#   sudo rake install
+#
+# == Git tag & push to origin/master
+#
+#   rake release
+#
+# == Release to Gemcutter.org:
+#
+#   rake gemcutter:release
+#
+begin
+  gem 'jeweler'
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name        = NAME
+    gemspec.summary     = SUMMARY
+    gemspec.description = SUMMARY
+    gemspec.homepage    = HOMEPAGE
+    gemspec.authors     = AUTHORS
+    gemspec.email       = EMAIL
+    
+    gemspec.require_paths = %w{lib}
+    gemspec.files = FileList["[A-Z]*", File.join(*%w[{generators,lib} ** *]).to_s, "init.rb"]
+    gemspec.extra_rdoc_files = SUPPORT_FILES
+    
+    # gemspec.add_dependency 'activesupport', '>= 2.3.0' # Dependencies and minimum versions?
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler - or one of its dependencies - is not available. " <<
+        "Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end

data/VERSION

@@ -0,0 +1 @@
+2.3.0

data/generators/cell/USAGE

@@ -0,0 +1,26 @@
+Description:
+  Stubs out a new cell and its views. Pass the cell name, either
+  CamelCased or under_scored, and a list of views as arguments.
+  
+  This generates a cell class in app/cells and view templates in
+  app/cells/cell_name.
+  
+Examples:
+  
+  ./script/generate cell Announcements index
+  
+  This will create an Announcements cell:
+    Cell:
+      app/cells/announcements_cell.rb
+    Views:
+      app/cells/announcements/index.html.erb
+      
+      
+  ./script/generate cell Articles popular recent --haml
+  
+  This will create an Articles cell:
+    Cell:
+      app/cells/articles_cell.rb
+    Views:
+      app/cells/articles/popular.html.haml
+      app/cells/articles/recent.html.haml

data/generators/cell/cell_generator.rb

@@ -0,0 +1,48 @@
+require 'rails_generator/generators/components/controller/controller_generator'
+
+class CellGenerator < ControllerGenerator
+
+  attr_reader :template_type
+
+  def initialize(runtime_args, runtime_options = {})
+    super
+    @template_type = options[:haml] ? :haml : :erb
+  end
+
+  def manifest
+    record do |m|
+      # Check for class naming collisions.
+      m.class_collisions class_path, "#{class_name}Cell"
+
+      # Directories
+      m.directory File.join('app/cells', class_path)
+      m.directory File.join('app/cells', class_path, file_name)
+
+      # Cell
+      m.template 'cell.rb', File.join('app/cells', class_path, "#{file_name}_cell.rb")
+
+      # View template for each action.
+      actions.each do |action|
+        path = File.join('app/cells', class_path, file_name, "#{action}.html.#{template_type}")
+        m.template "view.html.#{template_type}", path,
+          :assigns => { :action => action, :path => path }
+      end
+    end
+  end
+
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+
+    # Allow option to generate HAML views instead of ERB.
+    opt.on('--haml',
+    "Generate HAML output instead of the default ERB.") do |v|
+      options[:haml] = v
+    end
+  end
+
+  def banner
+    "Usage: #{$0} cell NAME a_view another_view ... [--haml]"
+  end
+
+end