erector-rails4 0.0.1

data/lib/erector/html.rb

@@ -0,0 +1,12 @@
+require "erector/element"
+require "erector/attributes"
+require "erector/promise"
+require "erector/text"
+require "erector/tag"
+
+module Erector
+  module HTML
+
+
+  end
+end

data/lib/erector/html_widget.rb

@@ -0,0 +1,220 @@
+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
+
+    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', :inline
+    tag 'acronym', :inline
+    tag 'address'
+    tag 'article'
+    tag 'aside'
+    tag 'audio'
+
+    tag 'b', :inline
+    tag 'bdo', :inline
+    tag 'big', :inline
+    tag 'blockquote'
+    tag 'body'
+    tag 'button', :inline
+
+    tag 'canvas'
+    tag 'caption', :inline
+    tag 'center'
+    tag 'cite', :inline
+    tag 'code', :inline
+    tag 'colgroup'
+    tag 'command'
+
+    tag 'datalist'
+    tag 'dd'
+    tag 'del'
+    tag 'details'
+    tag 'dfn', :inline
+    tag 'dialog'
+    tag 'div'
+    tag 'dl'
+    tag 'dt', :inline
+
+    tag 'em', :inline
+
+    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', :inline
+    tag 'label', :inline
+    tag 'legend', :inline
+    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', :inline
+    tag 'ruby'
+    tag 'rt'
+    tag 'rp'
+    tag 's'
+
+    tag 'samp', :inline
+    tag 'script'
+    tag 'section'
+    tag 'select', :inline
+    tag 'small', :inline
+    tag 'source'
+    tag 'span', :inline
+    tag 'strike'
+
+    tag 'strong', :inline
+    tag 'style'
+    tag 'sub', :inline
+    tag 'sup', :inline
+
+    tag 'table'
+    tag 'tbody'
+    tag 'td'
+    tag 'textarea', :inline
+    tag 'tfoot'
+
+    tag 'th'
+    tag 'thead'
+    tag 'time'
+    tag 'title'
+    tag 'tr'
+    tag 'tt', :inline
+
+    tag 'u'
+    tag 'ul'
+
+    tag 'var', :inline
+    tag 'video'
+
+
+    # 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
+
+  end
+
+  public
+
+  # Alias to make it easier to spell
+  HtmlWidget = HTMLWidget
+
+end

data/lib/erector/inline.rb

@@ -0,0 +1,37 @@
+module Erector
+  def self.inline(*args, &block)
+    InlineWidget.new(*args, &block)
+  end
+  
+  module Inline
+    # 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
+    # This is part of the sub-widget/parent feature (see #widget method).
+    def method_missing(name, *args, &block)
+      if parent && parent.respond_to?(name)
+        block ||= lambda {} # captures self HERE
+        parent.send(name, *args, &block)
+      else
+        super
+      end
+    end
+  end
+
+  class InlineWidget < Widget
+    include Inline
+  end
+
+end

data/lib/erector/jquery.rb

@@ -0,0 +1,28 @@
+module Erector
+  module JQuery
+    # Emits a jQuery script, inside its own script tag, that is to be run on document ready or load.
+    #
+    # Usage (from inside a widget method):
+    # jquery "alert('hi')" :: a jquery ready handler
+    # jquery "alert('hi')", :id => 'foo' :: a jquery ready handler, with attributes in the script tag
+    # jquery :load, "alert('hi')" :: a jquery load handler
+    #
+    def jquery(*args)
+      event = if args.first.is_a? Symbol
+        args.shift
+      else
+        :ready
+      end
+      txt = args.shift
+      attributes = args.shift || {}
+
+      javascript attributes do
+        rawtext "\n"
+        rawtext "jQuery(document).#{event}(function($){\n"
+        rawtext txt
+        rawtext "\n});"
+      end
+    end
+
+  end
+end

data/lib/erector/mixin.rb

@@ -0,0 +1,12 @@
+module Erector
+  module Mixin
+    # Executes the block as if it were the content body of a fresh Erector::Inline,
+    # and returns the #to_html 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. Funnily enough, the options are passed in to both
+    # to_html *and* to the widget itself, so they show up as instance variables.
+    def erector(options = {}, &block)
+      Erector.inline(options, &block).to_html(options)
+    end
+  end
+end

data/lib/erector/needs.rb

@@ -0,0 +1,95 @@
+module Erector
+  module Needs
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # 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'.
+      #
+      # 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 just like normal. 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 needs(*args)
+        args.each do |arg|
+          (@needs ||= []) << (arg.nil? ? nil : (arg.is_a? Hash) ? arg : arg.to_sym)
+        end
+      end
+
+      def 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 needed_variables
+        @needed_variables ||= get_needs.map{|need| need.is_a?(Hash) ? need.keys : need}.flatten
+      end
+
+      def needed_defaults
+        @needed_defaults ||= get_needs.inject({}) do |defaults, need|
+          defaults = need.merge(defaults) if need.is_a? Hash
+          defaults
+        end
+      end
+
+      def needs?(name)
+        needed_variables.empty? || needed_variables.include?(name)
+      end
+    end
+
+    def initialize(assigns = {})
+      super
+
+      assigned = assigns.keys
+
+      # set variables with default values
+      self.class.needed_defaults.each do |name, value|
+        unless assigned.include?(name)
+          value = [NilClass, FalseClass, TrueClass, Fixnum, Float, Symbol].include?(value.class) ? value : value.dup
+          instance_variable_set("@#{name}", value)
+          assigned << name
+        end
+      end
+
+      missing = self.class.needed_variables - assigned
+      unless missing.empty? || missing == [nil]
+        raise ArgumentError, "Missing parameter#{missing.size == 1 ? '' : 's'} for #{self.class.name}: #{missing.join(', ')}"
+      end
+
+      excess = assigned - self.class.needed_variables
+      unless self.class.needed_variables.empty? || excess.empty?
+        raise ArgumentError, "Excess parameter#{excess.size == 1 ? '' : 's'} for #{self.class.name}: #{excess.join(', ')}"
+      end
+    end
+  end
+end

data/lib/erector/output.rb

@@ -0,0 +1,144 @@
+require 'erector/abstract_widget'
+
+module Erector
+  class Output
+    SPACES_PER_INDENT = 2
+
+    attr_reader :prettyprint, :widgets, :indentation, :max_length
+
+    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 = []
+
+      @get_buffer = if options[:buffer] and options[:buffer].respond_to? :call
+        options[:buffer]
+      elsif options[:buffer]
+        lambda { options[:buffer] }
+      else
+        buffer = []
+        lambda { buffer }
+      end
+    end
+
+    def buffer
+      @get_buffer.call
+    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
+
+        append(" " * leading_spaces)
+        need_space = false
+        words = s.split(/ /)
+        words.each do |word|
+          if (need_space ? 1 : 0) + word.length > space_left
+            append_newline
+            append_indentation
+            need_space = false
+          end
+          append(" ") if need_space
+          append(word)
+          need_space = true
+        end
+        append(" " * trailing_spaces)
+      else
+        append(s)
+      end
+      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.
+    def placeholder
+      s = ""
+      buffer << s
+      s
+    end
+
+    def to_s
+      RawString.new(buffer.kind_of?(String) ? buffer : buffer.join)
+    end
+
+    def to_a
+      buffer.kind_of?(Array) ? buffer : [buffer]
+    end
+
+    def newline
+      if prettyprint
+        append_newline
+      end
+    end
+
+    def at_line_start?
+      @current_line_length == 0
+    end
+
+    def indent
+      @indentation += 1 if prettyprint
+    end
+
+    def undent
+      @indentation -= 1 if prettyprint
+    end
+
+    # always append a newline, regardless of prettyprint setting
+    #todo: test
+    def append_newline
+      buffer << "\n"
+      @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)
+      buffer << s
+      @current_line_length += s.length
+    end
+
+    def space_left
+      @max_length - @current_line_length
+    end
+
+    def append_indentation
+      if prettyprint and at_line_start?
+        spaces = " " * ([@indentation, 0].max * SPACES_PER_INDENT)
+        buffer << spaces
+        @current_line_length += spaces.length
+      end
+    end
+
+  end
+end