deface 0.5.0 → 0.5.1

data/README.markdown

@@ -41,10 +41,15 @@ Source
 
 * <tt>:template</tt> - Relative path to a template
 
+
 Optional
 --------
 * <tt>:name</tt> - Unique name for override so it can be identified and modified later. This needs to be unique within the same `:virtual_path`
 
+* <tt>:disabled</tt> - When set to true the override will not be applied.
+
+* <tt>:original</tt> - String containing original markup that is being overridden. If supplied Deface will log when the original markup changes, which helps highlight overrides that need attention when upgrading versions of the source application. Only really warranted for :replace overrides. NB: All whitespace is stripped before comparsion.
+
 Examples
 ========
 
@@ -69,11 +74,12 @@ Inserts the contents of `shared/_comment.html.erb` after all instances of `div`
                           :insert_after => "div#comment_21", 
                           :partial => "shared/comment")
 
-Removes any instance of `<%= helper_method %>` in the `posts/new.html.erb" template:
+Removes any ERB block containing the string `helper_method` in the `posts/new.html.erb` template, will also log if markup being removed does not match `<%= helper_method %>`
 
      Deface::Override.new(:virtual_path => "posts/new", 
                           :name => "example-4", 
-                          :remove => "code[erb-loud]:contains('helper_method')" )
+                          :remove => "code[erb-loud]:contains('helper_method')",
+                          :original => "<%= helper_method %>")
 
 
 Implementation
@@ -107,12 +113,12 @@ Deface overrides have full access to all variables accessible to the view being
 
 Caveats
 ======
+Deface uses the amazing Nokogiri library (and in turn libxml) for parsing HTML / view files, in some circumstances either Deface's own pre-parser or libxml's will fail to correctly parse a template. You can avoid such issues by ensuring your templates contain valid HTML. Some other caveats include:
 
-Due to the use of the Nokogiri library for parsing HTML / view files you need to ensure that your layout views include doctype, html, head and body tags in a single file, as Nokogiri will create such elements if it detects any of these tags have been incorrectly nested.
+1. Ensure that your layout views include doctype, html, head and body tags in a single file, as Nokogiri will create such elements if it detects any of these tags have been incorrectly nested.
 
-Parsing will fail and result in invalid output if ERB blocks are responsible for closing a HTML tag what was opened normally, i.e. don't do this:
+2. Parsing will fail and result in invalid output if ERB blocks are responsible for closing a HTML tag what was opened normally, i.e. don't do this:
 
 
       <div <%= ">" %>
 
-

data/Rakefile

@@ -22,22 +22,3 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('README')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
-
-begin
-  require "jeweler"
-  Jeweler::Tasks.new do |gem|
-    gem.name = "deface"
-    gem.summary = "Deface is a library that allows you to customize ERB views in Rails"
-    gem.description = "Deface is a library that allows you to customize ERB views in a Rails application without editing the underlying view."
-    gem.email = "brian@railsdog.com"
-    gem.homepage = "http://github.com/BDQ/Deface"
-    gem.authors = ["Brian Quinn"]
-    gem.files = Dir["*", "{lib}/**/*"]
-    gem.add_dependency("nokogiri", "~> 1.4.3")
-    gem.add_dependency("rails", "~> 3.0.0")
-  end
-
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end

data/deface.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{deface}
-  s.version = "0.5.0"
+  s.version = "0.5.1"
 
   s.authors = ["Brian Quinn"]
   s.description = %q{Deface is a library that allows you to customize ERB views in a Rails application without editing the underlying view.}
@@ -33,7 +33,7 @@ Gem::Specification.new do |s|
     end
   else
     s.add_dependency(%q<nokogiri>, ["~> 1.4.3"])
-    s.add_dependency(%q<rails>, ["~> 3.0.0"])
+    s.add_dependency(%q<rails>, [">= 3.0.0"])
   end
 end
 

data/lib/deface.rb

@@ -4,3 +4,7 @@ require "deface/action_view_extensions"
 require "deface/template_helper"
 require "deface/override"
 require "deface/parser"
+
+module Deface
+  require 'deface/railtie' if defined?(Rails)
+end

data/lib/deface/override.rb

@@ -37,6 +37,10 @@ module Deface
     # * <tt>:name</tt> - Unique name for override so it can be identified and modified later.
     #   This needs to be unique within the same :virtual_path
     # * <tt>:disabled</tt> - When set to true the override will not be applied.
+    # * <tt>:original</tt> - String containing original markup that is being overridden.
+    #   If supplied Deface will log when the original markup changes, which helps highlight overrides that need 
+    #   attention when upgrading versions of the source application. Only really warranted for :replace overrides.
+    #   NB: All whitespace is stripped before comparsion.
 
 
     def initialize(args)
@@ -77,6 +81,25 @@ module Deface
       Deface::Parser.convert(source.clone)
     end
 
+    def original_source
+      return nil unless @args[:original].present?
+
+      Deface::Parser.convert(@args[:original].clone)
+    end
+
+    # logs if original source has changed
+    def validate_original(match)
+      return true if self.original_source.nil?
+
+      valid = self.original_source.to_s.gsub(/\s/, '') == match.to_s.gsub(/\s/, '')
+
+      if !valid && defined?(Rails) == "constant"
+        Rails.logger.error "\e[1;32mDeface: [WARNING]\e[0m The original source for '#{self.name}' has changed, this override should be reviewed to ensure it's still valid."
+      end
+
+      valid
+    end
+
     def disabled?
       @args.key?(:disabled) ? @args[:disabled] : false
     end
@@ -89,10 +112,10 @@ module Deface
     #
     def self.apply(source, details)
       overrides = find(details)
-      @enable_logging ||= (defined?(Rails) == "constant" ? true : false)
+      @enable_logging ||= defined?(Rails) == "constant"
 
       if @enable_logging && overrides.size > 0
-        Rails.logger.info "\e[1;32mDeface:\e[0m #{overrides.size} overrides found for #{details[:virtual_path]}"
+        Rails.logger.info "\e[1;32mDeface:\e[0m #{overrides.size} overrides found for '#{details[:virtual_path]}'"
       end
 
       unless overrides.empty?
@@ -100,9 +123,7 @@ module Deface
 
         overrides.each do |override|
           if override.disabled?
-            if @enable_logging
-              Rails.logger.info "\e[1;32mDeface:\e[0m #{override.name} is disabled"
-            end
+            Rails.logger.info("\e[1;32mDeface:\e[0m '#{override.name}' is disabled") if @enable_logging
             next
           end
 
@@ -112,10 +133,12 @@ module Deface
             matches = doc.css(override.selector)
 
             if @enable_logging
-              Rails.logger.info "\e[1;32mDeface:\e[0m #{override.name} matched #{matches.size} times with #{override.selector}"
+              Rails.logger.send(matches.size == 0 ? :error : :info, "\e[1;32mDeface:\e[0m '#{override.name}' matched #{matches.size} times with '#{override.selector}'")
             end
 
             matches.each do |match|
+              override.validate_original(match)
+
               case override.action
                 when :remove
                   match.replace ""

data/lib/deface/railtie.rb

@@ -0,0 +1,7 @@
+module Deface
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.join([File.dirname(__FILE__) , "../../tasks/deface.rake"])
+    end
+  end
+end

data/lib/deface/template_helper.rb

@@ -17,5 +17,14 @@ module Deface
 
       @lookup_context.find(name, prefix, partial).source
     end
+
+    #gets source erb for an element
+    def element_source(template_source, selector)
+      doc = Deface::Parser.convert(template_source)
+
+      doc.css(selector).inject([]) do |result, match|
+        result << Deface::Parser.undo_erb_markup!(match.to_s.dup)
+      end
+    end
   end
 end

data/spec/deface/override_spec.rb

@@ -17,6 +17,37 @@ module Deface
       @override.selector.should == "h1"
     end
 
+    describe "#original_source" do
+      it "should return nil with not specified" do
+        @override.original_source.should be_nil
+      end
+
+      it "should return parsed nokogiri document when present" do
+        @original = Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :replace => "h1", :text => "<h1>Argh!</h1>", :original => "<p><%= something %></p>")
+        @original.original_source.should be_an_instance_of Nokogiri::HTML::DocumentFragment
+        @original.original_source.to_s.should == "<p><code erb-loud> something </code></p>"
+      end
+    end
+
+    describe "#validate_original" do
+      before(:each) do
+        @original = Deface::Override.new(:virtual_path => "posts/index", :name => "Posts#index", :replace => "h1", :text => "<h1>Argh!</h1>", :original => "<p><%= something %></p>")
+      end
+
+      it "should return true when :original is not present" do
+        @override.validate_original("").should be_true
+      end
+
+      it "should return true when :original present, and input contains similar (ignoring whitespace)" do
+        @original.validate_original("<p><code erb-loud> something </code></p>").should be_true
+        @original.validate_original("<p><code erb-loud>something\n</code>  </p>").should be_true
+      end
+
+      it "should return false when :original present, and input contains different string" do
+        @original.validate_original("wrong").should be_false
+      end
+    end
+
     describe "#find" do
       it "should find by virtual_path" do
         Deface::Override.find({:virtual_path => "posts/index"}).size.should == 1

data/tasks/deface.rake

@@ -0,0 +1,26 @@
+namespace :deface do
+  desc 'Gets source of html element from template.'
+  task :get_source, :template_path, :selector, :needs => :environment do |t, args|
+    include Deface::TemplateHelper
+
+    begin
+      source = load_template_source(args[:template_path], false)
+      output = element_source(source, args[:selector])
+    rescue
+      puts "Failed to find tempalte/partial"
+
+      output = []
+    end
+
+    if output.empty?
+      puts "0 matches found"
+    else
+      puts "Querying '#{args[:template_path]}' for '#{args[:selector]}'"
+      output.each_with_index do |content, i|
+        puts "---------------- Match #{i+1} ----------------"
+        puts content
+      end
+    end
+
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: deface
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: 
   segments: 
   - 0
   - 5
-  - 0
-  version: 0.5.0
+  - 1
+  version: 0.5.1
 platform: ruby
 authors: 
 - Brian Quinn
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-24 00:00:00 +01:00
+date: 2011-06-03 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -69,6 +69,7 @@ files:
 - lib/deface/action_view_extensions.rb
 - lib/deface/override.rb
 - lib/deface/parser.rb
+- lib/deface/railtie.rb
 - lib/deface/template_helper.rb
 - spec/assets/admin/posts/index.html.erb
 - spec/assets/shared/_post.html.erb
@@ -78,6 +79,7 @@ files:
 - spec/deface/template_helper_spec.rb
 - spec/deface/template_spec.rb
 - spec/spec_helper.rb
+- tasks/deface.rake
 has_rdoc: true
 homepage: http://github.com/railsdog/deface
 licenses: []