effigy 0.2.0 → 0.2.1

data/README.textile

@@ -36,10 +36,10 @@ class PostView < Effigy::View
     text('h1', post.title)
     text('title', "#{post.title} - Site title")
     text('p.body', post.body)
-    replace_with_each('.comment', post.comments) do |comment|
+    replace_each('.comment', post.comments) do |comment|
       text('h2', comment.title)
       text('p', comment.summary)
-      attributes('a', :href => url_for(comment))
+      attr('a', :href => url_for(comment))
     end
     remove('#no-comments') if post.comments.empty?
   end
@@ -72,6 +72,34 @@ document = view.render(template)
 
 See the documentation for more information on available transformations.
 
+h2. Chaining
+
+If you prefer, you can select elements and then apply tranformations in a chain. The previous example could have been written like this:
+
+<pre>
+class PostView < Effigy::View
+  attr_reader :post
+
+  def initialize(post)
+    @post = post
+  end
+
+  def transform
+    find('h1').text(post.title)
+    find('title').text("#{post.title} - Site title")
+    find('p.body').text(post.body)
+    find('.comment').replace_each(post.comments) do |comment|
+      find('h2').text(comment.title)
+      find('p').text(comment.summary)
+      find('a').attr(:href => url_for(comment))
+    end
+    find('#no-comments').remove if post.comments.empty?
+  end
+end
+</pre>
+
+#find is also aliased as #f for brevity, if you're into that sort of thing.
+
 h2. Rails
 
 Effigy integrates with Rails. It provides a view subclass that copies instance variables from the controller, a template handler to find Effigy views and templates, and a generator to create skeleton view files.
@@ -103,11 +131,21 @@ end
 
 View this example in your browser and you'll see "hocus pocus."
 
+h2. Install
+
+Effigy is distributed as a gem through gemcutter:
+
+<pre>
+sudo gem install effigy -s http://gemcutter.org
+</pre>
+
+Effigy requires Nokogiri.
+
 h2. Why?
 
 Effigy is based on the idea that putting behavior in your templates is confusing and makes them difficult to maintain, and that the closer an ERB template gets to 50% Ruby, 50% HTML, the closer it gets to total chaos. Complicated views require unintuitive concepts (ERB buffers, capture blocks, etc). ERB also has the constant threat of unescaped user input slipping into a view.
 
-Effigy was created because I have never liked interpolation-based templating languages like ERB and because XSLT is a new language (and I like Ruby just fine).
+Effigy was created because I have never liked interpolation-based templating languages like ERB and because XSLT requires introducing another language (and I like Ruby just fine).
 
 h2. Author
 

data/Rakefile

@@ -55,6 +55,8 @@ begin
     gem.email   = %q{jferris@thoughtbot.com}
 
     gem.platform = Gem::Platform::RUBY
+
+    gem.add_runtime_dependency 'nokogiri'
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/TODO.textile

@@ -0,0 +1,5 @@
+* Implement more jQuery manipulation methods
+* Handle Rails layouts specially
+* Find a replacement for Rails partials
+* Include ActionView helpers that don't generate markup
+* Replace ActionView helpers taht generate markup

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/effigy.rb

@@ -1,3 +1,8 @@
 require 'effigy/view'
 require 'effigy/errors'
 
+# Namespace module for Effigy.
+#
+# See {file:README.textile the README}, {View}, or {Rails}.
+module Effigy
+end

data/lib/effigy/class_list.rb

@@ -1,17 +1,26 @@
 require 'nokogiri'
 
 module Effigy
+  # Internal use only.
+  #
+  # Used when parsing and manipulating lists of CSS class names.
   class ClassList
+    # @param element [Nokogiri::XML::Element] the element whose class names
+    #   should be manipulated
     def initialize(element)
       @element = element
       read_class_names
     end
 
+    # Appends a class name to the list.
+    # @param [String] class_name the class name to append
     def <<(class_name)
       @class_names << class_name
       write_class_names
     end
 
+    # Removes a class name from the list.
+    # @param [String] class_name the class name to remove
     def remove(class_name)
       @class_names.delete(class_name)
       write_class_names
@@ -19,10 +28,12 @@ module Effigy
 
     private
 
+    # Parses and caches the list of class names. Called after initialization.
     def read_class_names
       @class_names = (@element['class'] || '').split(' ')
     end
 
+    # Writes the transformed list of classes to the element's class attribute.
     def write_class_names
       @element['class'] = @class_names.join(' ')
     end

data/lib/effigy/core_ext/hash.rb

@@ -0,0 +1,11 @@
+# Internal use only.
+#
+# Extends Hash to easily convert a hash or key, value pair to a hash.
+class Hash
+  # @return [Hash] self
+  # @param [Object] value ignored
+  # @see Object#to_effigy_attributes
+  def to_effigy_attributes(value)
+    self
+  end
+end

data/lib/effigy/core_ext/object.rb

@@ -0,0 +1,12 @@
+# Internal use only.
+#
+# Extends Object to easily convert a hash or key, value pair to a hash.
+class Object
+  # @return [Hash] a hash composed of the object as the key and the given value
+  #   as the value.
+  # @param [Object] value the value to use in the generated hash
+  # @see Hash#to_effigy_attributes
+  def to_effigy_attributes(value)
+    { self => value }
+  end
+end

data/lib/effigy/errors.rb

@@ -1,11 +1,16 @@
 module Effigy
+  # Raised when attempting to select an element that isn't on the source
+  # template.
   class ElementNotFound < StandardError
+    # [String] The selector that didn't match any elements
     attr_accessor :selector
 
+    # @param [String] the selector that didn't match any elements
     def initialize(selector)
       @selector = selector
     end
 
+    # @return [String] a description of the failed search
     def message
       "No element matched the given selector: #{selector.inspect}"
     end

data/lib/effigy/selection.rb

@@ -0,0 +1,39 @@
+module Effigy
+  # Proxy class for performing transformations with a set selection.
+  #
+  # Selections are created and returned when calling {View#find} without a
+  # block. Any methods called on the Selection will be forwarded to the given
+  # view with the given selector inserted at the front of the argument list.
+  #
+  # All methods should return the Selection itself, so transformation methods
+  # can be chained on a selection.
+  #
+  # Normally, Selections are not instantiated directly, but by calling
+  # {View#find}.
+  #
+  # @example
+  #  view = Effigy::View.new
+  #  # same as calling view.remove_class('.active', 'inactive')
+  #  view.find('.active').remove_class('inactive')
+  class Selection
+
+    # Creates a selection over the given view using the given selector.
+    # @param view [View] the view to which transformations should be forwarded
+    # @param selector [String] the selector that should be used for forwarded
+    #   transformation methods
+    def initialize(view, selector)
+      @view     = view
+      @selector = selector
+    end
+
+    # Undefined methods are forwarded to the view with the selector inserted at
+    # the beginning of the argument list. The Selection is then returned for
+    # chaining.
+    #
+    # @return [Selection] self
+    def method_missing(method, *args, &block)
+      @view.send(method, @selector, *args, &block)
+      self
+    end
+  end
+end

data/lib/effigy/view.rb

@@ -1,21 +1,72 @@
 require 'nokogiri'
 require 'effigy/class_list'
 require 'effigy/errors'
+require 'effigy/selection'
 
 module Effigy
+  # Accepts a template to be transformed.
+  #
+  # For most common cases, creating a subclass makes the most sense, but this
+  # class can be used directly by passing a block to {#render}.
+  #
+  # @see #transform
+  # @see #render
+  # @example
+  # view = Effigy::View.new
+  # view.render(template) do
+  #   view.find('h1').text('the title')
+  # end
+  #
   class View
+    # Replaces the text content of the selected element.
+    #
+    # Markup in the given content is escaped. Use {#html} if you want to
+    # replace the contents with live markup.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [String] content the text that should be the new element contents
+    # @example
+    #   text('h1', 'a title')
+    #   find('h1').text('a title')
+    #   text('p', '<b>title</b>') # <p>&lt;b&gt;title&lt;/title&gt;</p>
     def text(selector, content)
       select(selector).content = content
     end
 
-    def attributes(selector, attributes)
+    # Adds or updates the given attribute or attributes of the selected element.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [String,Hash] attributes_or_attribute_name if a String, replaces
+    #   that attribute with the given value. If a Hash, uses the keys as
+    #   attribute names and values as attribute values
+    # @param [String] value the value for the replaced attribute. Used only if
+    #   attributes_or_attribute_name is a String
+    # @example
+    #   attr('p', :id => 'an_id', :style => 'display: none')
+    #   attr('p', :id, 'an_id')
+    #   find('p').attr(:id, 'an_id')
+    def attr(selector, attributes_or_attribute_name, value = nil)
       element = select(selector)
+      attributes = attributes_or_attribute_name.to_effigy_attributes(value)
       attributes.each do |attribute, value|
         element[attribute.to_s] = value
       end
     end
 
-    def replace_with_each(selector, collection, &block)
+    # Replaces the selected element with a clone for each item in the collection.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [Enumerable] collection the items that are the base for each
+    #   cloned element
+    # @example
+    #   titles = %w(one two three)
+    #   find('.post').replace_each(titles) do |title|
+    #     text('h1', title)
+    #   end
+    def replace_each(selector, collection, &block)
       original_element = select(selector)
       collection.inject(original_element) do |sibling, item|
         item_element = clone_element_with_item(original_element, item, &block)
@@ -24,6 +75,13 @@ module Effigy
       original_element.unlink
     end
 
+    # Perform transformations on the given template.
+    #
+    # @yield inside the given block, transformation methods such as #text and
+    #   #html can be used on the template. Using a subclass, you can instead
+    #   override the #transform method, which is the preferred approach.
+    #
+    # @return [String] the resulting document
     def render(template)
       @current_context = Nokogiri::XML.parse(template)
       yield if block_given?
@@ -31,44 +89,141 @@ module Effigy
       output
     end
 
-    def context(new_context)
-      old_context = @current_context
-      @current_context = select(new_context)
-      yield
-      @current_context = old_context
-    end
-
+    # Removes the selected elements from the template.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @example
+    #   remove('.post')
+    #   find('.post').remove
     def remove(selector)
       select_all(selector).each { |element| element.unlink }
     end
 
-    def add_class_names(selector, *class_names)
+    # Adds the given class names to the selected element.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [String] class_names a CSS class name that should be added
+    # @example
+    #   add_class('a#home', 'selected')
+    #   find('a#home').add_class('selected')
+    def add_class(selector, *class_names)
       element = select(selector)
       class_list = ClassList.new(element)
       class_names.each { |class_name| class_list << class_name }
     end
 
-    def remove_class_names(selector, *class_names)
+    # Removes the given class names from the selected element.
+    #
+    # Ignores class names that are not present.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [String] class_names a CSS class name that should be removed
+    # @example
+    #   remove_class('a#home', 'selected')
+    #   find('a#home').remove_class('selected')
+    def remove_class(selector, *class_names)
       element = select(selector)
       class_list = ClassList.new(element)
       class_names.each { |class_name| class_list.remove(class_name) }
     end
 
-    def inner(selector, xml)
+    # Replaces the contents of the selected element with live markup.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [String] xml the new contents of the selected element. Markup is
+    #   not escaped.
+    # @example
+    #   html('p', '<b>Welcome!</b>')
+    #   find('p').html('<b>Welcome!</b>')
+    def html(selector, xml)
       select(selector).inner_html = xml
     end
 
-    def outer(selector, xml)
+    # Replaces the selected element with live markup.
+    #
+    # The "outer HTML" for the selected tag itself is also replaced.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @param [String] xml the new markup to replace the selected element. Markup is
+    #   not escaped.
+    def replace_with(selector, xml)
       select(selector).after(xml).unlink
     end
 
-    private
+    # Selects an element or elements for chained transformation.
+    #
+    # If given a block, the selection will be in effect during the block.
+    #
+    # If not given a block, a {Selection} will be returned on which
+    # transformation methods can be called. Any methods called on the
+    # Selection will be delegated back to the view with the selector inserted
+    # into the parameter list.
+    #
+    # @param [String] selector a CSS or XPath string describing the element to
+    #   transform
+    # @return [Selection] a proxy object on which transformation methods can be
+    #   called
+    # @example
+    #   find('.post') do
+    #     text('h1', post.title)
+    #     text('p', post.body)
+    #   end
+    #   find('h1').text(post.title).add_class('active')
+    def find(selector)
+      if block_given?
+        old_context = @current_context
+        @current_context = select(selector)
+        yield
+        @current_context = old_context
+      else
+        Selection.new(self, selector)
+      end
+    end
+    alias_method :f, :find
 
+    # Called by {#render} to perform transformations on the source template.
+    #
+    # Override this method in subclasses to perform the transformations
+    # specific to your view.
+    #
+    # @example
+    #   class PostView < Effigy::View
+    #     def initialize(post)
+    #       @post = post
+    #     end
+    #
+    #     def transform
+    #       find('.post') do
+    #         find('h2').text(post.title)
+    #         find('p').text(post.body)
+    #       end
+    #     end
+    #   end
     def transform
     end
 
+    private
+
+    # The current set of nodes on which transformations are performed.
+    #
+    # This is usually the entire document, but will be a subset of child nodes
+    # during {#find} blocks.
     attr_reader :current_context
 
+    # Returns the first node that matches the given selection, or the nodes
+    # themselves if given a set of nodes.
+    #
+    # @param nodes [String,Nokogiri::XML::NodeSet] if a String, the selector to
+    #   use when determining the current context. When a NodeSet, the set of
+    #   nodes that should be returned.
+    # @return [Nokogiri::XML::NodeSet] the nodes selected by the given selector
+    #   or node set.
+    # @raise [ElementNotFound] if no nodes match the given selector
     def select(nodes)
       if nodes.respond_to?(:search)
         nodes
@@ -78,18 +233,39 @@ module Effigy
       end
     end
 
+    # Returns a set of nodes matching the given selector.
+    #
+    # @param selector [String] the selctor to use when finding nodes
+    # @return [Nokogiri::XML::NodeSet] the nodes selected by the given selector
+    # @raise [ElementNotFound] if no nodes match the given selector
     def select_all(selector)
       result = current_context.search(selector)
       raise ElementNotFound, selector if result.empty?
       result
     end
 
+    # Clones an element, sets it as the current context, and yields to the
+    # given block with the given item.
+    #
+    # @param [Nokogiri::XML::Element] the element to clone
+    # @param [Object] item the item that should be yielded to the block
+    # @yield [Object] the item passed as item
+    # @return [Nokogiri::XML::Element] the clone of the original element
     def clone_element_with_item(original_element, item, &block)
       item_element = original_element.dup
-      context(item_element) { yield(item) }
+      find(item_element) { yield(item) }
       item_element
     end
 
+    # Converts the transformed document to a string.
+    #
+    # Called by {#render} after transforming the document using a passed block
+    # and {#transform}.
+    #
+    # Override this in subclasses if you wish to return something besides an
+    # XHTML string representation of the transformed document.
+    #
+    # @return [String] the transformed document as a string
     def output
       current_context.to_xhtml
     end

data/spec/effigy/core_ext/hash_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+require 'effigy/core_ext/hash'
+
+describe Hash do
+  it "should return itself as an attribute hash" do
+    hash = { :key => :value }
+    hash.to_effigy_attributes(nil).should == hash
+  end
+end
+

data/spec/effigy/core_ext/object_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+require 'effigy/core_ext/object'
+
+describe Object do
+  it "should return itself as the key of an effigy attribute hash" do
+    key = :key
+    value = :value
+    key.to_effigy_attributes(value).should == { key => value }
+  end
+end

data/spec/effigy/rails/template_handler_spec.rb

@@ -34,7 +34,7 @@ describe "a controller with an effigy view and template" do
     create_rails_file 'app/views/layouts/application.html.effigy', <<-RUBY
       class LayoutsApplicationView < Effigy::Rails::View
         def transform
-          inner('body', content_for(:layout))
+          html('body', content_for(:layout))
         end
       end
     RUBY

data/spec/effigy/selection_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require 'effigy/selection'
+
+module Effigy
+  describe Selection do
+    %w(text).each do |method|
+      it "should delegate #{method} to its view" do
+        view = stub('a view')
+        selector = '.findme'
+        arguments = [1, 2, 3]
+        view.should_receive(method).with(selector, *arguments)
+        selection = Selection.new(view, selector)
+        selection.send(method, *arguments)
+      end
+    end
+
+    it "should return itself after delegating" do
+      view = stub('a view')
+      view.stub!(:text)
+      selection = Selection.new(view, '.findme')
+      selection.text.should == selection
+    end
+
+    class BlockRecorder
+      attr_reader :block
+      def run(*args, &block)
+        @block = block
+      end
+    end
+
+    it "should pass blocks when delegating" do
+      view = BlockRecorder.new
+      block = lambda { 'hello' }
+      selection = Selection.new(view, '.findme')
+      selection.run(&block)
+      view.block.should == block
+    end
+  end
+end

data/spec/effigy/view_spec.rb

@@ -1,10 +1,12 @@
 require 'spec_helper'
 require 'effigy/view'
 require 'effigy/errors'
+require 'effigy/core_ext/hash'
+require 'effigy/core_ext/object'
 
 module Effigy
   describe View do
-    it "should replace element contents" do
+    it "should replace element text" do
       template = %{<test><element one="abc">something</element></test>}
 
       view = Effigy::View.new
@@ -20,18 +22,29 @@ module Effigy
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.attributes 'element', :one => '123', :two => '234'
+        view.attr 'element', :one => '123', :two => '234'
       end
 
       xml.should have_selector(:element, :contents => 'something', :one => '123', :two => '234')
     end
 
+    it "should replace one attribute" do
+      template = %{<test><element one="abc">something</element></test>}
+
+      view = Effigy::View.new
+      xml = view.render(template) do
+        view.attr 'element', :one, '123'
+      end
+
+      xml.should have_selector(:element, :contents => 'something', :one => '123')
+    end
+
     it "should replace an element with a clone for each item in a collection" do
       template = %{<test><element><value>original</value></element></test>}
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.replace_with_each('element', %w(one two)) do |value|
+        view.replace_each('element', %w(one two)) do |value|
           view.text('value', value)
         end
       end
@@ -47,7 +60,7 @@ module Effigy
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.context('element') do
+        view.find('element') do
           view.text('value', 'expected')
         end
       end
@@ -72,7 +85,7 @@ module Effigy
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.add_class_names('test', 'one', 'two')
+        view.add_class('test', 'one', 'two')
       end
 
       xml.should have_selector('test.original')
@@ -85,7 +98,7 @@ module Effigy
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.remove_class_names('test', 'one', 'two')
+        view.remove_class('test', 'one', 'two')
       end
 
       xml.should have_selector('test.three')
@@ -98,7 +111,7 @@ module Effigy
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.inner 'test', '<new>replaced</new>'
+        view.html 'test', '<new>replaced</new>'
       end
 
       xml.should have_selector('test new', :contents => 'replaced')
@@ -110,7 +123,7 @@ module Effigy
 
       view = Effigy::View.new
       xml = view.render(template) do
-        view.outer 'test', '<new>replaced</new>'
+        view.replace_with 'test', '<new>replaced</new>'
       end
 
       xml.should have_selector('new', :contents => 'replaced')
@@ -120,7 +133,20 @@ module Effigy
     it "should render xhtml by default" do
       template = %{<html/>}
       xml = Effigy::View.new.render(template)
-      xml.should_not include('xml')
+      xml.should_not include('<?xml')
+    end
+
+    %w(find f).each do |chain_method|
+      it "should allow chains using #{chain_method}" do
+        template = %{<test><element one="abc">something</element></test>}
+
+        view = Effigy::View.new
+        xml = view.render(template) do
+          view.send(chain_method, 'element').text('expected')
+        end
+
+        xml.should have_selector(:element, :contents => 'expected', :one => 'abc')
+      end
     end
 
     describe "given a template without .find" do
@@ -136,12 +162,12 @@ module Effigy
       end
 
       it "should raise when updating attributes for .find" do
-        render { |view| view.attributes('.find', :attr => 'value') }.
+        render { |view| view.attr('.find', :attr => 'value') }.
           should raise_error(Effigy::ElementNotFound)
       end
 
       it "should raise when replacing an element matching .find" do
-        render { |view| view.replace_with_each('.find', []) }.
+        render { |view| view.replace_each('.find', []) }.
           should raise_error(Effigy::ElementNotFound)
       end
 
@@ -151,7 +177,7 @@ module Effigy
       end
 
       it "should raise when setting the context to .find" do
-        render { |view| view.context('.find') }.
+        render { |view| view.find('.find') {} }.
           should raise_error(Effigy::ElementNotFound)
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: effigy
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Joe Ferris
@@ -9,10 +9,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-03 00:00:00 -05:00
+date: 2009-11-04 00:00:00 -05:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
 description: Define views in Ruby and templates in HTML. Avoid code interpolation or ugly templating languages. Use ids, class names, and semantic structures already present in your documents to produce content.
 email: jferris@thoughtbot.com
 executables: []
@@ -26,17 +35,24 @@ files:
 - LICENSE
 - README.textile
 - Rakefile
+- TODO.textile
 - VERSION
 - lib/effigy.rb
 - lib/effigy/class_list.rb
+- lib/effigy/core_ext/hash.rb
+- lib/effigy/core_ext/object.rb
 - lib/effigy/errors.rb
 - lib/effigy/rails.rb
 - lib/effigy/rails/template_handler.rb
 - lib/effigy/rails/view.rb
+- lib/effigy/selection.rb
 - lib/effigy/view.rb
 - spec/effigy/class_list_spec.rb
+- spec/effigy/core_ext/hash_spec.rb
+- spec/effigy/core_ext/object_spec.rb
 - spec/effigy/errors_spec.rb
 - spec/effigy/rails/template_handler_spec.rb
+- spec/effigy/selection_spec.rb
 - spec/effigy/view_spec.rb
 - spec/rails/generators/effigy_view_spec.rb
 - spec/spec_helper.rb
@@ -71,7 +87,10 @@ specification_version: 3
 summary: Effigy provides a view and template framework without a templating language.
 test_files: 
 - spec/effigy/class_list_spec.rb
+- spec/effigy/core_ext/hash_spec.rb
+- spec/effigy/core_ext/object_spec.rb
 - spec/effigy/errors_spec.rb
 - spec/effigy/rails/template_handler_spec.rb
+- spec/effigy/selection_spec.rb
 - spec/effigy/view_spec.rb
 - spec/rails/generators/effigy_view_spec.rb