erector 0.7.1 → 0.7.2

data/README.txt

@@ -62,6 +62,20 @@ To install as a Rails plugin:
 When installing this way, erector is automatically available to your Rails code
 (no require directive is needed).
 
+== CREDITS:
+
+Core Team:
+* Alex Chaffee
+* Brian Takita
+
+Special Thanks To:
+* Abby (Chaffee's muse & Best friend)
+* Jim Kingdon
+* Jeff Dean
+* John Firebaugh
+* Nathan Sobo
+* Nick Kallen
+
 == LICENSE:
 
 (The MIT License)

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 7
-:patch: 1
+:patch: 2

data/bin/erector

@@ -1,8 +1,13 @@
 #!/usr/bin/env ruby
-dir = File.expand_path(File.dirname(__FILE__))
-$LOAD_PATH.unshift("#{dir}/../lib")
-require "erector"
-require "erector/erect"
+
+begin
+  require 'erector'
+rescue LoadError
+  require 'rubygems'
+  require 'erector'
+end
+
+require 'erector/erect'
 
 unless Erector::Erect.new(ARGV).run
   exit 1

data/lib/erector.rb

@@ -1,19 +1,13 @@
-require "rubygems"
-dir = File.dirname(__FILE__)
-require 'cgi'
-require 'yaml'
+require "cgi"
+require "yaml"
 require "active_support/inflector"
 require "active_support/inflections"
-require "#{dir}/erector/extensions/object"
-require "#{dir}/erector/raw_string"
-require "#{dir}/erector/externals"
-require "#{dir}/erector/widget"
-require "#{dir}/erector/inline"
-require "#{dir}/erector/unicode"
-require "#{dir}/erector/widgets"
-require "#{dir}/erector/version"
-require "#{dir}/erector/mixin"
-if Object.const_defined?(:RAILS_ROOT)
-  require "#{dir}/erector/rails"
-end
-
+require "erector/extensions/object"
+require "erector/raw_string"
+require "erector/externals"
+require "erector/widget"
+require "erector/inline"
+require "erector/unicode"
+require "erector/widgets"
+require "erector/version"
+require "erector/mixin"

data/lib/erector/erected.rb

@@ -20,7 +20,7 @@ module Erector
       parent = File.dirname(@in_file)
       grandparent = File.dirname(parent)
       if File.basename(grandparent) == "views"
-        ["Views::" + classize(File.basename(parent)) + "::" + base, "Erector::RailsWidget"]
+        ["Views::" + classize(File.basename(parent)) + "::" + base, "Erector::Widget"]
       else
         [base, "Erector::Widget"]
       end

data/lib/erector/externals.rb

@@ -1,28 +1,31 @@
 module Erector
+  class External < Struct.new(:type, :klass, :text, :options)
+    def initialize(type, klass, text, options = {})
+      super(type.to_sym, klass, text, options)
+    end
+    
+    def ==(other)
+      (self.type == other.type and
+      self.text == other.text and
+      self.options == other.options) ? true : false
+    end
+  end
+  
   module Externals
     def externals(type, klass = nil)
       type = type.to_sym
-      assure_externals_declared(type, klass)
-      x = @@externals[type].dup
-      if klass
-        x.select{|value| @@externals[klass].include?(value)}
-      else
-        x
+      (@@externals ||= []).select do |x| 
+        x.type == type && 
+        (klass.nil? || x.klass == klass)
       end
     end
 
-    def assure_externals_declared(type, klass)
-      @@externals ||= {}
-      @@externals[type] ||= []
-      @@externals[klass] ||= [] if klass
-    end
-
-    def external(type, value)
+    def external(type, value, options = {})
       type = type.to_sym
       klass = self # since it's a class method, self should be the class itself
-      assure_externals_declared(type, klass)
-      @@externals[type] << value unless @@externals[type].include?(value)
-      @@externals[klass] << value unless @@externals[klass].include?(value)
+      x = External.new(type, klass, value, options)
+      @@externals ||= []
+      @@externals << x unless @@externals.include?(x)
     end
   end
 

data/lib/erector/inline.rb

@@ -4,17 +4,18 @@ module Erector
   end
   
   module Inline
-    # Evaluates its block (the one that was passed in the constructor) as a new widget's
-    # content method.
-    # Since "self" is pointing to the new widget, it can get access
-    # to parent widget methods via method_missing. Since it executes inside the 
-    # widget it does not
-    # have access to instance variables of the caller, although it does
-    # have access to bound variables.
-    def content
-      if @block
-        instance_eval(&@block)
-      end
+    # Executes the widget's block (the one that was passed in the
+    # constructor). Since "self" is pointing to the new widget, the block does
+    # not naturally have access to parent method methods, so an
+    # Erector::Inline widget uses some method_missing black magic to propagate
+    # messages to the parent object. Since it executes inside the *called*
+    # widget's context, when the block refers to instance variables, it's
+    # talking about those of this widget, not the caller. It does, of course,
+    # have access to bound local variables of the caller, so you can use those
+    # to smuggle in instance variables.
+    def call_block
+      # note that instance_eval seems to pass in self as a parameter to the block
+      instance_eval(&@block) if @block
     end
     
     private

data/lib/erector/mixin.rb

@@ -3,9 +3,12 @@ module Erector
     # Executes the block as if it were the content body of a fresh Erector::Inline,
     # and returns the #to_s value. Since it executes inside the new widget it does not
     # have access to instance variables of the caller, although it does
-    # have access to bound variables. 
+    # have access to bound variables. Funnily enough, the options are passed in to both
+    # to_s *and* to the widget itself, so they show up as instance variables.
     def erector(options = {}, &block)
-      Erector.inline(&block).to_s(options)
+      vars = options.dup
+      vars.delete_if {|key, value| Erector::Widget::RESERVED_INSTANCE_VARS.include?(key)}
+      Erector.inline(vars, &block).to_s(options)
     end
   end
 end

data/lib/erector/rails.rb

@@ -1,10 +1,27 @@
-dir = File.dirname(__FILE__)
 require "action_controller"
-require "#{dir}/rails/rails_version"
-require "#{dir}/rails/rails_form_builder"
-require "#{dir}/rails/extensions/rails_widget"
-require "#{dir}/rails/extensions/action_controller"
-require "#{dir}/rails/extensions/action_view"
-require "#{dir}/rails/extensions/rails_widget/rails_helpers"
-require "#{dir}/rails/template_handlers/rb_handler"
-require "#{dir}/rails/template_handlers/ert_handler"
+require "erector/rails/rails_version"
+require "erector/rails/rails_form_builder"
+require "erector/rails/extensions/rails_widget"
+require "erector/rails/extensions/action_controller"
+require "erector/rails/extensions/rails_widget/rails_helpers"
+require "erector/rails/template_handlers/rb_handler"
+require "erector/rails/template_handlers/ert_handler"
+
+module Erector
+  def self.init_rails(binding)
+    # Rails defaults do not include app/views in the eager load path.
+    # It needs to be there, because erector views are .rb files.
+    if config = eval("config if defined? config", binding)
+      view_path = config.view_path
+      config.load_paths       << view_path unless config.load_paths.include?(view_path)
+      config.eager_load_paths << view_path unless config.eager_load_paths.include?(view_path)
+
+      # Rails probably already ran Initializer#set_load_path and
+      # #set_autoload_paths by the time we got here.
+      $LOAD_PATH.unshift(view_path) unless $LOAD_PATH.include?(view_path)
+      unless ActiveSupport::Dependencies.load_paths.include?(view_path)
+        ActiveSupport::Dependencies.load_paths << view_path
+      end
+    end
+  end
+end

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

@@ -1,23 +1,11 @@
 ActionController::Base.class_eval do
   def render_widget(widget_class, assigns=nil)
-    @__widget_class = widget_class
-    if assigns
-      @__widget_assigns = assigns
-    else
-      @__widget_assigns = {}
-      variables = instance_variable_names
-      variables -= protected_instance_variables
-      variables.each do |name|
-        @__widget_assigns[name.sub('@', "")] = instance_variable_get(name)
-      end
-    end
-    response.template.send(:_evaluate_assigns_and_ivars)
-    render :inline => "<% @__widget_class.new(@__widget_assigns.merge(:parent => self)).to_s %>"
+    render :text => Erector::Rails.render(widget_class, self, assigns)
   end
 
   def render_with_erector_widget(*options, &block)
     if options.first.is_a?(Hash) && widget = options.first.delete(:widget)
-      render_widget widget, @assigns, &block
+      render_widget widget, @assigns
     else
       render_without_erector_widget *options, &block
     end

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

@@ -1,44 +1,84 @@
 module Erector
-  class RailsWidget < Widget
-    def self.inline(*args, &block)
-      InlineRailsWidget.new(*args, &block)
-    end
+  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 output
-      process_output_buffer || @output
-    end
+        widget = widget.new(assigns)
+      end
+
+      view = controller.response.template
+      view.send(:_evaluate_assigns_and_ivars)
 
-    def capture_with_parent(&block)
-      parent ? parent.capture(&block) : capture_without_parent(&block)
+      view.with_output_buffer do
+        widget.to_s(
+          :output => view.output_buffer,
+          :parent => view,
+          :helpers => view
+        )
+      end
     end
 
-    alias_method_chain :capture, :parent
+    module WidgetExtensions
+      def self.included(base)
+        base.alias_method_chain :output, :parent
+        base.alias_method_chain :capture, :parent
+      end
 
-    # This is here to force #parent.capture to return the output
-    def __in_erb_template; end
+      def output_with_parent
+        if parent.respond_to?(:output_buffer)
+          parent.output_buffer.is_a?(String) ? parent.output_buffer : handle_rjs_buffer
+        else
+          output_without_parent
+        end
+      end
 
-    private
+      def capture_with_parent(&block)
+        parent ? raw(parent.capture(&block).to_s) : capture_without_parent(&block)
+      end
 
-    def process_output_buffer
-      if parent.respond_to?(:output_buffer)
-        parent.output_buffer.is_a?(String) ? parent.output_buffer : handle_rjs_buffer
-      else
-        nil
+      # This is here to force #parent.capture to return the output
+      def __in_erb_template;
       end
-    end
 
-    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
+      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/extensions/rails_widget/rails_helpers.rb

@@ -1,6 +1,6 @@
 module Erector
-  class RailsWidget < Widget
-    module RailsHelpers
+  module Rails
+    module Helpers
       include ActionController::UrlWriter
 
       # parent returning raw text whose first parameter is HTML escaped
@@ -131,6 +131,7 @@ module Erector
         parent.pluralize(*args)
       end
     end
-    include RailsHelpers
+
+    Erector::Widget.send :include, Helpers
   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::RailsWidget.inline do",
+          "r =::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,46 +1,11 @@
-module ActionView #:nodoc:
-  module TemplateHandlers #:nodoc:
-    class RbHandler < TemplateHandler
-      include Compilable
-      def self.line_offset
-        2
-      end
-
-      ActionView::Template.instance_eval do
-        register_template_handler :rb, ActionView::TemplateHandlers::RbHandler
-      end
-
-      def compile(template)
-        relative_path_parts = template.path.split('/')
-
-        is_partial = relative_path_parts.last =~ /^_/
-        require_dependency File.expand_path(template.filename)
-
-        widget_class_parts = relative_path_parts.inject(['Views']) do |class_parts, node|
-          class_parts << node.gsub(/^_/, "").gsub(/(\.html)?\.rb$/, '').camelize
-          class_parts
-        end
-        widget_class_name = widget_class_parts.join("::")
-        render_method = is_partial ? 'render_partial' : 'content'
-
-        erb_template = <<-ERB
-        <%
-          assigns = instance_variables.inject({}) do |hash, name|
-            hash[name.sub('@', "")] = instance_variable_get(name)
-            hash
-          end
-
-          widget = #{widget_class_name}.new(assigns)
-          widget.to_s(:output => output_buffer, :helpers => self, :content_method_name => :#{render_method})
-        %>
-        ERB
-        ::ERB.new(
-          erb_template,
-          nil,
-          ::ActionView::TemplateHandlers::ERB.erb_trim_mode,
-          "@output_buffer"
-        ).src
-      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)
     end
   end
 end
+
+ActionView::Template.register_template_handler :rb, Erector::RbHandler

data/lib/erector/widget.rb

@@ -49,24 +49,47 @@ module Erector
       # Tags which can contain other stuff. Click "[Source]" to see the full list.
       def full_tags
         [
-          'a', 'abbr', 'acronym', 'address', 
+          'a', 'abbr', 'acronym', 'address', 'article', 'aside', 'audio',
           'b', 'bdo', 'big', 'blockquote', 'body', 'button', 
-          'caption', 'center', 'cite', 'code', 'colgroup',
-          'dd', 'del', 'dfn', 'div', 'dl', 'dt', 'em',
-          'embed',
-          'fieldset', 'form', 'frameset',
-          'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'html', 'i',
-          'iframe', 'ins', 'kbd', 'label', 'legend', 'li', 'map',
-          'noframes', 'noscript', 
-          'object', 'ol', 'optgroup', 'option', 'p', 'param', 'pre',
-          'q', 's',
-          'samp', 'script', 'select', 'small', 'span', 'strike',
+          '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', 'title', 'tr', 'tt', 'u', 'ul', 'var'
+          '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
@@ -139,6 +162,14 @@ module Erector
       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
     @@prettyprint_default = false
     def prettyprint_default
@@ -160,6 +191,7 @@ module Erector
 
     attr_reader *RESERVED_INSTANCE_VARS
     attr_reader :parent
+    attr_writer :block
     
     def initialize(assigns={}, &block)
       unless assigns.is_a? Hash
@@ -178,12 +210,14 @@ module Erector
 #++
 
     protected
-    def context(output, prettyprint = false, indentation = 0, helpers = nil)
+    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
@@ -192,6 +226,7 @@ module Erector
       @prettyprint = prettyprint
       yield
     ensure
+      @parent = original_parent
       @output = original_output
       @indentation = original_indendation
       @helpers = original_helpers
@@ -200,7 +235,7 @@ module Erector
 
     public
     def assign_instance_variables (instance_variables)
-      needed = self.class.get_needs.map{|need| need.is_a?(Hash) ? need.keys : need}.flatten
+      needed = self.class.get_needed_variables
       assigned = []
       instance_variables.each do |name, value|
         unless needed.empty? || needed.include?(name)
@@ -211,7 +246,7 @@ module Erector
       end
 
       # set variables with default values
-      self.class.get_needs.select{|var| var.is_a? Hash}.each do |hash|
+      self.class.get_needed_defaults.each do |hash|
         hash.each_pair do |name, value|
           unless assigned.include?(name)
             assign_instance_variable(name, value)
@@ -239,6 +274,11 @@ module Erector
     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(/<[^>]*>/, ''))
+    end
 
     # Entry point for rendering a widget (and all its children). This method
     # creates a new output string (if necessary), calls this widget's #content
@@ -275,9 +315,10 @@ module Erector
         :prettyprint => prettyprint_default,
         :indentation => 0,
         :helpers => nil,
+        :parent => @parent,
         :content_method_name => :content,
       }.merge(options)
-      context(options[:output], options[:prettyprint], options[:indentation], options[:helpers]) do
+      context(options[:parent], options[:output], options[:prettyprint], options[:indentation], options[:helpers]) do
         send(options[:content_method_name], &blk)
         output
       end
@@ -286,13 +327,27 @@ module Erector
     # 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
-    # +content+) then your widget will render any block that was passed into
-    # its constructor. If you want this block to have access to Erector methods
-    # then see Erector::Inline#content or Erector#inline.
+    # +content+, or explicitly call "call_block") then your widget will
+    # execute the block that was passed into its constructor. The semantics of
+    # this block are confusing; make sure to read the rdoc for Erector#call_block
     def content
-      if @block
-        @block.call
-      end
+      call_block
+    end
+    
+    # When this method is executed, the default block that was passed in to 
+    # the widget's constructor will be executed. The semantics of this 
+    # block -- that is, what "self" is, and whether it has access to
+    # Erector methods like "div" and "text", and the widget's instance
+    # variables -- can be quite confusing. The rule is, most of the time the
+    # block is evaluated using "call" or "yield", which means that its scope
+    # is that of the caller. So if that caller is not an Erector widget, it
+    # will *not* have access to the Erector methods, but it *will* have access 
+    # to instance variables and methods of the calling object.
+    #   
+    # 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+
@@ -301,8 +356,7 @@ module Erector
     # which gives better performance than using +capture+ or +to_s+. You can
     # also use the +widget+ method.
     def write_via(parent)
-      @parent = parent
-      context(parent.output, parent.prettyprint, parent.indentation, parent.helpers) do
+      context(parent, parent.output, parent.prettyprint, parent.indentation, parent.helpers) do
         content
       end
     end
@@ -311,10 +365,8 @@ module Erector
     # either a class or an instance. If the first argument is a class, then
     # the second argument is a hash used to populate its instance variables.
     # If the first argument is an instance then the hash must be unspecified
-    # (or empty).
-    #
-    # The sub-widget will have access to the methods of the parent class, via
-    # some method_missing magic and a "parent" pointer.
+    # (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)
@@ -322,6 +374,7 @@ module Erector
         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)
@@ -354,9 +407,14 @@ module Erector
     # how elegant it is? Not confusing at all if you don't think about it.
     #
     def element(*args, &block)
-      __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).
     #
@@ -409,10 +467,12 @@ module Erector
     end
 
     # Emits text which will *not* be HTML-escaped. Same effect as text(raw(s))
-    def rawtext(value)
+    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
@@ -443,7 +503,7 @@ module Erector
 
       output <<("</#{tag_name}>")
 
-      if newliney(tag_name)
+      if newliney?(tag_name)
         _newline
       end
     end
@@ -467,17 +527,36 @@ module Erector
       output << "<?xml#{format_sorted(sort_for_xml_declaration(attributes))}?>"
     end
 
-    # Emits an HTML comment, which looks like this: &lt;!--foo--&gt;
+    # 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)
+    def comment(text = '', &block)
       puts "Warning: Authors should avoid putting two or more adjacent hyphens inside comments." if text =~ /--/
-      output << "<!--#{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 emits it as raw text. If at all possible
+    # 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)
@@ -492,23 +571,11 @@ module Erector
     end
 
     full_tags.each do |tag_name|
-      self.class_eval(
-        "def #{tag_name}(*args, &block)\n" <<
-        "  __element__('#{tag_name}', *args, &block)\n" <<
-        "end",
-        __FILE__,
-        __LINE__ - 4
-      )
+      def_full_tag_method(tag_name)
     end
 
     empty_tags.each do |tag_name|
-      self.class_eval(
-        "def #{tag_name}(*args, &block)\n" <<
-        "  __empty_element__('#{tag_name}', *args, &block)\n" <<
-        "end",
-        __FILE__,
-        __LINE__ - 4
-      )
+      def_empty_tag_method(tag_name)
     end
 
     # Emits a javascript block inside a +script+ tag, wrapped in CDATA
@@ -556,23 +623,21 @@ module Erector
     # 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)
-      link :rel => 'stylesheet', :type => 'text/css', :href => href
+    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)
-      a href, :href => href
+    def url(href, options = {})
+      a href, ({:href => href}.merge(options))
     end
 
-    def newliney(tag_name)
-      if @prettyprint
-        !NON_NEWLINEY.include?(tag_name)
-      else
-        false
-      end
-    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)
@@ -584,7 +649,7 @@ module Erector
     protected
     def jquery_ready(txt)
       rawtext "\n"
-      rawtext "$(document).ready(function(){\n"
+      rawtext "jQuery(document).ready(function($){\n"
       rawtext txt
       rawtext "\n});"
     end
@@ -592,10 +657,9 @@ module Erector
 ### internal utility methods
 
 protected
-
-    def __element__(tag_name, *args, &block)
+    def __element__(raw, tag_name, *args, &block)
       if args.length > 2
-        raise ArgumentError, "Cannot accept more than three arguments"
+        raise ArgumentError, "Cannot accept more than four arguments"
       end
       attributes, value = nil, nil
       arg0 = args[0]
@@ -614,7 +678,9 @@ protected
         raise ArgumentError, "You can't pass both a block and a value to #{tag_name} -- please choose one."
       end
       if block
-        instance_eval(&block)
+        block.call
+      elsif raw
+        text! value
       else
         text value
       end
@@ -626,7 +692,7 @@ protected
 
       output << "<#{tag_name}#{format_attributes(attributes)} />"
 
-      if newliney(tag_name)
+      if newliney?(tag_name)
         _newline
       end
     end
@@ -639,7 +705,7 @@ protected
 
     def indent_for_open_tag(tag_name)
       return unless @prettyprint      
-      if !@at_start_of_line && newliney(tag_name)
+      if !@at_start_of_line && newliney?(tag_name)
         _newline
       end
       indent()
@@ -664,7 +730,9 @@ protected
       sorted.each do |key, value|
         if value
           if value.is_a?(Array)
-            value = [value].flatten.join(' ')
+            value = value.flatten
+            next if value.empty?
+            value = value.join(' ')
           end
           results << "#{key}=\"#{value.html_escape}\""
         end
@@ -689,5 +757,14 @@ protected
       end
       return stringized.sort{|a, b| b <=> a}
     end
+
+    def newliney?(tag_name)
+      if @prettyprint
+        !NON_NEWLINEY.include?(tag_name)
+      else
+        false
+      end
+    end
+
   end
 end