effigy 0.2.1 → 0.3.0

data/Rakefile

@@ -2,35 +2,25 @@ require 'rubygems'
 require 'rake'
 require 'rake/gempackagetask'
 
-require 'spec/rake/spectask'
-
 desc 'Default: run the specs and metrics.'
 task :default => [:spec, :metrics]
 
-Spec::Rake::SpecTask.new do |t|
-  t.spec_opts = ['--color', '--format', 'progress']
-  t.libs = %w(spec)
-  t.ruby_opts = ['-rrubygems']
-end
+begin
+  require 'spec/rake/spectask'
 
-task :rails_root do
-  rails_root = File.join('tmp', 'rails_root')
-  unless File.exist?(rails_root)
-    FileUtils.mkdir_p(File.dirname(rails_root))
-    command = "rails #{rails_root}"
-    output = `#{command} 2>&1`
-    if $? == 0
-      FileUtils.ln_s(FileUtils.pwd, File.join(rails_root, 'vendor', 'plugins'))
-    else
-      $stderr.puts "Command failed with status #{$?}:"
-      $stderr.puts command
-      $stderr.puts output
-    end
+  Spec::Rake::SpecTask.new do |t|
+    t.spec_opts = ['--color', '--format', 'progress']
+    t.libs = %w(spec)
+    t.ruby_opts = ['-rrubygems']
   end
-end
-
 
-task :spec => :rails_root
+  task :spec => :rails_root
+rescue LoadError => exception
+  puts "Missing dependencies for specs"
+  task :spec do
+    raise exception
+  end
+end
 
 desc "Remove build files"
 task :clean do
@@ -60,34 +50,37 @@ begin
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+  puts "Missing dependencies for jeweler"
 end
 
-begin
-  require 'reek/adapters/rake_task'
-
-  namespace :metrics do
-    desc "Run reek"
-    Reek::RakeTask.new do |t|
-      t.source_files = FileList['lib/**/*.rb', 'rails/**/*.rb']
-      t.fail_on_error = false
+namespace :metrics do
+  desc "Run reek"
+  begin
+    require 'reek/adapters/rake_task'
+    task :reek do
+      files = FileList['lib/**/*.rb', 'rails/**/*.rb'].to_a.join(' ')
+      system("reek -q #{files}")
+    end
+  rescue LoadError => exception
+    puts "Missing dependencies for metrics."
+    task :reek do
+      puts exception.inspect
     end
   end
-
-  desc "Run all metrics"
-  task :metrics => ['metrics:reek']
-rescue LoadError => e
-  puts e.inspect
-  puts "Missing dependencies for metrics."
 end
 
+desc "Run all metrics"
+task :metrics => ['metrics:reek']
+
 begin
   require 'yard'
 
   YARD::Rake::YardocTask.new do |t|
     t.files   = ['lib/**/*.rb', 'rails/**/*.rb']
   end
-rescue LoadError => e
-  puts e.inspect
+rescue LoadError => exception
   puts "Missing dependencies for yard."
+  task :yard do
+    raise exception
+  end
 end

data/TODO.textile

@@ -1,5 +1,3 @@
 * 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.1
+0.3.0

data/lib/effigy/rails.rb

@@ -3,4 +3,61 @@ require 'effigy/view'
 require 'effigy/rails/view'
 require 'effigy/rails/template_handler'
 
+module Effigy
+  # Rails-specific functionality.
+  #
+  # Effigy includes Rails generators for generating effigy view and template
+  # files within Rails projects, as well as a Rails-specific view superclass
+  # that provides functionality like assigns, layouts, and partials.
+  #
+  # Example:
+  #
+  # <pre>
+  # # app/controllers/magic_controller.rb
+  # class MagicController < ApplicationController
+  #   def index
+  #     @spell = 'hocus pocus'
+  #   end
+  # end
+  # </pre>
+  #
+  # <pre>
+  # # app/views/magic/index.html.effigy
+  # class MagicIndexView < Effigy::Rails::View
+  #   def transform
+  #     text('h1', @spell)
+  #   end
+  # end
+  # </pre>
+  #
+  # <pre>
+  # # app/templates/magic/index.html
+  # <h1>Spell name goes here</h1>
+  # </pre>
+  #
+  # View this example in your browser and you'll see "hocus pocus."
+  #
+  # == Generators
+  #
+  # Example:
+  #   ./script/generate effigy_view users new edit index
+  #
+  # This will generate Effigy views and templates for the "new," "edit," and
+  # "index," actions of UsersController, such as
+  # app/views/users/new.html.effigy, and app/templates/users/new.html.
+  #
+  # == Rendering Effigy views from Rails
+  #
+  # Effigy includes a Rails template handler, so you can render effigy views as normal.
+  # Rendering the "index" action from "UsersController" will look for a
+  # UsersIndexView class in app/views/users/index.html.effigy, and use it to
+  # transform app/templates/users/index.html.
+  #
+  # == Effigy Rails views
+  #
+  # See {Effigy::Rails::View} for extra methods available to Rails views.
+  module Rails
+  end
+end
+
 ActionView::Template.register_template_handler :effigy, Effigy::Rails::TemplateHandler

data/lib/effigy/rails/template_handler.rb

@@ -1,8 +1,24 @@
 module Effigy
   module Rails
+    # Adds hooks to Rails to discover Effigy views and templates.
+    #
+    # View files should be added to the app/views/<controller> directory with
+    # an .effigy suffix. Template files should be added to
+    # app/templates/<controller> with no suffix.
+    #
+    # For example, the view and template for PostsController#new would be
+    # app/views/posts/new.html.effigy and app/templates/posts/new.html,
+    # respectively.
+    #
+    # You can use the packaged generators to create these files.
+    #
+    # See {Effigy::Rails} for more information about generators.
     class TemplateHandler < ActionView::TemplateHandler
       include ActionView::TemplateHandlers::Compilable
 
+      # Compiles the given view. Calls by ActionView when loading the view.
+      # @return [String] Ruby code that can be evaluated to get the rendered
+      #   contents of this view
       def compile(view)
         @view = view
         load_view_class
@@ -13,28 +29,73 @@ module Effigy
             assigns = variables.inject({}) do |hash, name|
               hash.update(name => @controller.instance_variable_get(name))
             end
+            local_assigns.each do |name, value|
+              assigns.update("@\#{name}" => value)
+            end
           end
-          view = #{view_class_name}.new(assigns) { |*names| yield(*names) }
+          view = #{view_class_name}.new(self, assigns) { |*names| yield(*names) }
           view.render(#{template_source.inspect})
         RUBY
       end
 
+      # @return [String] the name of the view, such as "index"
       def view_name
         @view.name
       end
 
+      # @return [String] the path from the view root to the view file. For
+      #   example, "RAILS_ROOT/app/views/users/index.html.effigy" would be
+      #   "users."
       def base_path
         @view.base_path
       end
 
+      # Loads the view class from the discovered view file. View classes should
+      # be named after the controller and action, such as UsersIndexView.
+      #
+      # See {#view_class_name} for more information about class names.
       def load_view_class
         load(@view.filename)
       end
 
+      # Generates a class name for this view. Normal views are prefixed with
+      # the controller namd and suffixed with "View," such as "PostsEditView"
+      # for app/views/posts/edit.html.effigy. Partials are prefixed with the
+      # controller and suffixed with "Partial," such as "PostsPostPartial" for
+      # app/views/posts/_post.html.effigy. Layouts are suffixed with "Layout,"
+      # such as "ApplicationLayout" for
+      # app/views/layouts/application.html.effigy.
       def view_class_name
-        [base_path, view_name, 'view'].join('_').camelize
+        view_class_components.join('_').camelize.sub(/^Layouts/, '')
+      end
+
+      # @return [Array] the components that make up the class name for this view
+      def view_class_components
+        [base_path, view_name.sub(/^_/, ''), view_class_suffix]
+      end
+
+      # @return [String] the suffix for this view based on the type of view
+      def view_class_suffix
+        if layout?
+          'layout'
+        elsif partial?
+          'partial'
+        else
+          'view'
+        end
+      end
+
+      # @return [Boolean] true-ish if this view is a layout, false-ish otherwise
+      def layout?
+        base_path =~ /^layouts/
+      end
+
+      # @return [Boolean] true-ish if this view is a partial, false-ish otherwise
+      def partial?
+        @view.name =~ /^_/
       end
 
+      # @return [String] the contents of the template file for this view
       def template_source
         template_path = @view.load_path.path.sub(/\/views$/, '/templates')
         template_file_name = File.join(template_path, base_path, "#{view_name}.#{@view.format}")

data/lib/effigy/rails/view.rb

@@ -1,15 +1,52 @@
 module Effigy
   module Rails
+    # Provides Rails-specific methods to Effigy views. Rather than
+    # instantiating this class directly, it is recommended that you create view
+    # and template files and allow {Effigy::Rails::TemplateHandler} to discover
+    # and compile views.
+    #
+    # Instance variables from controller actions will be copied to the view.
     class View < ::Effigy::View
-      def initialize(assigns, &layout_block)
+
+      # [ActionView::Base] the instance that is rendering this view. This
+      #   instance is used to render partials and access other information about
+      #   the action being rendered.
+      attr_reader :action_view
+
+      # The passed block will be called to access content captured by
+      # content_for, such as layout contents.
+      #
+      # @param [ActionView::Base] action_view the instance that is rendering
+      #   this view. See the action_view attribute.
+      # @param [Hash] assigns a hash of instance variables to be copied. Names
+      #   should include the "@" prefix.
+      def initialize(action_view, assigns, &layout_block)
+
+        @action_view = action_view
         assigns.each do |name, value|
           instance_variable_set(name, value)
         end
         @layout_block = layout_block
       end
 
-      protected
+      # Renders the given partial and returns the generated markup.
+      #
+      # @param [String] name the name of the partial to render, as given to
+      #   ActionView::Base#render
+      # @param [Hash] options
+      # @option options [Hash] :locals a hash of extra variables to be assigned
+      #   on the partial view
+      # @return [String] the rendered contents from the partial
+      def partial(name, options = {})
+        options[:partial] = name
+        action_view.render(options)
+      end
 
+      # Returns the captured content of the given name. Use "layout" as a name
+      # to access the contents for the layout.
+      #
+      # @param [Symbol] capture the name of the captured content to return
+      # @return [String] the captured content of the given name
       def content_for(capture)
         @layout_block.call(capture)
       end

data/spec/effigy/rails/template_handler_spec.rb

@@ -8,10 +8,42 @@ require 'nokogiri'
 describe "a controller with an effigy view and template" do
   before do
     @files = []
+  end
+
+  after do
+    @files.each do |file|
+      FileUtils.rm(file)
+    end
+  end
+
+  def create_rails_file(relative_path, contents)
+    absolute_path = File.join(RAILS_ROOT, relative_path)
+    FileUtils.mkdir_p(File.dirname(absolute_path))
+    File.open(absolute_path, 'w') { |file| file.write(contents) }
+    @files << absolute_path
+    absolute_path
+  end
+
+  def create_rails_source_file(relative_path, contents)
+    load create_rails_file(relative_path, contents)
+  end
+
+  def render(controller, action = :index)
+    @controller = controller
+    class << @controller
+      include ActionController::TestCase::RaiseActionExceptions
+    end
+    @request  ||= ActionController::TestRequest.new
+    @response ||= ActionController::TestResponse.new
+    get :index
+    @response
+  end
+
+  include ActionController::TestProcess
+
+  it "should use the view to render the template" do
     create_rails_source_file 'app/controllers/magic_controller.rb', <<-RUBY
       class MagicController < ApplicationController
-        layout 'application'
-        include ActionController::TestCase::RaiseActionExceptions
         def index
           @spell = 'hocus pocus'
           render
@@ -31,8 +63,32 @@ describe "a controller with an effigy view and template" do
       <h1 class="success">placeholder title</h1>
     HTML
 
+    response = render(MagicController.new)
+
+    response.should be_success
+    response.rendered[:template].to_s.should == 'magic/index.html.effigy'
+    assigns(:spell).should_not be_nil
+    response.body.should have_selector('h1.success', :contents => assigns(:spell))
+  end
+
+  it "should render an effigy layout" do
+    create_rails_source_file 'app/controllers/magic_controller.rb', <<-RUBY
+      class MagicController < ApplicationController
+        layout 'application'
+      end
+    RUBY
+
+    create_rails_file 'app/views/magic/index.html.effigy', <<-RUBY
+      class MagicIndexView < Effigy::Rails::View
+      end
+    RUBY
+
+    create_rails_file 'app/templates/magic/index.html', <<-HTML
+      <h1 class="success">title</h1>
+    HTML
+
     create_rails_file 'app/views/layouts/application.html.effigy', <<-RUBY
-      class LayoutsApplicationView < Effigy::Rails::View
+      class ApplicationLayout < Effigy::Rails::View
         def transform
           html('body', content_for(:layout))
         end
@@ -43,47 +99,48 @@ describe "a controller with an effigy view and template" do
       <html><body></body></html>
     HTML
 
-    @controller = MagicController.new
-    @request    = ActionController::TestRequest.new
-    @response   = ActionController::TestResponse.new
-  end
+    response = render(MagicController.new)
 
-  after do
-    @files.each do |file|
-      FileUtils.rm(file)
-    end
+    response.should be_success
+    response.body.should have_selector('html body h1.success')
   end
 
-  def create_rails_file(relative_path, contents)
-    absolute_path = File.join(RAILS_ROOT, relative_path)
-    FileUtils.mkdir_p(File.dirname(absolute_path))
-    File.open(absolute_path, 'w') { |file| file.write(contents) }
-    @files << absolute_path
-    absolute_path
-  end
+  it "should render an effigy partial" do
+    create_rails_source_file 'app/controllers/magic_controller.rb', <<-RUBY
+      class WandController < ApplicationController
+      end
+    RUBY
 
-  def create_rails_source_file(relative_path, contents)
-    load create_rails_file(relative_path, contents)
-  end
+    create_rails_file 'app/views/wand/index.html.effigy', <<-RUBY
+      class WandIndexView < Effigy::Rails::View
+        def transform
+          replace_with('p', partial('spell', :locals  => { :name => 'hocus pocus' }))
+        end
+      end
+    RUBY
 
-  def render
-    get :index
-  end
+    create_rails_file 'app/templates/wand/index.html', <<-HTML
+      <html><body>
+        <h1 class="success">spell</h1>
+        <p>placeholder</p>
+      </body></html>
+    HTML
 
-  include ActionController::TestProcess
+    create_rails_file 'app/views/wand/_spell.html.effigy', <<-RUBY
+      class WandSpellPartial < Effigy::Rails::View
+        def transform
+          text('p', @name)
+        end
+      end
+    RUBY
 
-  it "should use the view to render the template" do
-    render
-    @response.should be_success
-    @response.rendered[:template].to_s.should == 'magic/index.html.effigy'
-    assigns(:spell).should_not be_nil
-    @response.body.should have_selector('h1.success', :contents => assigns(:spell))
-  end
+    create_rails_file 'app/templates/wand/_spell.html', <<-HTML
+      <p>put a spell on me</p>
+    HTML
 
-  it "should render an effigy layout" do
-    render
+    response = render(WandController.new)
 
-    @response.should be_success
-    @response.body.should have_selector('html body h1.success')
+    response.should be_success
+    response.body.should have_selector('html body p', :contents => 'hocus pocus')
   end
 end

data/spec/rails/generators/effigy_view_spec.rb

@@ -1,18 +1,44 @@
 require 'spec_helper'
 
-describe "script/generate effigy_view users create" do
-  before do
-    @controller_name = 'users'
-    @view_name = 'create'
-    @view_class_name = 'UsersCreateView'
+module TemplateMatchers
+  def contain(expected_text)
+    simple_matcher("contain the following lines:\n#{expected_text}") do |path, matcher|
+      if File.exist?(path)
+        actual_text = IO.read(path)
+        if actual_text.include?(expected_text)
+          true
+        else
+          matcher.failure_message =
+            "Expected to get the following text:\n#{expected_text}\nBut got:\n#{actual_text}"
+          false
+        end
+      else
+        matcher.failure_message = "File does not exist"
+        false
+      end
+    end
+  end
+
+  def rails_command(command)
     FileUtils.cd RAILS_ROOT do
-      command = "script/generate effigy_view --backtrace #{@controller_name} #{@view_name} 2>&1"
-      output = `#{command}`
+      output = `#{command} 2>&1`
       unless $? == 0
         violated "Command failed: #{command}\n#{output}"
       end
     end
   end
+end
+
+describe "script/generate effigy_view users create" do
+
+  include TemplateMatchers
+
+  before do
+    @controller_name = 'users'
+    @view_name = 'create'
+    @view_class_name = 'UsersCreateView'
+    rails_command "script/generate effigy_view --backtrace #{@controller_name} #{@view_name} 2>&1"
+  end
 
   after do
     FileUtils.rm_f(view_path)
@@ -49,22 +75,55 @@ describe "script/generate effigy_view users create" do
     File.join('app', 'templates', @controller_name, "#{@view_name}.html")
   end
 
-  def contain(expected_text)
-    simple_matcher("contain the following lines:\n#{expected_text}") do |path, matcher|
-      if File.exist?(path)
-        actual_text = IO.read(path)
-        if actual_text.include?(expected_text)
-          true
-        else
-          matcher.failure_message =
-            "Expected to get the following text:\n#{expected_text}\nBut got:\n#{actual_text}"
-          false
-        end
-      else
-        matcher.failure_message = "File does not exist"
-        false
-      end
-    end
+end
+
+describe "script/generate effigy_view layouts narrow" do
+
+  include TemplateMatchers
+
+  before do
+    @layout_name = 'narrow'
+    @layout_class_name = 'NarrowLayout'
+    rails_command "script/generate effigy_view --backtrace layouts #{@layout_name} 2>&1"
+  end
+
+  after do
+    FileUtils.rm_f(view_path)
+    FileUtils.rm_f(template_path)
+  end
+
+  it "should create a view file" do
+    view_path.should contain("class #{@layout_class_name} < Rails::Effigy::View")
+    view_path.should contain("private")
+    view_path.should contain("def transform")
+    view_path.should contain("html('body', content_for(:layout))")
+    view_path.should contain(relative_template_path)
+    view_path.should contain("end\nend")
+  end
+
+  it "should create a template file" do
+    template_path.should contain("<html>")
+    template_path.should contain("<body>")
+    template_path.should contain("<p>Edit me at #{relative_template_path}</p>")
+    template_path.should contain("<p>Edit my view at #{relative_view_path}</p>")
+    template_path.should contain("</body>")
+    template_path.should contain("</html>")
+  end
+
+  def view_path
+    File.join(RAILS_ROOT, relative_view_path)
+  end
+
+  def relative_view_path
+    File.join('app', 'views', 'layouts', "#{@layout_name}.html.effigy")
+  end
+
+  def template_path
+    File.join(RAILS_ROOT, relative_template_path)
+  end
+
+  def relative_template_path
+    File.join('app', 'templates', 'layouts', "#{@layout_name}.html")
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: effigy
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors: 
 - Joe Ferris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-04 00:00:00 -05:00
+date: 2009-12-01 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency