deface 0.7.0 → 0.7.1

data/README.markdown

@@ -12,12 +12,26 @@ Deface is a library that allows you to customize HTML ERB views in a Rails appli
 It allows you to easily target html & erb elements as the hooks for customization using CSS selectors as supported by Nokogiri.
 
 Demo & Testing
----------------
+--------------
 You can play with Deface and see its parsing in action at [deface.heroku.com](http://deface.heroku.com)
 
 
+Production & Precompiling
+------------------------
+
+Deface now supports precompiling where all overrides are loaded and applied to the original views and the resulting templates are then saved to your application's `app/compiled_views` directory. To precompile run:
+
+     bundle exec rake deface:precompile
+
+It's important to disable Deface once precompiling is used to prevent overrides getting applied twice. To disable add the following line to your application's `production.rb` file:
+
+     config.deface.enabled = false
+
+NOTE: You can also use precompiling in development mode.
+
+
 Deface::Override
-=======
+================
 
 A new instance of the Deface::Override class is initialized for each customization you wish to define. When initializing a new override you must supply only one Target, Action & Source parameter and any number of Optional parameters. Note: the source parameter is not required when the "remove" action is specified.
 
@@ -31,6 +45,12 @@ Action
 
 * <tt>:replace</tt> - Replaces all elements that match the supplied selector
 
+* <tt>:replace_contents</tt> - Replaces the contents of all elements that match the supplied selector
+
+* <tt>:surround</tt> - Surrounds all elements that match the supplied selector, expects replacement markup to contain <%= render_original %> placeholder
+
+* <tt>:surround_contents</tt> - Surrounds the contents of all elements that match the supplied selector, expects replacement markup to contain <%= render_original %> placeholder
+
 * <tt>:insert_after</tt> - Inserts after all elements that match the supplied selector
 
 * <tt>:insert_before</tt> - Inserts before all elements that match the supplied selector
@@ -72,7 +92,7 @@ Optional
 Examples
 ========
 
-Replaces all instances of _h1_ in the `posts/_form.html.erb` partial with `<h1>New Post</h1>`
+Replaces all instances of `h1` in the `posts/_form.html.erb` partial with `<h1>New Post</h1>`
 
      Deface::Override.new(:virtual_path => "posts/_form", 
                           :name => "example-1", 
@@ -100,6 +120,13 @@ Removes any ERB block containing the string `helper_method` in the `posts/new.ht
                           :remove => "code[erb-loud]:contains('helper_method')",
                           :original => "<%= helper_method %>")
 
+Wraps the `div` with id of `products` in ruby if statement, the <%= render_original %> in the `text` indicates where the matching content should be re-included.
+
+     Deface::Override.new(:virtual_path => "posts/new", 
+                          :name => "example-5", 
+                          :surround => "div#products",
+                          :text => "<% if @product.present? %><%= render_original %><% end %>")
+
 Sets (or adds if not present) the `class` and `title` attributes to all instances of `a` with an id of `link` in `posts/index.html.erb` 
 
     Deface::Override.new(:virtual_path => 'posts/index',
@@ -111,8 +138,8 @@ Remove an entire ERB if statement (and all it's contents) in the 'admin/products
 
     Deface::Override.new(:virtual_path => 'admin/products/index',
                          :name => "remove_if_statement",
-                         :remove => "code[:erb-silent]:contains('if @product.sold?')",
-                         :closing_selector => "code[:erb-silent]:contains('end')"
+                         :remove => "code[erb-silent]:contains('if @product.sold?')",
+                         :closing_selector => "code[erb-silent]:contains('end')"
 
 Scope
 =====
@@ -140,12 +167,16 @@ Deface includes a couple of rake tasks that can be helpful when defining or debu
 
     rake deface:get_result['admin/products/index']
 
-**deface:test_selector** - Applies a given CSS selector against a parital or template and outputs the markup for each match (if any). *test_selector* requires two arguments, the first is the virtual_path for the partial / template, the second is the CSS selector to apply:
+**deface:test_selector** - Applies a given CSS selector against a partial or template and outputs the markup for each match (if any). *test_selector* requires two arguments, the first is the virtual_path for the partial / template, the second is the CSS selector to apply:
 
     rake deface:test_selector[shared/_head,title]
 
     rake deface:test_selector['admin/products/index','div.toolbar']
 
+**deface:precompile** - Generates compiled views that contain all overrides applied. See `Production & Precompiling` section above for more.
+
+    rake deface:precompile
+
 
 Implementation
 ==============

data/deface.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "deface"
-  s.version = "0.7.0"
+  s.version = "0.7.1"
 
   s.authors = ["Brian D Quinn"]
   s.description = "Deface is a library that allows you to customize ERB views in a Rails application without editing the underlying view."
@@ -18,5 +18,5 @@ Gem::Specification.new do |s|
   s.add_dependency('nokogiri', '~> 1.5.0')
   s.add_dependency('rails', '>= 3.0.9')
 
-  s.add_development_dependency('rspec', '>= 2.6.0')
+  s.add_development_dependency('rspec', '>= 2.7.0')
 end

data/lib/deface/action_view_extensions.rb

@@ -2,7 +2,9 @@ ActionView::Template.class_eval do
   alias_method :rails_initialize, :initialize
 
   def initialize(source, identifier, handler, details)
-    source = Deface::Override.apply(source, details)
+    if Rails.application.config.deface.enabled
+      source = Deface::Override.apply(source, details)
+    end
 
     rails_initialize(source, identifier, handler, details)
   end

data/lib/deface/environment.rb

@@ -1,9 +1,10 @@
 module Deface
 
   class Environment
-    attr_accessor :overrides
+    attr_accessor :overrides, :enabled
     def initialize
       @overrides = Overrides.new
+      @enabled   = true
     end
   end
 
@@ -18,12 +19,40 @@ module Deface
       Deface::Override.find(*args)
     end
 
-      def early_check
-        Deface::Override._early.each do |args|
-          Deface::Override.new(args)
+    def load_all(app)
+      # check application for specified overrides paths
+      #
+      #
+      override_paths = app.paths["app/overrides"]
+      enumerate_and_load(override_paths, app.root)
+
+      # check all railties / engines / extensions for overrides
+      app.railties.all.each do |railtie|
+        next unless railtie.respond_to? :root
+
+        override_paths = railtie.respond_to?(:paths) ? railtie.paths["app/overrides"] : nil
+        enumerate_and_load(override_paths, railtie.root)
+      end
+    end
+
+    def early_check
+      Deface::Override._early.each do |args|
+        Deface::Override.new(args)
+      end
+
+      Deface::Override._early.clear
+    end
+
+    private 
+      def enumerate_and_load(paths, root)
+        paths ||= ["app/overrides"]
+
+        paths.each do |path|
+          Dir.glob(root.join path, "*.rb") do |c|
+            Rails.application.config.cache_classes ? require(c) : load(c)
+          end
         end
 
-        Deface::Override._early.clear
       end
   end
 end

data/lib/deface/override.rb

@@ -6,7 +6,7 @@ module Deface
     attr_accessor :args
 
     @@_early = []
-    @@actions = [:remove, :replace, :replace_contents, :insert_after, :insert_before, :insert_top, :insert_bottom, :set_attributes]
+    @@actions = [:remove, :replace, :replace_contents, :surround, :surround_contents, :insert_after, :insert_before, :insert_top, :insert_bottom, :set_attributes]
     @@sources = [:text, :partial, :template]
 
     # Initializes new override, you must supply only one Target, Action & Source
@@ -23,6 +23,8 @@ module Deface
     # * <tt>:remove</tt> - Removes all elements that match the supplied selector
     # * <tt>:replace</tt> - Replaces all elements that match the supplied selector
     # * <tt>:replace_contents</tt> - Replaces the contents of all elements that match the supplied selector
+    # * <tt>:surround</tt> - Surrounds all elements that match the supplied selector, expects replacement markup to contain <%= render_original %> placeholder
+    # * <tt>:surround_contents</tt> - Surrounds the contents of all elements that match the supplied selector, expects replacement markup to contain <%= render_original %> placeholder
     # * <tt>:insert_after</tt> - Inserts after all elements that match the supplied selector
     # * <tt>:insert_before</tt> - Inserts before all elements that match the supplied selector
     # * <tt>:insert_top</tt> - Inserts inside all elements that match the supplied selector, before all existing child
@@ -59,7 +61,7 @@ module Deface
     # * <tt>:attributes</tt> - A hash containing all the attributes to be set on the matched elements, eg: :attributes => {:class => "green", :title => "some string"}
     #
     def initialize(args)
-      unless Rails.application.try(:config).try(:deface)
+      unless Rails.application.try(:config).respond_to?(:deface) and Rails.application.try(:config).deface.try(:overrides)
         @@_early << args
         warn "[WARNING] Deface railtie has not initialized yet, override '#{args[:name]}' is being declared too early."
         return
@@ -92,6 +94,7 @@ module Deface
       else
         #initializing new override
         @args = args
+
         raise(ArgumentError, ":action is invalid") if self.action.nil?
       end
 
@@ -235,6 +238,23 @@ module Deface
                 when :replace_contents
                   match.children.remove 
                   match.add_child(override.source_element)
+                when :surround, :surround_contents
+
+                  new_source = override.source_element.clone(1)
+
+                  if original = new_source.css("code:contains('render_original')").first
+                    if override.action == :surround
+                      original.replace match.clone(1)
+                      match.replace new_source
+                    elsif override.action == :surround_contents
+                      original.replace match.children
+                      match.children.remove
+                      match.add_child new_source
+                    end
+                  else
+                    #maybe we should log that the original wasn't found.
+                  end
+
                 when :insert_before
                   match.before override.source_element
                 when :insert_after
@@ -316,6 +336,8 @@ module Deface
       virtual_path = details[:virtual_path]
       return [] if virtual_path.nil?
 
+      virtual_path = virtual_path[1..-1] if virtual_path.first == '/'
+
       result = []
       result << self.all[virtual_path.to_sym].try(:values)
 

data/lib/deface/railtie.rb

@@ -1,12 +1,67 @@
 module Deface
   class Railtie < Rails::Railtie
+    # include rake tasks.
+    # 
     rake_tasks do
-      load File.join([File.dirname(__FILE__) , "../../tasks/deface.rake"])
+      %w{utils precompile}.each { |r| load File.join([File.dirname(__FILE__) , "../../tasks/#{r}.rake"]) }
     end
 
-    initializer "deface.environment" do |app|
+    def self.activate
+      if Rails.application.config.deface.enabled
+        #load all overrides
+        Rails.application.config.deface.overrides.load_all Rails.application
+      end
+
+    end
+
+    config.to_prepare &method(:activate).to_proc
+
+    # configures basic deface environment, with gets replaced
+    # with real environment if deface is not disabled
+    #
+    initializer "deface.add_configuration", :before => :load_environment_config do |app|
+      app.config.deface = ActiveSupport::OrderedOptions.new
+      app.config.deface.enabled = true
+    end
+
+    # injects path for compiled views
+    #
+    initializer "deface.precompile.inject_views", :before => :add_view_paths do |app|
+      app.paths["app/views"].unshift "app/compiled_views"
+    end
+
+    # remove app/overrides from eager_load_path for app and all railites
+    # as we require them manually depending on configuration values
+    #
+    initializer "deface.tweak_eager_loading", :before => :set_load_path do |app|
+
+      # application
+      app.config.eager_load_paths.reject! {|path| path  =~ /app\/overrides\z/ }
+
+      # railites / engines / extensions
+      app.railties.all.each do |railtie|
+        next unless railtie.respond_to? :root
+
+        railtie.config.eager_load_paths.reject! {|path| path  =~ /app\/overrides\z/ }
+      end
+    end
+
+    # sets up deface environment and requires / loads all
+    # overrides if deface is enabled.
+    #
+    initializer "deface.environment", :after => :load_environment_config do |app|
+      next unless app.config.deface.enabled
+
+      #setup real env object
       app.config.deface = Deface::Environment.new
+
+      #catchs any overrides that we required manually
       app.config.deface.overrides.early_check
+
+      if Dir.glob(app.root.join("app/compiled_views", "**/*.erb")).present?
+        puts "[WARNING] Precompiled views present and Deface is enabled, this can result in overrides being applied twice."
+      end
     end
+
   end
 end

data/lib/deface/template_helper.rb

@@ -2,7 +2,7 @@ module Deface
   module TemplateHelper
 
     # used to find source for a partial or template using virutal_path
-    def load_template_source(virtual_path, partial, include_overrides=true)
+    def load_template_source(virtual_path, partial, apply_overrides=true)
       parts = virtual_path.split("/")
       prefix = []
       if parts.size == 2
@@ -13,15 +13,9 @@ module Deface
         name = parts.join("/")
       end
 
+      Rails.application.config.deface.enabled = apply_overrides
       @lookup_context ||= ActionView::LookupContext.new(ActionController::Base.view_paths, {:formats => [:html]})
-
-      source = @lookup_context.find(name, prefix, partial).source
-
-      if include_overrides
-        Deface::Override.apply(source, {:virtual_path => virtual_path}, false)
-      else
-        source
-      end
+      @lookup_context.find(name, prefix, partial).source
     end
 
     #gets source erb for an element

data/spec/deface/environment_spec.rb

@@ -29,6 +29,73 @@ module Deface
       it "should find overrides" do
         Rails.application.config.deface.overrides.find(:virtual_path => "posts/new").size.should == 1
       end
+
+      describe "load_all" do
+
+        before do
+          Rails.application.stub :root => Pathname.new(File.join(File.dirname(__FILE__), '..', "assets"))
+          Rails.application.stub :paths => {}
+          Rails.application.stub_chain :railties, :all => [] 
+        end
+
+        it "should enumerate_and_load nil when app has no app/overrides path set" do
+          Rails.application.config.deface.overrides.should_receive(:enumerate_and_load).with(nil, Rails.application.root)
+          Rails.application.config.deface.overrides.load_all(Rails.application)
+        end
+
+        it "should enumerate_and_load path when app has app/overrides path set" do
+          Rails.application.stub :paths => {"app/overrides" => ["app/some_path"] }
+          Rails.application.config.deface.overrides.should_receive(:enumerate_and_load).with(["app/some_path"] , Rails.application.root)
+          Rails.application.config.deface.overrides.load_all(Rails.application)
+        end
+
+        it "should enumerate_and_load nil when railtie has no app/overrides path set" do
+          Rails.application.stub_chain :railties, :all => [mock('railtie', :root => "/some/path")]
+
+          Rails.application.config.deface.overrides.should_receive(:enumerate_and_load).with(nil, Rails.application.root)
+          Rails.application.config.deface.overrides.should_receive(:enumerate_and_load).with(nil, "/some/path")
+          Rails.application.config.deface.overrides.load_all(Rails.application)
+        end
+
+        it "should enumerate_and_load path when railtie has  app/overrides path set" do
+          Rails.application.stub_chain :railties, :all => [ mock('railtie', :root => "/some/path", :paths => {"app/overrides" => ["app/some_path"] } )]
+
+          Rails.application.config.deface.overrides.should_receive(:enumerate_and_load).with(nil, Rails.application.root)
+          Rails.application.config.deface.overrides.should_receive(:enumerate_and_load).with(["app/some_path"] , "/some/path")
+          Rails.application.config.deface.overrides.load_all(Rails.application)
+        end
+
+        it "should ignore railtie with no root" do
+          railtie = mock('railtie')
+          Rails.application.stub_chain :railties, :all => [railtie]
+
+          railtie.should_receive(:respond_to?).with(:root)
+          railtie.should_not_receive(:respond_to?).with(:paths)
+          Rails.application.config.deface.overrides.load_all(Rails.application)
+        end
+
+      end
+
+      describe "enumerate_and_load" do
+        let(:root) { Pathname.new("/some/path") }
+
+        it "should be enumerate default path when none supplied" do
+          Dir.should_receive(:glob).with(root.join "app/overrides", "*.rb")
+          Rails.application.config.deface.overrides.send(:enumerate_and_load, nil, root)
+        end
+
+        it "should be enumerate supplied path" do
+          Dir.should_receive(:glob).with(root.join "app/junk", "*.rb")
+          Rails.application.config.deface.overrides.send(:enumerate_and_load, ["app/junk"], root)
+        end
+
+        it "should be enumerate supplied paths" do
+          Dir.should_receive(:glob).with(root.join "app/junk", "*.rb" )
+          Dir.should_receive(:glob).with(root.join "app/gold", "*.rb" )
+          Rails.application.config.deface.overrides.send(:enumerate_and_load, ["app/junk", "app/gold"], root)
+        end
+
+      end
     end
 
     describe "#_early" do

data/spec/deface/template_helper_spec.rb

@@ -13,7 +13,7 @@ module Deface
 
       describe "with no overrides defined" do
         it "should return source for partial" do
-          load_template_source("shared/_post", false).should == "<p>I'm from shared/post partial</p>\n<%= \"And I've got ERB\" %>\n"
+          load_template_source("shared/post", true).should == "<p>I'm from shared/post partial</p>\n<%= \"And I've got ERB\" %>\n"
         end
 
         it "should return source for template" do
@@ -25,7 +25,7 @@ module Deface
         end
 
         it "should raise exception for non-existing file" do
-          lambda { load_template_source("tester/_post", false) }.should raise_error(ActionView::MissingTemplate)
+          lambda { load_template_source("tester/post", true) }.should raise_error(ActionView::MissingTemplate)
         end
 
       end
@@ -40,11 +40,11 @@ module Deface
         end
 
         it "should return source for partial including overrides" do
-          load_template_source("shared/_post", false).should == "\n<%= \"And I've got ERB\" %>"
+          load_template_source("shared/post", true).should == "\n<%= \"And I've got ERB\" %>"
         end
 
         it "should return source for partial excluding overrides" do
-          load_template_source("shared/_post", false, false).should == "<p>I'm from shared/post partial</p>\n<%= \"And I've got ERB\" %>\n"
+          load_template_source("shared/post", true, false).should == "<p>I'm from shared/post partial</p>\n<%= \"And I've got ERB\" %>\n"
         end
 
         it "should return source for template including overrides" do

data/spec/deface/template_spec.rb

@@ -209,6 +209,51 @@ module ActionView
       end
     end
 
+
+    describe "with a single html surround override defined" do
+      before(:each) do
+        Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :surround => "p", :text => "<h1>It's behind you!</h1><div><%= render_original %></div>")
+        @template = ActionView::Template.new("<p>test</p>", "/some/path/to/file.erb", ActionView::Template::Handlers::ERB, {:virtual_path=>"posts/index", :format=>:html})
+      end
+
+      it "should return modified source" do
+        @template.source.should == "<h1>It's behind you!</h1><div><p>test</p></div>"
+      end
+    end
+
+    describe "with a single erb surround override defined" do
+      before(:each) do
+        Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :surround => "p", :text => "<% some_method('test') do %><%= render_original %><% end %>")
+        @template = ActionView::Template.new("<span><p>test</p></span>", "/some/path/to/file.erb", ActionView::Template::Handlers::ERB, {:virtual_path=>"posts/index", :format=>:html})
+      end
+
+      it "should return modified source" do
+        @template.source.gsub("\n", '').should == "<span><% some_method('test') do %><p>test</p><% end %></span>"
+      end
+    end
+
+    describe "with a single html surround_contents override defined" do
+      before(:each) do
+        Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :surround_contents => "div", :text => "<span><%= render_original %></span>")
+        @template = ActionView::Template.new("<h4>yay!</h4><div><p>test</p></div>", "/some/path/to/file.erb", ActionView::Template::Handlers::ERB, {:virtual_path=>"posts/index", :format=>:html})
+      end
+
+      it "should return modified source" do
+        @template.source.should == "<h4>yay!</h4><div><span><p>test</p></span></div>"
+      end
+    end
+
+    describe "with a single erb surround_contents override defined" do
+      before(:each) do
+        Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :surround_contents => "p", :text => "<% if 1==1 %><%= render_original %><% end %>")
+        @template = ActionView::Template.new("<p>test</p>", "/some/path/to/file.erb", ActionView::Template::Handlers::ERB, {:virtual_path=>"posts/index", :format=>:html})
+      end
+
+      it "should return modified source" do
+        @template.source.should == "<p><% if 1==1 %>test<% end %></p>"
+      end
+    end
+
     describe "with a single disabled override defined" do
       before(:each) do
         Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :remove => "p", :text => "<h1>Argh!</h1>", :disabled => true)

data/spec/spec_helper.rb

@@ -16,7 +16,8 @@ shared_context "mock Rails" do
     Rails.stub :application => mock('application')
     Rails.application.stub :config => mock('config')
     Rails.application.config.stub :cache_classes => true
-    Rails.application.config.stub :deface => nil
+    Rails.application.config.stub :deface => ActiveSupport::OrderedOptions.new
+    Rails.application.config.deface.enabled = true
   end
 end
 

data/tasks/precompile.rake

@@ -0,0 +1,40 @@
+require 'deface'
+
+namespace :deface do
+  include Deface::TemplateHelper
+
+  desc "Precompiles overrides into template files"
+  task :precompile => [:environment, :clean] do |t, args|
+    base_path = Rails.root.join("app/compiled_views")
+
+    # temporarily configures deface env and loads
+    # all overrides so we can precompile
+    unless Rails.application.config.deface.enabled
+      Rails.application.config.deface = Deface::Environment.new
+      Rails.application.config.deface.overrides.early_check
+      Rails.application.config.deface.overrides.load_all Rails.application
+    end
+
+    Rails.application.config.deface.overrides.all.each do |virtual_path,overrides|
+      template_path = base_path.join( "#{virtual_path}.html.erb")
+
+      FileUtils.mkdir_p template_path.dirname
+      begin
+        source = load_template_source(virtual_path.to_s, false, true)
+        if source.blank?
+          raise "Compiled source was blank for '#{virtual_path}'"
+        end
+        File.open(template_path, 'w') {|f| f.write source } 
+      rescue Exception => e
+        puts "Unable to precompile '#{virtual_path}' due to: "
+        puts e.message
+      end
+    end
+  end
+
+  desc "Removes all precompiled override templates"
+  task :clean do
+    FileUtils.rm_rf Rails.root.join("app/compiled_views")
+  end
+
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: deface
 version: !ruby/object:Gem::Version 
-  hash: 3
+  hash: 1
   prerelease: 
   segments: 
   - 0
   - 7
-  - 0
-  version: 0.7.0
+  - 1
+  version: 0.7.1
 platform: ruby
 authors: 
 - Brian D Quinn
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-05 00:00:00 Z
+date: 2011-10-27 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: nokogiri
@@ -57,12 +57,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 23
+        hash: 19
         segments: 
         - 2
-        - 6
+        - 7
         - 0
-        version: 2.6.0
+        version: 2.7.0
   type: :development
   version_requirements: *id003
 description: Deface is a library that allows you to customize ERB views in a Rails application without editing the underlying view.
@@ -97,7 +97,8 @@ files:
 - spec/deface/template_helper_spec.rb
 - spec/deface/template_spec.rb
 - spec/spec_helper.rb
-- tasks/deface.rake
+- tasks/precompile.rake
+- tasks/utils.rake
 homepage: http://github.com/railsdog/deface
 licenses: []