erector 0.1.25 → 0.2.42

data/README.txt

@@ -6,20 +6,33 @@
 
 == DESCRIPTION
 
-Erector is a Builder-based view framework, inspired by Markaby but overcoming some of its flaws. In Erector all views are
-objects, not template files, which allows the full power of OO (inheritance, modular decomposition, encapsulation) in views.
+Erector is a Builder-like view framework, inspired by Markaby but overcoming
+some of its flaws. In Erector all views are objects, not template files,
+which allows the full power of object-oriented programming (inheritance,
+modular decomposition, encapsulation) in views.
 
 == FEATURES/PROBLEMS:
 
-This is a *prerelease work in progress* and this gem is **NOT READY FOR USE** by anyone who's not on the Erector team yet. We'll be rolling out a
-version 0.2.0 soon which should include howto documentation and such.
+While Erector is in use on several projects, it is still at a relatively
+early stage.  In particular, not all features are documented (although
+the most important ones are).  
 
 == SYNOPSIS
 
-TODO (HOWTO, sample code, etc.)
+    require 'erector'
+
+    class Hello < Erector::Widget
+      def render
+        div do
+          text "Hello!"
+        end
+      end
+    end
 
 == REQUIREMENTS
 
+The gem depends on hoe and rake, although this is just for building
+erector (those who just use erector won't need these).
 
 == INSTALL
 
@@ -27,9 +40,14 @@ To install as a gem:
 
 * sudo gem install erector
 
-To install as a plugin:
+Then add "require 'erector'" to any files which need erector.
+
+To install as a Rails plugin:
 
-* TODO
+* Copy the erector source to vendor/plugins/erector in your Rails directory.
+
+When installing this way, erector is automatically available to your Rails code
+(no require directive is needed).
 
 == LICENSE:
 
@@ -56,19 +74,29 @@ 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.
 
-== USER DOCUMENTATION
+== MOTIVATION
 
-TODO (more on how you get started, and call it from rails)
+Why use Erector? This section will soon become a real essay or blog post,
+but briefly:
 
-The basic way to construct some HTML/XML with erector is to pass a
-block to Erector::Widget.new.  For example:
+* Markaby-style DOM Domain language
+* Your views are real classes, written in a real language, allowing
+  * Functional decomposition
+  * Inheritance
+  * Composition, not partials
+  * Well-defined semantics for variables, loops, blocks
+  * Dependency injection via constructor params
+* As little magic as possible (e.g. no automagic copying of "assigns" variable from your controller)
+* yield works again (Markaby broke it)
+* Very testable
+* form_for ERB code is craaaaazy (not to mention the quagmire of options vs. htmloptions)
+* Output is streamed, improving performance over string copy
 
-  html = Erector::Widget.new do
-    p "Hello, world!"
-  end
-  html.to_s          #=> <p>Hello, world!</p>
 
-Or, subclass Erector::Widget and implement a render method:
+== USER DOCUMENTATION
+
+The basic way to construct some HTML/XML with erector is to 
+subclass Erector::Widget and implement a render method:
 
   class Hello < Erector::Widget
     def render
@@ -108,6 +136,39 @@ Here are the basics:
 
 TODO: document more obscure features like capture, Table, :class => ['one', 'two']
 
+=== Using erector from Ruby on Rails
+
+Your views are just ruby classes.  Your controller instantiates the
+relevant view and calls render.  For example:
+
+app/controllers/welcome_controller.rb:
+
+  class WelcomeController < ApplicationController
+
+    def index
+      render :template => 'welcome/show'
+    end
+
+  end
+
+app/views/welcome/show.rb:
+
+  class Views::Welcome::Show < Erector::Widget
+
+    def render
+      html do
+        head do
+          title "Welcome page"
+        end
+      
+        body do
+          p "Hello, world"
+        end
+      end
+    end
+  
+  end
+
 === Layout Inheritance
 
 Erector replaces the typical Rails layout mechanism with a more natural construct, the use of inheritance. Want a common
@@ -140,6 +201,16 @@ Here the abstract layout widget is used in a concrete fashion by the template-ba
 would be implemented by subclassing widgets, but the layout template sets it directly and then calls to_s on the layout widget.
 This allows the same layout to be shared in a backward compatible way.
 
+=== Other ways to call erector
+
+Instead of subclassing Erector::Widget and implementing a render
+method, you can pass a block to Erector::Widget.new.  For example:
+
+  html = Erector::Widget.new do
+    p "Hello, world!"
+  end
+  html.to_s          #=> <p>Hello, world!</p>
+
 == DEVELOPER NOTES
 
 * Check out project from rubyforge: 
@@ -163,12 +234,13 @@ This allows the same layout to be shared in a backward compatible way.
 
 * Versions are of the form major.minor.tiny
 * Tiny revisions fix bugs or documentation
+* Tiny revisions are roughly equal to the svn revision number when they were made
 * Minor revisions add API calls, or change behavior
 * Minor revisions may also remove API calls, but these must be clearly announced in History.txt, with instructions on how to migrate 
 * Major revisions are about marketing more than technical needs. We will stay in major version 0 until we're happy taking the "alpha" label off it. And if we ever do a major overhaul of the API, especially one that breaks backwards compatibility, we will probably want to increment the major version.
-* We will not be shy about incrementing version numbers -- if we end up going to version 0.943.67 then so be it.
+* We will not be shy about incrementing version numbers -- if we end up going to version 0.943.67454 then so be it.
 * Developers should attempt to add lines in History.txt to reflect their checkins. These should reflect feature-level changes, not just one line per checkin. The top section of History.txt is used as the Release Notes by the "rake publish" task and will appear on the RubyForge file page.
-* Someone making a release must fill in the version number in History.txt as well as in Rakefile. Note that "rake publish" requires a "VERSION=1.2.3" parameter to confirm you're releasing the version you intend.
+* Someone making a release must fill in the version number in History.txt as well as in Rakefile. Note that "rake release" requires a "VERSION=1.2.3" parameter to confirm you're releasing the version you intend.
 * As soon as a release is made and published, the publisher should go into History.txt and make a new section. Since we won't yet know what the next version will be called, the new section will be noted by a single "==" at the top of the file. 
 
 

data/lib/erector.rb

@@ -1,6 +1,7 @@
 require "rubygems"
 require "action_controller"
 require "erector/extensions/action_controller"
+require "erector/extensions/action_view_template_handler"
 require "erector/extensions/object"
 require "erector/helpers"
 require "erector/html_parts"

data/lib/erector/extensions/action_controller.rb

@@ -8,6 +8,15 @@ class ActionController::Base
     @rendered_widget = widget_class.new(@template, assigns.merge(:params => params))
     @rendered_widget.to_s
   end
+  
+  def render_with_erector_widget(*options, &block)
+    if options.first.is_a?(Hash) && widget = options.first.delete(:widget)
+      render_widget widget, *options, &block
+    else
+      render_without_erector_widget *options, &block
+    end
+  end
+  alias_method_chain :render, :erector_widget
 
   attr_reader :rendered_widget
 end

data/lib/erector/extensions/action_view_template_handler.rb

@@ -0,0 +1,26 @@
+module ActionView
+  module TemplateHandlers
+    class Erector
+      def initialize(view)
+        @view = view
+      end
+
+      def render(template, local_assigns)
+        paths = @view.first_render.split('/')
+        dot_rb = /\.rb$/
+        widget_class = paths.inject(Views) do |current_module, node|
+          current_module.const_get(node.gsub(dot_rb, '').camelize)
+        end
+
+        rendered_widget = widget_class.new(@view, @view.assigns)
+        rendered_widget.to_s
+      end
+    end
+  end
+end
+
+ActionView::Base.instance_eval do
+  if respond_to?(:register_template_handler)
+    register_template_handler :rb, ActionView::TemplateHandlers::Erector
+  end
+end

data/lib/erector/widget.rb

@@ -39,7 +39,6 @@ module Erector
         end
       end
       @helpers = helpers
-      fake_erbout
       @parent = block ? eval("self", block.binding) : nil
       @doc = doc
       @block = block
@@ -50,7 +49,7 @@ module Erector
         instance_eval(&@block)
       end
     end
-    
+
     def render_to(doc)
       @doc = doc
       render
@@ -128,7 +127,7 @@ module Erector
       # (maybe, but the syntax is specific to javascript; it isn't
       # really a generic XML CDATA section.  Specifically,
       # ]]> within value is not treated as ending the
-      # CDATA section by Firefox2 when parsing text/html, 
+      # CDATA section by Firefox2 when parsing text/html,
       # although I guess we could refuse to generate ]]>
       # there, for the benefit of XML/XHTML parsers).
       rawtext "\n// <![CDATA[\n"
@@ -226,14 +225,22 @@ module Erector
         super
       end
     end
-    
-    def fake_erbout
+
+    def fake_erbout(&blk)
       widget = self
       @helpers.metaclass.class_eval do
+        raise "Cannot nest fake_erbout" if instance_methods.include?('concat_without_erector')
+        alias_method :concat_without_erector, :concat
         define_method :concat do |some_text, binding|
           widget.text widget.raw(some_text)
         end
       end
+      yield
+    ensure
+      @helpers.metaclass.class_eval do
+        alias_method :concat, :concat_without_erector
+        remove_method :concat_without_erector
+      end
     end
   end
 end

data/lib/erector/widgets/table.rb

@@ -20,32 +20,43 @@ module Erector
 
       def render
         table do
-          tr do
-            column_definitions.each do |column_def|
-              th do
-                if column_def.name.is_a?(Proc)
-                  self.instance_exec(column_def.id, &column_def.name)
-                else
-                  text column_def.name
+          thead do
+            tr do
+              column_definitions.each do |column_def|
+                th do
+                  if column_def.name.is_a?(Proc)
+                    self.instance_exec(column_def.id, &column_def.name)
+                  else
+                    text column_def.name
+                  end
                 end
               end
             end
           end
           tbody do
             @row_objects.each_with_index do |object, index|
-              tr(:class => cycle(index)) do
-                column_definitions.each do |column_def|
-                  td do
-                    self.instance_exec(object, &column_def.cell_proc)
-                  end
-                end
-              end
+              row object, index
             end
           end
         end
       end
 
       protected
+      def row(object, index)
+        tr(:class => row_css_class(object, index)) do
+          column_definitions.each do |column_def|
+            td do
+              self.instance_exec(object, &column_def.cell_proc)
+            end
+          end
+        end
+      end
+
+      # Im overridable
+      def row_css_class(object, index)
+        cycle(index)
+      end
+
       def column_definitions
         self.class.column_definitions
       end

data/spec/erect/erect_spec.rb

@@ -0,0 +1,7 @@
+dir = File.dirname(__FILE__)
+require "#{dir}/spec_helper"
+
+context "" do
+  specify "" do
+  end
+end

data/spec/erector/extensions/render_widget_spec.rb

@@ -10,6 +10,10 @@ module BaseSpec
     def index_with_explicit_assigns
       render_widget Erector::TestWidget, :foobar => "foobar"
     end
+    
+    def index_with_render_colon_widget
+      render :widget => Erector::TestWidget, :foobar => "foobar"
+    end
   end
 
   class Erector::TestWidget < Erector::Widget
@@ -18,7 +22,7 @@ module BaseSpec
     end
   end
 
-  describe TestWidgetController, "#render_widget" do
+  describe TestWidgetController, "rendering widgets" do
     before do
       @controller = BaseSpec::TestWidgetController.new
       @request = ActionController::TestRequest.new
@@ -26,24 +30,39 @@ module BaseSpec
       @controller.send(:initialize_template_class, @response)
       @controller.send(:assign_shortcuts, @request, @response)
       class << @controller
-        public :rendered_widget
+        public :rendered_widget, :render
       end
     end
 
-    it "assigns to @rendered_widget" do
-      @controller.rendered_widget.should be_nil
-      @controller.render_widget Erector::TestWidget
-      @controller.rendered_widget.should be_instance_of(Erector::TestWidget)
-    end
+    describe "#render_widget" do
+      it "assigns to @rendered_widget" do
+        @controller.rendered_widget.should be_nil
+        @controller.render_widget Erector::TestWidget
+        @controller.rendered_widget.should be_instance_of(Erector::TestWidget)
+      end
     
-    it "instantiates a widget with implicit assigns" do
-      @controller.index_with_implicit_assigns
-      @response.body.should == "foobar"
-    end
+      it "instantiates a widget with implicit assigns" do
+        @controller.index_with_implicit_assigns
+        @response.body.should == "foobar"
+      end
 
-    it "instantiates a widget with explicit assigns" do
-      @controller.index_with_explicit_assigns
-      @response.body.should == "foobar"
+      it "instantiates a widget with explicit assigns" do
+        @controller.index_with_explicit_assigns
+        @response.body.should == "foobar"
+      end
+    end
+    
+    describe "#render :widget" do
+      it "assigns to @rendered_widget" do
+        @controller.rendered_widget.should be_nil
+        @controller.render :widget => Erector::TestWidget
+        @controller.rendered_widget.should be_instance_of(Erector::TestWidget)
+      end
+      
+      it "instantiates a widget with explicit assigns" do
+        @controller.index_with_render_colon_widget
+        @response.body.should == "foobar"
+      end
     end
   end
 end

data/spec/erector/widgets/table_spec.rb

@@ -1,5 +1,7 @@
 require File.expand_path("#{File.dirname(__FILE__)}/../../spec_helper")
 
+#TODO: This is very confusing with column_a etc.  Rewrite to use LastName, FirstName, Email or something like that.
+
 module TableSpec
   class DefaultsTestTable < Erector::Widgets::Table
     column :column_a

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: erector
 version: !ruby/object:Gem::Version 
-  version: 0.1.25
-platform: ruby
+  version: 0.2.42
+platform: ""
 authors: 
 - Pivotal Labs
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2008-02-26 00:00:00 -08:00
+date: 2008-04-11 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,7 +21,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.5.0
     version: 
-description: Erector is a Builder-based view framework, inspired by Markaby but overcoming some of its flaws. In Erector all views are objects, not template files, which allows the full power of OO (inheritance, modular decomposition, encapsulation) in views.
+description: Erector is a Builder-like view framework, inspired by Markaby but overcoming some of its flaws. In Erector all views are objects, not template files, which allows the full power of object-oriented programming (inheritance, modular decomposition, encapsulation) in views.
 email: 
 - alex@pivotallabs.com
 executables: []
@@ -31,26 +31,29 @@ extensions: []
 extra_rdoc_files: 
 - README.txt
 files: 
+- spec/erect
 - spec/erector
+- spec/spec_helper.rb
+- spec/spec_suite.rb
+- spec/view_caching.rb
+- spec/erect/erect_spec.rb
 - spec/erector/extensions
-- spec/erector/extensions/render_widget_spec.rb
 - spec/erector/widget_spec.rb
 - spec/erector/widgets
+- spec/erector/extensions/render_widget_spec.rb
 - spec/erector/widgets/table_spec.rb
-- spec/spec_helper.rb
-- spec/spec_suite.rb
-- spec/view_caching.rb
 - lib/erector
+- lib/erector.rb
 - lib/erector/extensions
-- lib/erector/extensions/action_controller.rb
-- lib/erector/extensions/object.rb
 - lib/erector/helpers.rb
 - lib/erector/html_parts.rb
 - lib/erector/widget.rb
 - lib/erector/widgets
-- lib/erector/widgets/table.rb
 - lib/erector/widgets.rb
-- lib/erector.rb
+- lib/erector/extensions/action_controller.rb
+- lib/erector/extensions/action_view_template_handler.rb
+- lib/erector/extensions/object.rb
+- lib/erector/widgets/table.rb
 - README.txt
 has_rdoc: true
 homepage: http://erector.rubyforge.org
@@ -75,9 +78,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: erector
-rubygems_version: 1.0.1
+rubygems_version: 0.9.5
 signing_key: 
 specification_version: 2
-summary: Erector is a Builder-based view framework, inspired by Markaby but overcoming some of its flaws
+summary: Erector is a Builder-like view framework, inspired by Markaby but overcoming some of its flaws
 test_files: []