erector 0.8.3 → 0.9.0.pre1

data/lib/erector/html_widget.rb

@@ -0,0 +1,300 @@
+require "erector/xml_widget"
+
+module Erector
+
+  # A Widget is the center of the Erector universe.
+  #
+  # To create a widget, extend Erector::Widget and implement the +content+
+  # method. Inside this method you may call any of the tag methods like +span+
+  # 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. 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_html+
+  # method.
+  #
+  # A widget's +new+ method optionally accepts an options hash. Entries in
+  # 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
+  # exactly what parameters are supported by a given widget, avoiding
+  # confusing runtime NilClass errors.
+  #
+  # 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_html+. It also preserves the
+  # indentation and helpers of the enclosing class.
+  #
+  # In this documentation we've tried to keep the distinction clear between
+  # methods that *emit* text and those that *return* text. "Emit" means that
+  # 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.
+  #
+  # This class extends AbstractWidget and includes several modules,
+  # so be sure to check all of those places for API documentation for the
+  # various methods of Widget:
+  #
+  # * AbstractWidget
+  # * Element
+  # * Attributes
+  # * Text
+  # * Needs
+  # * Caching
+  # * Externals
+  # * AfterInitialize
+  #
+  # * HTML
+  # * Convenience
+  # * JQuery
+  # * Sass
+  #
+  # Also read the API Cheatsheet in the user guide
+  # at http://erector.rubyforge.org/userguide#apicheatsheet
+  class HTMLWidget < Erector::XMLWidget
+
+    include Erector::HTML
+    include Erector::Convenience
+    include Erector::JQuery
+    include Erector::Sass if Object.const_defined?(:Sass)
+
+    tag 'area', :self_closing
+    tag 'base', :self_closing
+    tag 'br', :self_closing
+    tag 'col', :self_closing
+    tag 'embed', :self_closing
+    tag 'frame', :self_closing
+    tag 'hr', :self_closing
+    tag 'img', :self_closing, :inline
+    tag 'input', :self_closing, :inline
+    tag 'link', :self_closing
+    tag 'meta', :self_closing
+    tag 'param', :self_closing
+
+    tag 'a', :inline
+    tag 'abbr'
+    tag 'acronym'
+    tag 'address'
+    tag 'article'
+    tag 'aside'
+    tag 'audio'
+
+    tag 'b', :inline
+    tag 'bdo'
+    tag 'big'
+    tag 'blockquote'
+    tag 'body'
+    tag 'button', :inline
+
+    tag 'canvas'
+    tag 'caption'
+    tag 'center'
+    tag 'cite'
+    tag 'code'
+    tag 'colgroup'
+    tag 'command'
+
+    tag 'datalist'
+    tag 'dd'
+    tag 'del'
+    tag 'details'
+    tag 'dfn'
+    tag 'dialog'
+    tag 'div'
+    tag 'dl'
+    tag 'dt'
+
+    tag 'em'
+
+    tag 'fieldset'
+    tag 'figure'
+    tag 'footer'
+    tag 'form'
+    tag 'frameset'
+
+    tag 'h1'
+    tag 'h2'
+    tag 'h3'
+    tag 'h4'
+    tag 'h5'
+    tag 'h6'
+    tag 'head'
+    tag 'header'
+    tag 'hgroup'
+    tag 'html'
+    tag 'i', :inline
+
+    tag 'iframe'
+    tag 'ins'
+    tag 'keygen'
+    tag 'kbd'
+    tag 'label'
+    tag 'legend'
+    tag 'li'
+
+    tag 'map'
+    tag 'mark'
+    tag 'meter'
+
+    tag 'nav'
+    tag 'noframes'
+    tag 'noscript'
+
+    tag 'object'
+    tag 'ol'
+    tag 'optgroup'
+    tag 'option'
+
+    tag 'p'
+    tag 'pre'
+    tag 'progress'
+
+    tag 'q'
+    tag 'ruby'
+    tag 'rt'
+    tag 'rp'
+    tag 's'
+
+    tag 'samp'
+    tag 'script'
+    tag 'section'
+    tag 'select', :inline
+    tag 'small', :inline
+    tag 'source'
+    tag 'span', :inline
+    tag 'strike'
+
+    tag 'strong'
+    tag 'style'
+    tag 'sub'
+    tag 'sup'
+
+    tag 'table'
+    tag 'tbody'
+    tag 'td'
+    tag 'textarea', :inline
+    tag 'tfoot'
+
+    tag 'th'
+    tag 'thead'
+    tag 'time'
+    tag 'title'
+    tag 'tr'
+    tag 'tt'
+
+    tag 'u'
+    tag 'ul'
+
+    tag 'var'
+    tag 'video'
+
+
+    # Emits a javascript block inside a +script+ tag, wrapped in CDATA
+    # doohickeys like all the cool JS kids do.
+    def javascript(value = nil, attributes = {})
+      if value.is_a?(Hash)
+        attributes = value
+        value      = nil
+      elsif block_given? && value
+        raise ArgumentError, "You can't pass both a block and a value to javascript -- please choose one."
+      end
+
+      script(attributes.merge(:type => "text/javascript")) do
+        # 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).
+        output << raw("\n// <![CDATA[\n")
+        if block_given?
+          yield
+        else
+          output << raw(value)
+        end
+        output << raw("\n// ]]>")
+        output.append_newline # this forces a newline even if we're not in pretty mode
+      end
+
+      output << raw("\n")
+    end
+
+
+
+    # alias for AbstractWidget#render
+    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
+
+    # 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
+
+
+    # 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 << raw("<?xml#{format_sorted(sort_for_xml_declaration(attributes))}?>")
+    end
+
+    # Emits an XML/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 = '')
+      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_given?
+        rawtext "\n"
+        yield
+        rawtext "\n"
+      end
+
+      rawtext "<![endif]" if conditional
+      rawtext "-->\n"
+    end
+
+    protected
+
+    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
+      stringized.sort{|a, b| b <=> a}
+    end
+
+  end
+
+  public
+
+  # Alias to make it easier to spell
+  HtmlWidget = HTMLWidget
+
+end

data/lib/erector/inline.rb

@@ -30,7 +30,7 @@ module Erector
     end
   end
 
-  class InlineWidget < Erector::Widget
+  class InlineWidget < Widget
     include Inline
   end
 

data/lib/erector/output.rb

@@ -1,22 +1,25 @@
+require 'erector/abstract_widget'
+
 module Erector
   class Output
     SPACES_PER_INDENT = 2
 
     attr_reader :prettyprint, :widgets, :indentation, :max_length
 
-    def initialize(options = {}, & get_buffer)
-      @prettyprint = options.fetch(:prettyprint, Widget.prettyprint_default)
+    def initialize(options = {})
+      @prettyprint = options.fetch(:prettyprint, AbstractWidget.prettyprint_default)
       @indentation = options.fetch(:indentation, 0)
       @current_line_length = 0
       @max_length = options[:max_length]
       @widgets = []
-      if get_buffer
-        @get_buffer = get_buffer
-      elsif buffer = options[:output]
-        @get_buffer = lambda { buffer }
+
+      @get_buffer = if options[:buffer] and options[:buffer].respond_to? :call
+        options[:buffer]
+      elsif options[:buffer]
+        lambda { options[:buffer] }
       else
         buffer = []
-        @get_buffer = lambda { buffer }
+        lambda { buffer }
       end
     end
 
@@ -25,11 +28,13 @@ module Erector
     end
 
     def <<(s)
+      # raise s.inspect unless s.is_a? String
+      #
       s = s.to_s unless s.is_a? String
       append_indentation
       if @max_length && s.length + @current_line_length > @max_length
         leading_spaces = s =~ /^( +)/ ? $1.size : 0
-        trailing_spaces = s =~ /( +)$/ ? $1.size : 0 
+        trailing_spaces = s =~ /( +)$/ ? $1.size : 0
 
         append(" " * leading_spaces)
         need_space = false
@@ -51,10 +56,11 @@ module Erector
       self
     end
 
-    # Inserts a blank string into the output stream and returns a pointer to it.
-    # If the caller holds on to this pointer, she can later go back and insert text
-    # earlier in the stream. This is used for, e.g., inserting stuff inside the
-    # HEAD element that is not known until after the entire page renders.
+    # Inserts a blank string into the output stream and returns a pointer to
+    # it. If the caller holds on to this pointer, she can later go back and
+    # insert text earlier in the stream. This is used for, e.g., inserting
+    # stuff inside the HEAD element that is not known until after the entire
+    # page renders.
     def placeholder
       s = ""
       buffer << s
@@ -94,6 +100,27 @@ module Erector
       @current_line_length = 0
     end
 
+    def mark
+      @mark = buffer.size
+    end
+
+    def rewind pos = @mark
+      if buffer.kind_of?(Array)
+        buffer.slice!(pos..-1)
+      elsif (Object.const_defined?(:ActiveSupport) and
+        buffer.kind_of?(ActiveSupport::SafeBuffer))
+        # monkey patch to get around SafeBuffer's well-meaning paranoia
+        # see http://yehudakatz.com/2010/02/01/safebuffers-and-rails-3-0/
+        # and http://weblog.rubyonrails.org/2011/6/8/potential-xss-vulnerability-in-ruby-on-rails-applications
+        String.instance_method(:slice!).bind(buffer).call(pos..-1)
+      elsif buffer.kind_of?(String)
+        buffer.slice!(pos..-1)
+      else
+        raise "Don't know how to rewind a #{buffer.class}"
+      end
+
+    end
+
     protected
 
     def append(s)

data/lib/erector/promise.rb

@@ -0,0 +1,137 @@
+require "erector/attributes"
+require "erector/text"
+
+module Erector
+  class Promise
+    extend Attributes
+    extend Text
+
+    def initialize(output, tag_name, attributes = {}, self_closing = false, newliney = true, &inside_renderer)
+      raise "bad output: #{output.inspect}" unless output.is_a? Output
+      raise "forgot self-closing" unless [false, true].include? self_closing
+
+      @output = output
+
+      # todo: pointer to Tag object?
+      @tag_name = tag_name
+      @self_closing = self_closing
+      @newliney = newliney
+
+      @attributes = {}
+      _set_attributes attributes
+      @text = nil
+      @inside_renderer = inside_renderer
+      _mark
+    end
+
+    def _set_attributes attributes
+      attributes.each_pair do |k,v|
+        @attributes[k.to_s] = v
+      end
+    end
+
+    def _mark
+      @mark = @output.mark
+    end
+
+    def _rewind
+      @output.rewind @mark
+    end
+
+    def _render
+      _rewind
+      _render_open_tag
+      begin
+        _render_inside_tag
+      ensure
+        _render_close_tag
+      end
+    end
+
+    def _render_open_tag
+
+      @output.newline if !@self_closing and @newliney and !@output.at_line_start?
+
+      @output << RawString.new( "<#{@tag_name}#{Promise.format_attributes(@attributes)}")
+      if @self_closing
+        @output << RawString.new( " />")
+        @output.newline if @newliney
+      else
+        @output << RawString.new( ">")
+        @output.indent
+      end
+    end
+
+    def _render_inside_tag
+      return if @self_closing
+      if @text
+        @output << @text
+      end
+      if @inside_renderer
+        @inside_renderer.call
+      end
+    end
+
+    def _render_close_tag
+      return if @self_closing
+
+      @output.undent
+      @output<< RawString.new("</#{@tag_name}>")
+      if @newliney
+        @output.newline
+      end
+    end
+
+    def method_missing(method_name, *args, &block)
+      method_name = method_name.to_s
+      if method_name =~ /\!$/
+        id_str = method_name[0...-1]
+        raise ArgumentError, "setting id #{id_str} but id #{@attributes["id"]} already present" if @attributes["id"]
+        @attributes["id"] = id_str
+      else
+        if @attributes["class"]
+          @attributes["class"] += " "
+        else
+          @attributes["class"] = ""
+        end
+        @attributes["class"] += method_name.to_s
+      end
+
+      if block_given?
+        @inside_renderer = block
+      end
+
+      if args.last.is_a? Hash
+        attributes = args.pop
+        _set_attributes attributes
+      end
+
+      # todo: allow multiple args
+      # todo: allow promise args
+      @text = args.first
+
+      _render
+
+      self
+    end
+
+    # are these accessors necessary?
+
+    def _tag_name
+      @tag_name
+    end
+
+    def _attributes
+      @attributes
+    end
+
+    def _open_tag
+      @open_tag
+    end
+
+    def _close_tag
+      @close_tag
+    end
+
+  end
+end