erector 0.7.2 → 0.8.0

data/lib/erector/rails/extensions/rails_widget.rb

@@ -1,84 +1,126 @@
 module Erector
   module Rails
-    # These controller instance variables should not be passed to the
-    # widget if it does not +need+ them.
-    NON_NEEDED_CONTROLLER_INSTANCE_VARIABLES = [:@template, :@_request]
-    
-    def self.render(widget, controller, assigns = nil)
-      if widget.is_a?(Class)
-        unless assigns
-          needs = widget.get_needed_variables
-          assigns = {}
-          variables = controller.instance_variable_names
-          variables -= controller.protected_instance_variables
-          variables.each do |name|
-            assign = name.sub('@', '').to_sym
-            next if !needs.empty? && !needs.include?(assign) && NON_NEEDED_CONTROLLER_INSTANCE_VARIABLES.include?(name.to_sym)
-            assigns[assign] = controller.instance_variable_get(name)
-          end
-        end
+    def self.assigns_for(widget_class, view, local_assigns, is_partial)
+      assigns = {}
+
+      instance_variables = view.instance_variables_for_widget_assignment
+      if is_partial || widget_class.ignore_extra_controller_assigns
+        instance_variables = remove_unneeded_assigns(widget_class, instance_variables)
+      end
+
+      assigns.merge!(instance_variables) unless is_partial && (! widget_class.controller_assigns_propagate_to_partials)
+
+      if is_partial
+        assigns.merge!(filter_local_assigns_for_partial(widget_class, local_assigns || { }))
+      end
+
+      assigns
+    end
 
+    def self.remove_unneeded_assigns(widget_class, assigns)
+      needs = widget_class.needed_variables
+      if needs.empty?
+        assigns
+      else
+        assigns.reject { |key, value| ! needs.include?(key) }
+      end
+    end
+
+    def self.filter_local_assigns_for_partial(widget_class, local_assigns)
+      widget_class_variable_name = widget_class.name.underscore
+      widget_class_variable_name = $1 if widget_class_variable_name =~ %r{.*/(.*?)$}
+
+      local_assigns.reject do |name, value|
+        name == :object || name == widget_class_variable_name.to_sym
+      end
+    end
+
+    def self.render(widget, view, assigns = nil, options = {})
+      if widget.is_a?(Class)
+        assigns ||= assigns_for(widget, view, nil, false)
         widget = widget.new(assigns)
       end
 
-      view = controller.response.template
       view.send(:_evaluate_assigns_and_ivars)
 
       view.with_output_buffer do
-        widget.to_s(
-          :output => view.output_buffer,
-          :parent => view,
-          :helpers => view
-        )
+        # Set parent to the view and use Rails's output buffer.
+        widget.to_html(options.merge(:parent => view,
+                                  :output => Output.new { view.output_buffer }))
       end
     end
 
     module WidgetExtensions
+      module ClassMethods
+        def ignore_extra_controller_assigns
+          out = @ignore_extra_controller_assigns
+          out ||= (superclass.ignore_extra_controller_assigns ? :true : :false) if superclass.respond_to?(:ignore_extra_controller_assigns)
+          out ||= :true
+          out == :true
+        end
+
+        # Often, large Rails applications will assign many controller instance variables.
+        # Sometimes these aren't used by a view: ApplicationController might assign
+        # variables that are used by many, but not all, views; and various other things
+        # may accumulate, especially if you've been using templating systems that are
+        # more forgiving than Erector. If you then migrate to Erector, you're stuck using
+        # no "needs" declaration at all, because it needs to contain every assigned
+        # variable, or Erector will raise an exception.
+        #
+        # If you set this to true (and it's inherited through to subclasses), however,
+        # then "needs" declarations on the widget will cause excess controller variables
+        # to be ignored -- they'll be unavailable to the widget (so 'needs' still means
+        # something), but they won't cause widget instantiation to fail, either. This
+        # can let a large Rails project transition to Erector more smoothly.
+        def ignore_extra_controller_assigns=(new_value)
+          @ignore_extra_controller_assigns = (new_value ? :true : :false)
+        end
+
+        def controller_assigns_propagate_to_partials
+          out = @controller_assigns_propagate_to_partials
+          out ||= (superclass.controller_assigns_propagate_to_partials ? :true : :false) if superclass.respond_to?(:controller_assigns_propagate_to_partials)
+          out ||= :true
+          out == :true
+        end
+
+        # In ERb templates, controller instance variables are available to any partial
+        # that gets rendered by the view, no matter how deeply-nested. This effectively
+        # makes controller instance variables "globals". In small view hierarchies this
+        # probably isn't an issue, but in large ones it can make debugging and
+        # reasoning about the code very difficult.
+        #
+        # If you set this to true (and it's inherited through to subclasses), then any
+        # widget that's getting rendered as a partial will only have access to locals
+        # explicitly passed to it (render :partial => ..., :locals => ...). (This
+        # doesn't change the behavior of widgets that are explicitly rendered, as they
+        # don't have this issue.) This can allow for cleaner encapsulation of partials,
+        # as they must be passed everything they use and can't rely on controller
+        # instance variables.
+        def controller_assigns_propagate_to_partials=(new_value)
+          @controller_assigns_propagate_to_partials = (new_value ? :true : :false)
+        end
+      end
+      
       def self.included(base)
-        base.alias_method_chain :output, :parent
-        base.alias_method_chain :capture, :parent
+        base.extend(ClassMethods)
       end
 
-      def output_with_parent
-        if parent.respond_to?(:output_buffer)
-          parent.output_buffer.is_a?(String) ? parent.output_buffer : handle_rjs_buffer
+      # We need to delegate #capture to parent.capture, so that when
+      # the captured block is executed, both erector and Rails output
+      # from within the block go to the appropriate buffer.
+      def capture(&block)
+        if parent.respond_to?(:capture)
+          raw(parent.capture(&block).to_s)
         else
-          output_without_parent
+          super
         end
       end
 
-      def capture_with_parent(&block)
-        parent ? raw(parent.capture(&block).to_s) : capture_without_parent(&block)
-      end
-
       # This is here to force #parent.capture to return the output
       def __in_erb_template;
       end
-
-      private
-
-      def handle_rjs_buffer
-        returning buffer = parent.output_buffer.dup.to_s do
-          parent.output_buffer.clear
-          parent.with_output_buffer(buffer) do
-            buffer << parent.output_buffer.to_s
-          end
-        end
-      end
     end
 
     Erector::Widget.send :include, WidgetExtensions
   end
-
-  # RailsWidget and InlineRailsWidget are for backward compatibility.
-  # New code should use Widget, InlineWidget, or Erector.inline.
-  class RailsWidget < Widget
-    def self.inline(*args, &block)
-      InlineRailsWidget.new(*args, &block)
-    end
-  end
-
-  class InlineRailsWidget < RailsWidget
-    include Inline
-  end
 end

data/lib/erector/rails/rails_form_builder.rb

@@ -4,17 +4,21 @@ module Erector
 
     def initialize(object_name, object, template, options, proc)
       @template = template
-      @parent = ActionView::Helpers::FormBuilder.new(object_name, object, template, options, proc)
+      @parent = ActionView::Base.default_form_builder.new(object_name, object, template, options, proc)
     end
 
     def method_missing(method_name, *args, &block)
       if parent.respond_to?(method_name)
         return_value = parent.send(method_name, *args, &block)
-        template.concat(return_value) if return_value.is_a?(String)
-        return_value
+        if return_value.is_a?(String)
+          template.concat(return_value)
+          nil
+        else
+          return_value
+        end
       else
         super
       end
     end
   end
-end
+end

data/lib/erector/rails/rails_version.rb

@@ -1,6 +1,6 @@
 module Erector
   module Rails
-    RAILS_VERSION = "2.3.4"
-    RAILS_VERSION_TAG = "v2.3.4"
+    RAILS_VERSION = "2.3.8"
+    RAILS_VERSION_TAG = "v2.3.8"
   end
 end

data/lib/erector/rails/template_handlers/ert_handler.rb

@@ -18,7 +18,7 @@ module ActionView #:nodoc:
           "  all[instance_variable] = instance_variable_get(instance_variable)",
           "  all",
           "end",
-          "r =::Erector.inline do",
+          "r = (controller.ert_template_base_class || ::Erector).inline do",
           "  memoized_instance_variables.each do |instance_variable, value|",
           "    instance_variable_set(instance_variable, value)",
           "  end",

data/lib/erector/rails/template_handlers/rb_handler.rb

@@ -1,9 +1,50 @@
+class ActionView::Base
+  def instance_variables_for_widget_assignment
+    instance_variables_for_widget_assignment_for(controller)
+  end
+
+  def instance_variables_for_widget_assignment_for(target)
+    assigns = { }
+    variables = target.instance_variable_names
+    variables -= target.protected_instance_variables if target.respond_to?(:protected_instance_variables)
+    variables -= %w{@real_format @request @template @_request}
+    variables.each do |name|
+      assign = name.sub('@', '').to_sym
+      assigns[assign] = target.instance_variable_get(name)
+    end
+    assigns
+  end
+end
+
+# Out of the box, the Cells plugin for Rails (http://cells.rubyforge.org/)
+# does not work with Erector, because Erector tries to grab instance variables
+# off the controller, rather than the cell itself. 
+#
+# This code patches up Cell::View to make it work, but only if the Cells plugin
+# is installed. (That's the bare "Cell::View" at the top, and rescue NameError
+# at the bottom.) While you'd imagine that unilaterally opening Cell::View
+# and adding the method would work, it doesn't; Cell::View is normally
+# autoloaded, and since we'd end up defining it here, we'd keep it from getting
+# loaded at all.
+begin
+  Cell::View
+  
+  class Cell::View < ActionView::Base
+    def instance_variables_for_widget_assignment
+      instance_variables_for_widget_assignment_for(cell)
+    end
+  end
+rescue NameError
+end
+
 module Erector
   class RbHandler < ActionView::TemplateHandler
     def render(template, local_assigns)
       require_dependency File.expand_path(template.filename)
       widget_class = "views/#{template.path_without_format_and_extension}".camelize.constantize
-      Erector::Rails.render(widget_class, @view.controller)
+      is_partial = (File.basename(template.path_without_format_and_extension) =~ /^_/)
+      assigns = Erector::Rails.assigns_for(widget_class, @view, local_assigns, is_partial)
+      Erector::Rails.render(widget_class, @view, assigns)
     end
   end
 end

data/lib/erector/raw_string.rb

@@ -1,8 +1,8 @@
 module Erector
   # A string that has a special type so Erector knows to render it directly, not HTML-escaped
   class RawString < String
-    def html_escape
-      self
+    def html_safe?
+      true
     end
   end
 end

data/lib/erector/sass.rb

@@ -0,0 +1,22 @@
+
+if Object.const_defined?(:Sass)
+  module Erector
+    # Adds sass support to Erector widgets. 
+    # Note that sass is provided inside the gem named "haml", 
+    # not the gem named "sass".
+    # To get sass support into your Erector project, install the 
+    # haml gem -- see http://sass-lang.com/download.html -- and
+    # then do something like this:
+    #     require 'rubygems'
+    #     require 'sass'
+    #
+    # Current support is barebones. Please offer suggestions (or better
+    # yet, patches) for whether and how to support, e.g., caching, 
+    # loading from files, precompilation, etc.
+    module Sass
+      def sass(sass_text)
+        style ::Sass::Engine.new(sass_text, :cache => false).render
+      end
+    end
+  end
+end

data/lib/erector/widget.rb

@@ -7,14 +7,15 @@ module Erector
   # or +p+ to emit HTML/XML tags. 
   #  
   # You can also define a widget on the fly by passing a block to +new+. This
-  # block will get executed when the widget's +content+ method is called.
+  # block will get executed when the widget's +content+ method is called. See
+  # the userguide for important details about the scope of this block when run --
+  # http://erector.rubyforge.org/userguide.html#blocks
   #
-  # To render a widget from the outside, instantiate it and call its +to_s+
+  # To render a widget from the outside, instantiate it and call its +to_html+
   # method.
   #
   # A widget's +new+ method optionally accepts an options hash. Entries in
-  # this hash are converted to instance variables, and +attr_reader+ accessors
-  # are defined for each.
+  # this hash are converted to instance variables.
   #
   # You can add runtime input checking via the +needs+ macro. See #needs. 
   # This mechanism is meant to ameliorate development-time confusion about
@@ -24,7 +25,7 @@ module Erector
   # To call one widget from another, inside the parent widget's +content+
   # method, instantiate the child widget and call the +widget+ method. This
   # assures that the same output stream is used, which gives better
-  # performance than using +capture+ or +to_s+. It also preserves the
+  # performance than using +capture+ or +to_html+. It also preserves the
   # indentation and helpers of the enclosing class.
   #  
   # In this documentation we've tried to keep the distinction clear between
@@ -32,252 +33,50 @@ module Erector
   # it writes to the output stream; "return" means that it returns a string
   # like a normal method and leaves it up to the caller to emit that string if
   # it wants.
-  class Widget
-    extend Erector::Externals # 'extend'ing since they're class methods, not instance methods
-    
-    class << self
-      def all_tags
-        Erector::Widget.full_tags + Erector::Widget.empty_tags
-      end
-
-      # Tags which are always self-closing. Click "[Source]" to see the full list.
-      def empty_tags
-        ['area', 'base', 'br', 'col', 'frame', 
-        'hr', 'img', 'input', 'link', 'meta']
-      end
-
-      # Tags which can contain other stuff. Click "[Source]" to see the full list.
-      def full_tags
-        [
-          'a', 'abbr', 'acronym', 'address', 'article', 'aside', 'audio',
-          'b', 'bdo', 'big', 'blockquote', 'body', 'button', 
-          'canvas', 'caption', 'center', 'cite', 'code', 'colgroup', 'command',
-          'datalist', 'dd', 'del', 'details', 'dfn', 'dialog', 'div', 'dl', 'dt',
-          'em', 'embed',
-          'fieldset', 'figure', 'footer', 'form', 'frameset',
-          'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'header', 'hgroup', 'html', 'i',
-          'iframe', 'ins', 'keygen', 'kbd', 'label', 'legend', 'li',
-          'map', 'mark', 'meter',
-          'nav', 'noframes', 'noscript',
-          'object', 'ol', 'optgroup', 'option',
-          'p', 'param', 'pre', 'progress',
-          'q', 'ruby', 'rt', 'rp', 's',
-          'samp', 'script', 'section', 'select', 'small', 'source', 'span', 'strike',
-          'strong', 'style', 'sub', 'sup',
-          'table', 'tbody', 'td', 'textarea', 'tfoot',
-          'th', 'thead', 'time', 'title', 'tr', 'tt', 'u', 'ul',
-          'var', 'video'
-        ]
-      end
-
-      def def_empty_tag_method(tag_name)
-        self.class_eval(<<-SRC, __FILE__, __LINE__)
-          def #{tag_name}(*args, &block)
-            __empty_element__('#{tag_name}', *args, &block)
-          end
-        SRC
-      end
-
-      def def_full_tag_method(tag_name)
-        self.class_eval(<<-SRC, __FILE__, __LINE__)
-          def #{tag_name}(*args, &block)
-              __element__(false, '#{tag_name}', *args, &block)
-          end
-
-          def #{tag_name}!(*args, &block)
-            __element__(true, '#{tag_name}', *args, &block)
-          end
-        SRC
-      end
-
-      def after_initialize(instance=nil, &blk)
-        if blk
-          after_initialize_parts << blk
-        elsif instance
-          if superclass.respond_to?(:after_initialize)
-            superclass.after_initialize instance
-          end
-          after_initialize_parts.each do |part|
-            instance.instance_eval &part
-          end
-        else
-          raise ArgumentError, "You must provide either an instance or a block"
-        end
-      end
-      
-      protected
-      def after_initialize_parts
-        @after_initialize_parts ||= []
-      end
-      
-    end
-
-    # Class method by which widget classes can declare that they need certain
-    # parameters. If needed parameters are not passed in to #new, then an
-    # exception will be thrown (with a hopefully useful message about which
-    # parameters are missing). This is intended to catch silly bugs like
-    # passing in a parameter called 'name' to a widget that expects a
-    # parameter called 'title'. Every variable declared in 'needs' will get an
-    # attr_reader accessor declared for it.
-    #
-    # You can also declare default values for parameters using hash syntax.
-    # You can put #needs declarations on multiple lines or on the same line;
-    # the only caveat is that if there are default values, they all have to be
-    # at the end of the line (so they go into the magic hash parameter).
-    #
-    # If a widget has no #needs declaration then it will accept any
-    # combination of parameters (and make accessors for them) just like
-    # normal. In that case there will be no 'attr_reader's declared. If a
-    # widget wants to declare that it takes no parameters, use the special
-    # incantation "needs nil" (and don't declare any other needs, or kittens
-    # will cry).
-    #
-    # Usage:
-    #    class FancyForm < Erector::Widget
-    #      needs :title, :show_okay => true, :show_cancel => false
-    #      ...
-    #    end
-    #  
-    # That means that
-    #   FancyForm.new(:title => 'Login')
-    # will succeed, as will
-    #   FancyForm.new(:title => 'Login', :show_cancel => true)
-    # but
-    #   FancyForm.new(:name => 'Login')
-    # will fail.
-    #
-    def self.needs(*args)
-      args.each do |arg|
-        (@needs ||= []) << (arg.nil? ? nil : (arg.is_a? Hash) ? arg : arg.to_sym)
-      end
-    end
-
-    protected
-    def self.get_needs
-      @needs ||= []
-
-      ancestors[1..-1].inject(@needs.dup) do |needs, ancestor|
-        needs.push(*ancestor.get_needs) if ancestor.respond_to?(:get_needs)
-        needs
-      end
-    end
-
-    def self.get_needed_variables
-      get_needs.map{|need| need.is_a?(Hash) ? need.keys : need}.flatten
-    end
-
-    def self.get_needed_defaults
-      get_needs.select{|need| need.is_a? Hash}
-    end
-
-    public
+  #
+  # Now, seriously, after playing around a bit, go read the user guide. It's
+  # fun!
+  class AbstractWidget
     @@prettyprint_default = false
     def prettyprint_default
       @@prettyprint_default
     end
 
+    def self.prettyprint_default
+      @@prettyprint_default
+    end
+
     def self.prettyprint_default=(enabled)
       @@prettyprint_default = enabled
     end
 
-    NON_NEWLINEY = {'i' => true, 'b' => true, 'small' => true,
-      'img' => true, 'span' => true, 'a' => true,
-      'input' => true, 'textarea' => true, 'button' => true, 'select' => true
-    }
-
-    SPACES_PER_INDENT = 2
-
-    RESERVED_INSTANCE_VARS = [:helpers, :assigns, :block, :output, :prettyprint, :indentation, :at_start_of_line]
-
-    attr_reader *RESERVED_INSTANCE_VARS
-    attr_reader :parent
-    attr_writer :block
-    
-    def initialize(assigns={}, &block)
-      unless assigns.is_a? Hash
-        raise "Erector's API has changed. Now you should pass only an options hash into Widget.new; the rest come in via to_s, or by using #widget."
-      end
-      @assigns = assigns
-      assign_instance_variables(assigns)
-      unless @parent
-        @parent = block ? eval("self", block.binding) : nil
-      end
-      @block = block
-      self.class.after_initialize self
+    def self.inline(*args, &block)
+      Class.new(self) do
+        include Erector::Inline
+      end.new(*args, &block)
     end
 
-#-- methods for other classes to call, left public for ease of testing and documentation
-#++
-
-    protected
-    def context(parent, output, prettyprint = false, indentation = 0, helpers = nil)
-      #TODO: pass in options hash, maybe, instead of parameters
-      original_parent = @parent
-      original_output = @output
-      original_indendation = @indentation
-      original_helpers = @helpers
-      original_prettyprint = @prettyprint
-      @parent = parent
-      @output = output
-      @at_start_of_line = true
-      raise "indentation must be a number, not #{indentation.inspect}" unless indentation.is_a? Fixnum
-      @indentation = indentation
-      @helpers = helpers
-      @prettyprint = prettyprint
-      yield
-    ensure
-      @parent = original_parent
-      @output = original_output
-      @indentation = original_indendation
-      @helpers = original_helpers
-      @prettyprint = original_prettyprint
+    [:helpers, :assigns, :output, :parent, :block].each do |attr|
+      class_eval(<<-SRC, __FILE__, __LINE__ + 1)
+        def #{attr}
+          @_#{attr}
+        end
+      SRC
     end
 
-    public
-    def assign_instance_variables (instance_variables)
-      needed = self.class.get_needed_variables
-      assigned = []
-      instance_variables.each do |name, value|
-        unless needed.empty? || needed.include?(name)
-          raise "Unknown parameter '#{name}'. #{self.class.name} only accepts #{needed.join(', ')}"
-        end
-        assign_instance_variable(name, value)
-        assigned << name
+    def initialize(assigns = {}, &block)
+      unless assigns.is_a? Hash
+        raise "Erector widgets are initialized with only a parameter hash. (Other parameters are passed to to_html, or the #widget method.)"
       end
 
-      # set variables with default values
-      self.class.get_needed_defaults.each do |hash|
-        hash.each_pair do |name, value|
-          unless assigned.include?(name)
-            assign_instance_variable(name, value)
-            assigned << name
-          end
-        end
-      end
+      @_assigns = assigns
 
-      missing = needed - assigned
-      unless missing.empty? || missing == [nil]
-        raise "Missing parameter#{missing.size == 1 ? '' : 's'}: #{missing.join(', ')}"
+      assigns.each do |name, value|
+        instance_variable_set(name.to_s[0..0] == '@' ? name : "@#{name}", value)
       end
-    end
-    
-    def assign_instance_variable (name, value)
-      raise ArgumentError, "Sorry, #{name} is a reserved variable name for Erector. Please choose a different name." if RESERVED_INSTANCE_VARS.include?(name)
-      name = name.to_s
-      ivar_name = (name[0..0] == '@' ? name : "@#{name}")
-      instance_variable_set(ivar_name, value)
-    end
-    
-    # Render (like to_s) but adding newlines and indentation.
-    # This is a convenience method; you may just want to call to_s(:prettyprint => true)
-    # so you can pass in other rendering options as well.  
-    def to_pretty
-      to_s(:prettyprint => true)
-    end
-    
-    # Render (like to_s) but stripping all tags.
-    def to_text
-      CGI.unescapeHTML(to_s(:prettyprint => false).gsub(/<[^>]*>/, ''))
+
+      @_parent = eval("self", block.binding) if block
+      @_block = block
     end
 
     # Entry point for rendering a widget (and all its children). This method
@@ -291,39 +90,40 @@ module Erector
     #               by default). 
     # indentation:: the amount of spaces to indent. Ignored unless prettyprint
     #               is true.
+    # max_length:: preferred maximum length of a line. Line wraps will only
+    #              occur at space characters, so a long word may end up creating
+    #              a line longer than this. If nil (default), then there is no
+    #              arbitrary limit to line lengths, and only internal newline
+    #              characters and prettyprinting will determine newlines in the
+    #              output.
     # helpers:: a helpers object containing utility methods. Usually this is a
     #           Rails view object.
     # content_method_name:: in case you want to call a method other than
     #                       #content, pass its name in here.
-    def to_s(options = {}, &blk)
-      raise "Erector::Widget#to_s now takes an options hash, not a symbol. Try calling \"to_s(:content_method_name=> :#{options})\"" if options.is_a? Symbol
-      _render(options, &blk).to_s
+    def to_html(options = {})
+      raise "Erector::Widget#to_html takes an options hash, not a symbol. Try calling \"to_html(:content_method_name=> :#{options})\"" if options.is_a? Symbol
+      _render(options).to_s
     end
-    
-    # Entry point for rendering a widget (and all its children). Same as #to_s
+
+    # alias for #to_html
+    # @deprecated Please use {#to_html} instead
+    def to_s(*args)
+      unless defined? @@already_warned_to_s
+        $stderr.puts "Erector::Widget#to_s is deprecated. Please use #to_html instead. Called from #{caller.first}"
+        @@already_warned_to_s = true
+      end
+      to_html(*args)
+    end
+
+    # Entry point for rendering a widget (and all its children). Same as #to_html
     # only it returns an array, for theoretical performance improvements when using a
     # Rack server (like Sinatra or Rails Metal).
     #
-    # # Options: see #to_s
-    def to_a(options = {}, &blk)
-      _render({:output => []}.merge(options), &blk).to_a
-    end
-    
-    def _render(options = {}, &blk)
-      options = {
-        :output => "",  # "" is apparently faster than [] in a long-running process
-        :prettyprint => prettyprint_default,
-        :indentation => 0,
-        :helpers => nil,
-        :parent => @parent,
-        :content_method_name => :content,
-      }.merge(options)
-      context(options[:parent], options[:output], options[:prettyprint], options[:indentation], options[:helpers]) do
-        send(options[:content_method_name], &blk)
-        output
-      end
+    # # Options: see #to_html
+    def to_a(options = {})
+      _render(options).to_a
     end
-    
+
     # Template method which must be overridden by all widget subclasses.
     # Inside this method you call the magic #element methods which emit HTML
     # and text to the output string. If you call "super" (or don't override
@@ -347,18 +147,7 @@ module Erector
     # If you want this block to have access to Erector methods then use 
     # Erector::Inline#content or Erector#inline.
     def call_block
-      @block.call(self) if @block
-    end
-
-    # To call one widget from another, inside the parent widget's +content+
-    # method, instantiate the child widget and call its +write_via+ method,
-    # passing in +self+. This assures that the same output string is used,
-    # which gives better performance than using +capture+ or +to_s+. You can
-    # also use the +widget+ method.
-    def write_via(parent)
-      context(parent, parent.output, parent.prettyprint, parent.indentation, parent.helpers) do
-        content
-      end
+      @_block.call(self) if @_block
     end
 
     # Emits a (nested) widget onto the current widget's output stream. Accepts
@@ -367,404 +156,62 @@ module Erector
     # If the first argument is an instance then the hash must be unspecified
     # (or empty). If a block is passed to this method, then it gets set as the
     # rendered widget's block.
-    def widget(target, assigns={}, &block)
-      child = if target.is_a? Class
-        target.new(assigns, &block)
-      else
-        unless assigns.empty?
-          raise "Unexpected second parameter. Did you mean to pass in variables when you instantiated the #{target.class.to_s}?"
-        end
-        target.block = block unless block.nil?
-        target
-      end
-      child.write_via(self)
-    end
-
-    # (Should we make this hidden?)
-    def html_escape
-      return to_s
-    end
-
-#-- methods for subclasses to call
-#++
-
-    # Internal method used to emit an HTML/XML element, including an open tag,
-    # attributes (optional, via the default hash), contents (also optional),
-    # and close tag.
-    #
-    # Using the arcane powers of Ruby, there are magic methods that call
-    # +element+ for all the standard HTML tags, like +a+, +body+, +p+, and so
-    # forth. Look at the source of #full_tags for the full list.
-    # Unfortunately, this big mojo confuses rdoc, so we can't see each method
-    # in this rdoc page, but trust us, they're there.
-    #
-    # When calling one of these magic methods, put attributes in the default
-    # hash. If there is a string parameter, then it is used as the contents.
-    # If there is a block, then it is executed (yielded), and the string
-    # parameter is ignored. The block will usually be in the scope of the
-    # child widget, which means it has access to all the methods of Widget,
-    # which will eventually end up appending text to the +output+ string. See
-    # how elegant it is? Not confusing at all if you don't think about it.
-    #
-    def element(*args, &block)
-      __element__(false, *args, &block)
-    end
-
-    # Like +element+, but string parameters are not escaped.
-    def element!(*args, &block)
-      __element__(true, *args, &block)
-    end
-
-    # Internal method used to emit a self-closing HTML/XML element, including
-    # a tag name and optional attributes (passed in via the default hash).
     #
-    # Using the arcane powers of Ruby, there are magic methods that call
-    # +empty_element+ for all the standard HTML tags, like +img+, +br+, and so
-    # forth. Look at the source of #empty_tags for the full list.
-    # Unfortunately, this big mojo confuses rdoc, so we can't see each method
-    # in this rdoc page, but trust us, they're there.
-    #
-    def empty_element(*args, &block)
-      __empty_element__(*args, &block)
-    end
-
-    # Returns an HTML-escaped version of its parameter. Leaves the output
-    # string untouched. Note that the #text method automatically HTML-escapes
-    # its parameter, so be careful *not* to do something like text(h("2<4"))
-    # since that will double-escape the less-than sign (you'll get
-    # "2&amp;lt;4" instead of "2&lt;4").
-    def h(content)
-      content.html_escape
-    end
-
-    # Emits an open tag, comprising '<', tag name, optional attributes, and '>'
-    def open_tag(tag_name, attributes={})
-      indent_for_open_tag(tag_name)
-      @indentation += SPACES_PER_INDENT
-
-      output << "<#{tag_name}#{format_attributes(attributes)}>"
-      @at_start_of_line = false
-    end
-
-    # Emits text.  If a string is passed in, it will be HTML-escaped. If a
-    # widget or the result of calling methods such as raw is passed in, the
-    # HTML will not be HTML-escaped again. If another kind of object is passed
-    # in, the result of calling its to_s method will be treated as a string
-    # would be.
-    def text(value)
-      if value.is_a? Widget
-        widget value
+    # This is the preferred way to call one widget from inside another. This
+    # method assures that the same output string is used, which gives better
+    # performance than using +capture+ or +to_html+.
+    def widget(target, assigns = {}, options = {}, &block)
+      if target.is_a? Class
+        target.new(assigns, &block)._render_via(self, options)
       else
-        output <<(value.html_escape)
-      end
-      @at_start_of_line = false
-      nil
-    end
-
-    # Returns text which will *not* be HTML-escaped.
-    def raw(value)
-      RawString.new(value.to_s)
-    end
-
-    # Emits text which will *not* be HTML-escaped. Same effect as text(raw(s))
-    def text!(value)
-      text raw(value)
-    end
-
-    alias rawtext text!
-
-    # Returns a copy of value with spaces replaced by non-breaking space characters.
-    # With no arguments, return a single non-breaking space.
-    # The output uses the escaping format '&#160;' since that works
-    # in both HTML and XML (as opposed to '&nbsp;' which only works in HTML).
-    def nbsp(value = " ")
-      raw(value.html_escape.gsub(/ /,'&#160;'))
-    end
-    
-    # Return a character given its unicode code point or unicode name.
-    def character(code_point_or_name)
-      if code_point_or_name.is_a?(Symbol)
-        found = Erector::CHARACTERS[code_point_or_name]
-        if found.nil?
-          raise "Unrecognized character #{code_point_or_name}"
-        end
-        raw("&#x#{sprintf '%x', found};")
-      elsif code_point_or_name.is_a?(Integer)
-        raw("&#x#{sprintf '%x', code_point_or_name};")
-      else
-        raise "Unrecognized argument to character: #{code_point_or_name}"
-      end
-    end
-
-    # Emits a close tag, consisting of '<', '/', tag name, and '>'
-    def close_tag(tag_name)
-      @indentation -= SPACES_PER_INDENT
-      indent()
-
-      output <<("</#{tag_name}>")
-
-      if newliney?(tag_name)
-        _newline
-      end
-    end
-    
-    # Emits the result of joining the elements in array with the separator.
-    # The array elements and separator can be Erector::Widget objects,
-    # which are rendered, or strings, which are html-escaped and output.
-    def join(array, separator)
-      first = true
-      array.each do |widget_or_text|
-        if !first
-          text separator
+        unless assigns.empty?
+          raise "Unexpected second parameter. Did you mean to pass in assigns when you instantiated the #{target.class.to_s}?"
         end
-        first = false
-        text widget_or_text
+        target._render_via(self, options, &block)
       end
     end
 
-    # Emits an XML instruction, which looks like this: <?xml version=\"1.0\" encoding=\"UTF-8\"?>
-    def instruct(attributes={:version => "1.0", :encoding => "UTF-8"})
-      output << "<?xml#{format_sorted(sort_for_xml_declaration(attributes))}?>"
-    end
-
-    # Emits an HTML comment (&lt;!-- ... --&gt;) surrounding +text+ and/or the output of +block+.
-    # see http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.2.4
-    #
-    # If +text+ is an Internet Explorer conditional comment condition such as "[if IE]",
-    # the output includes the opening condition and closing "[endif]". See
-    # http://www.quirksmode.org/css/condcom.html
-    #
-    # Since "Authors should avoid putting two or more adjacent hyphens inside comments,"
-    # we emit a warning if you do that.
-    def comment(text = '', &block)
-      puts "Warning: Authors should avoid putting two or more adjacent hyphens inside comments." if text =~ /--/
-
-      conditional = text =~ /\[if .*\]/
-
-      rawtext "<!--"
-      rawtext text
-      rawtext ">" if conditional
-
-      if block
-        rawtext "\n"
-        block.call
-        rawtext "\n"
-      end
-
-      rawtext "<![endif]" if conditional
-      rawtext "-->\n"
-    end
-
     # Creates a whole new output string, executes the block, then converts the
     # output string to a string and returns it as raw text. If at all possible
-    # you should avoid this method since it hurts performance, and use
-    # +widget+ or +write_via+ instead.
-    def capture(&block)
-      begin
-        original_output = output
-        @output = ""
-        yield
-        raw(output.to_s)
-      ensure
-        @output = original_output
-      end
-    end
-
-    full_tags.each do |tag_name|
-      def_full_tag_method(tag_name)
-    end
-
-    empty_tags.each do |tag_name|
-      def_empty_tag_method(tag_name)
-    end
-
-    # Emits a javascript block inside a +script+ tag, wrapped in CDATA
-    # doohickeys like all the cool JS kids do.
-    def javascript(*args, &block)
-      if args.length > 2
-        raise ArgumentError, "Cannot accept more than two arguments"
-      end
-      attributes, value = nil, nil
-      arg0 = args[0]
-      if arg0.is_a?(Hash)
-        attributes = arg0
-      else
-        value = arg0
-        arg1 = args[1]
-        if arg1.is_a?(Hash)
-          attributes = arg1
-        end
-      end
-      attributes ||= {}
-      attributes[:type] = "text/javascript"
-      open_tag 'script', attributes
-
-      # Shouldn't this be a "cdata" HtmlPart?
-      # (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,
-      # although I guess we could refuse to generate ]]>
-      # there, for the benefit of XML/XHTML parsers).
-      rawtext "\n// <![CDATA[\n"
-      if block
-        instance_eval(&block)
-      else
-        rawtext value
-      end
-      rawtext "\n// ]]>\n"
-
-      close_tag 'script'
-      rawtext "\n"
-    end
-    
-    # Convenience method to emit a css file link, which looks like this:
-    # <link href="erector.css" rel="stylesheet" type="text/css" />
-    # The parameter is the full contents of the href attribute, including any ".css" extension.
-    #
-    # If you want to emit raw CSS inline, use the #style method instead.
-    def css(href, options = {})
-      link({:rel => 'stylesheet', :type => 'text/css', :href => href}.merge(options))
-    end
-    
-    # Convenience method to emit an anchor tag whose href and text are the same,
-    # e.g. <a href="http://example.com">http://example.com</a>
-    def url(href, options = {})
-      a href, ({:href => href}.merge(options))
-    end
-
-    # makes a unique id based on the widget's class name and object id
-    # that you can use as the HTML id of an emitted element
-    def dom_id
-      "#{self.class.name.gsub(/:+/,"_")}_#{self.object_id}"
-    end
-
-    # emits a jQuery script that is to be run on document ready
-    def jquery(txt)
-      javascript do
-        jquery_ready txt
-      end
+    # you should avoid this method since it hurts performance, and use +widget+
+    # instead.
+    def capture
+      original, @_output = output, Output.new
+      yield
+      original.widgets.concat(output.widgets) # todo: test!!!
+      output.to_s
+    ensure
+      @_output = original
     end
 
     protected
-    def jquery_ready(txt)
-      rawtext "\n"
-      rawtext "jQuery(document).ready(function($){\n"
-      rawtext txt
-      rawtext "\n});"
-    end
-    
-### internal utility methods
-
-protected
-    def __element__(raw, tag_name, *args, &block)
-      if args.length > 2
-        raise ArgumentError, "Cannot accept more than four arguments"
-      end
-      attributes, value = nil, nil
-      arg0 = args[0]
-      if arg0.is_a?(Hash)
-        attributes = arg0
-      else
-        value = arg0
-        arg1 = args[1]
-        if arg1.is_a?(Hash)
-          attributes = arg1
-        end
-      end
-      attributes ||= {}
-      open_tag tag_name, attributes
-      if block && value
-        raise ArgumentError, "You can't pass both a block and a value to #{tag_name} -- please choose one."
-      end
-      if block
-        block.call
-      elsif raw
-        text! value
-      else
-        text value
-      end
-      close_tag tag_name
-    end
-
-    def __empty_element__(tag_name, attributes={})
-      indent_for_open_tag(tag_name)
-
-      output << "<#{tag_name}#{format_attributes(attributes)} />"
-
-      if newliney?(tag_name)
-        _newline
-      end
-    end
-    
-    def _newline
-      return unless @prettyprint      
-      output << "\n"
-      @at_start_of_line = true
-    end
-
-    def indent_for_open_tag(tag_name)
-      return unless @prettyprint      
-      if !@at_start_of_line && newliney?(tag_name)
-        _newline
-      end
-      indent()
-    end
-
-    def indent()
-      if @at_start_of_line
-        output << " " * [@indentation, 0].max
-      end
-    end
-
-    def format_attributes(attributes)
-      if !attributes || attributes.empty?
-        ""
-      else
-        format_sorted(sorted(attributes))
-      end
-    end
-
-    def format_sorted(sorted)
-      results = ['']
-      sorted.each do |key, value|
-        if value
-          if value.is_a?(Array)
-            value = value.flatten
-            next if value.empty?
-            value = value.join(' ')
-          end
-          results << "#{key}=\"#{value.html_escape}\""
-        end
-      end
-      return results.join(' ')
-    end
-
-    def sorted(attributes)
-      stringized = []
-      attributes.each do |key, value|
-        stringized << [key.to_s, value]
-      end
-      return stringized.sort
-    end
+    def _render(options = {}, &block)
+      @_block   = block if block
+      @_parent  = options[:parent]  || parent
+      @_helpers = options[:helpers] || parent
+      @_output  = options[:output]
+      @_output  = Output.new(options) unless output.is_a?(Output)
 
-    def sort_for_xml_declaration(attributes)
-      # correct order is "version, encoding, standalone" (XML 1.0 section 2.8).
-      # But we only try to put version before encoding for now.
-      stringized = []
-      attributes.each do |key, value|
-        stringized << [key.to_s, value]
-      end
-      return stringized.sort{|a, b| b <=> a}
+      output.widgets << self.class
+      send(options[:content_method_name] || :content)
+      output
     end
 
-    def newliney?(tag_name)
-      if @prettyprint
-        !NON_NEWLINEY.include?(tag_name)
-      else
-        false
-      end
+    def _render_via(parent, options = {}, &block)
+      _render(options.merge(:parent  => parent,
+                            :output  => parent.output,
+                            :helpers => parent.helpers), &block)
     end
+  end
 
+  class Widget < AbstractWidget
+    include Erector::HTML
+    include Erector::Needs
+    include Erector::Caching
+    include Erector::Externals
+    include Erector::Convenience
+    include Erector::JQuery
+    include Erector::AfterInitialize
+    include Erector::Sass if Object.const_defined?(:Sass)
   end
 end