deface 0.8.0 → 0.9.0

data/.travis.yml

@@ -3,4 +3,6 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
-  - ree
+gemfile:
+  - gemfiles/rails3_1.gemfile
+  - gemfiles/rails3_2.gemfile

data/README.markdown

@@ -7,40 +7,40 @@
 Deface
 ======
 
-Deface is a library that allows you to customize HTML ERB views in a Rails application without editing the underlying view.
+Deface is a library that allows you to customize HTML (ERB and HAML) views in a Rails application without editing the underlying view.
 
 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)
 
+Usage
+-----
 
-Production & Precompiling
-------------------------
+There are two ways of using Deface:
 
-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:
+- Using `Deface::Override` - this is the traditional method whereby you define instances of the Deface::Override class directly.
+- Using the Deface DSL (.deface files) - the DSL provides a terser syntax, and better organization of the individual override files.
 
-     bundle exec rake deface:precompile
+Both methods are interoperable, so you can use a mix, and redefine overrides defined one-way using the other.
 
-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.
+Using 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, :set_attributes, :add_to_attributes, :remove_from_attributes```` actions are specified.
 
-Deface::Override
-================
+You should save your overrides in the ````app/overrides````, normally one override per file using the same file name as specified in the :name argument. Deface will automatically require these from your application, and any engines installed.
 
-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.
+**Note:** You should NOT manually require override files, as this can cause problems for precompiling.
+
+### Target
 
-Target
-------
 * <tt>:virtual_path</tt> - The template / partial / layout where the override should take effect eg: *"shared/_person"*, *"admin/posts/new"* this will apply to all controller actions that use the specified template.
 
-Action
-------
+### Action
+
 * <tt>:remove</tt> - Removes all elements that match the supplied selector
 
 * <tt>:replace</tt> - Replaces all elements that match the supplied selector
@@ -59,23 +59,30 @@ Action
 
 * <tt>:insert_bottom</tt> - Inserts inside all elements that match the supplied selector, as the last child.
 
-* <tt>:set_attributes</tt> - Sets attributes on all elements that match the supplied selector, replacing existing attribute value if present or adding if not. Expects :attributes option to be passed.
+* <tt>:set_</tt> - Sets attributes on all elements that match the supplied selector, replacing existing attribute value if present or adding if not. Expects :attributes option to be passed.
 
 * <tt>:add_to_attributes</tt> - Appends value to attributes on all elements that match the supplied selector, adds attribute if not present. Expects :attributes option to be passed.
 
 * <tt>:remove_from_attributes</tt> - Removes value from attributes on all elements that match the supplied selector. Expects :attributes option to be passed.
 
-Source
-------
+### Source
+
 * <tt>:text</tt> - String containing markup
 
 * <tt>:partial</tt> - Relative path to a partial
 
 * <tt>:template</tt> - Relative path to a template
 
+* <tt>:cut</tt> - Cuts (i.e. copies and removes) an element or a range of elements from the current template as the source, using css selector(s). Supports two versions:
+  * <tt>selector</tt> -  A single string css selector (first match is used).
+  * <tt>{:start => 'selector_a', :end => 'selector_b'}</tt> - select a range of elements using :start and :end css selectors. The end element must be a sibling of the first/starting element.
+
+* <tt>:copy</tt> - Copies an element or a range of elements from the current template as the source, using css selector(s). Supports two versions:
+  * <tt>selector</tt> -  A single string css selector (first match is used).
+  * <tt>{:start => 'selector_a', :end => 'selector_b'}</tt> - select a range of elements using :start and :end css selectors. The end element must be a sibling of the first/starting element.
+
+### Optional
 
-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.
@@ -93,8 +100,7 @@ Optional
 
 * <tt>:attributes</tt> - A hash containing all the attributes to be set on the matched elements, eg: :attributes => {:class => "green", :title => "some string"}
 
-Examples
-========
+### Examples
 
 Replaces all instances of `h1` in the `posts/_form.html.erb` partial with `<h1>New Post</h1>`
 
@@ -153,23 +159,84 @@ Remove an entire ERB if statement (and all it's contents) in the 'admin/products
                          :remove => "code[erb-silent]:contains('if @product.sold?')",
                          :closing_selector => "code[erb-silent]:contains('end')"
 
-Scope
-=====
+### Scope
 
 Deface scopes overrides by virtual_path (or partial / template file), that means all override names only need to be unique within that single file.
 
-Redefining Overrides
-====================
+### Redefining Overrides
 
 You can redefine an existing override by simply declaring a new override with the same <tt>:virtual_path</tt> and <tt>:name</tt> that was originally used.
 You do not need to resupply all the values originally used, just the ones you want to change:
 
-   Deface::Override.new(:virtual_path => 'posts/index',
+    Deface::Override.new(:virtual_path => 'posts/index',
                         :name => 'add_attrs_to_a_link',
                         :disabled => true)
 
+
+Using the Deface DSL (.deface files)
+------------------------------------
+
+Instead of defining Deface::Override instances directly, you can alternatively add `.deface` files to the `app/overrides` folder and Deface will automatically them pick up.
+The path of each override should match the path of the view template you want to modify, say for example if you have a template at:
+
+    app/views/posts/_post.html.erb
+
+Then you can override it by adding a .deface file at:
+
+    app/overrides/posts/_post/my_override.html.erb.deface
+
+The format of a .deface file is a comment showing the action to be performed, followed by any markup that would be normally passed to the :erb, :text, :haml arguments:
+
+    <!-- insert_after 'h1' -->
+    <h2>These robots are awesome.</h2>
+
+The same effect can also be achieved with haml, by changing the overrides filename to:
+
+    app/overrides/posts/_post/my_override.html.haml.deface
+
+and including haml source:
+
+    /
+      insert_after 'h1'
+    %h2 These robots are awesome.
+
+
+#### Additional Options
+
+You can include all the additional options you can normally use when defining a Deface::Override manually, a more complex example:
+
+    <!-- replace_contents 'h1'
+         closing_selector 'div#intro'
+         disabled -->
+    <p>This is a complicated example</p>
+
+#### Disabled / Enabled
+
+The DSL does not accept the instance style ````:disabled => boolean```` instead you can simply include either:
+
+    <!-- enabled -->
+
+or
+
+    <!-- disabled -->
+
+### DSL usage for overrides that do not include markup
+
+If your override does not require any markup, for example actions including ````:remove, :set_attributes, :remove_from_attributes, :add_to_attrbiutes```` you can exclude the "html.erb" or "html.haml" from the file name and you do not need to wrap the arguments in a comment.
+
+So the override filename becomes simply:
+
+    app/overrides/posts/_post/my_override.deface
+
+And the contents:
+
+    add_to_attributes 'a#search'
+    attributes :alt => 'Click here to search'
+
+
+
 Rake Tasks
-==========
+----------
 
 Deface includes a couple of rake tasks that can be helpful when defining or debugging overrides.
 
@@ -185,10 +252,28 @@ Deface includes a couple of rake tasks that can be helpful when defining or debu
 
     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.
+**deface:precompile** - Generates compiled views that contain all overrides applied. See `Production & Precompiling` section below for more.
 
     rake deface:precompile
 
+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.
+
+
+Demo & Testing
+--------------
+You can play with Deface and see its parsing in action at [deface.heroku.com](http://deface.heroku.com)
+
 
 Implementation
 ==============
@@ -219,6 +304,7 @@ ERB that is contained inside a HTML tag definition is converted slightly differe
 
 Deface overrides have full access to all variables accessible to the view being customized.
 
+
 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:

data/deface.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "deface"
-  s.version = "0.8.0"
+  s.version = "0.9.0"
 
   s.authors = ["Brian D Quinn"]
   s.description = "Deface is a library that allows you to customize ERB & HAML views in a Rails application without editing the underlying view."
@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
   s.summary = "Deface is a library that allows you to customize ERB & HAML views in Rails"
 
   s.add_dependency('nokogiri', '~> 1.5.0')
-  s.add_dependency('rails', '>= 3.0.9')
+  s.add_dependency('rails', '~> 3.1')
 
   s.add_development_dependency('rspec', '>= 2.8.0')
   s.add_development_dependency('haml', '>= 3.1.4')

data/gemfiles/rails3_1.gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gem "rails", "~> 3.1.0"
+
+gemspec :path=>"../"

data/gemfiles/rails3_2.gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gem "rails", "~> 3.2.0"
+
+gemspec :path=>"../"

data/lib/deface.rb

@@ -7,9 +7,16 @@ require "deface/search"
 require "deface/override"
 require "deface/parser"
 require "deface/environment"
+require "deface/dsl/loader"
 
 module Deface
   if defined?(Rails)
     require "deface/railtie"
   end
+
+  # Exceptions
+  class DefaceError < StandardError; end
+
+  class NotSupportedError < DefaceError; end
+  
 end

data/lib/deface/action_view_extensions.rb

@@ -23,23 +23,33 @@ ActionView::Template.class_eval do
   # view needs to be recompiled
   #
   def render(view, locals, buffer=nil, &block)
-    if @compiled && !view.respond_to?(method_name)
+
+    if view.is_a?(ActionView::CompiledTemplates)
+      mod = ActionView::CompiledTemplates
+    else
+      mod = view.singleton_class
+    end
+
+    if @compiled && !mod.instance_methods.map(&:to_s).include?(method_name)
       @compiled = false
       @source = refresh(view).source
     end
     render_without_deface(view, locals, buffer, &block)
   end
 
+  protected
 
-  alias_method :method_name_without_deface, :method_name
+    alias_method :method_name_without_deface, :method_name
 
-  # inject deface hash into compiled view method name
-  # used to determine if recompilation is needed
-  #
-  def method_name
-    deface_hash = Deface::Override.digest(:virtual_path => @virtual_path)
-    "_#{deface_hash}_#{method_name_without_deface}"
-  end
+    # inject deface hash into compiled view method name
+    # used to determine if recompilation is needed
+    #
+    def method_name
+      deface_hash = Deface::Override.digest(:virtual_path => @virtual_path)
+
+      #we digest the whole method name as if it gets too long there's problems
+      "_#{Digest::MD5.new.update("#{deface_hash}_#{method_name_without_deface}").hexdigest}"
+    end
 end
 
 #fix for Rails 3.1 not setting virutal_path anymore (BOO!)

data/lib/deface/applicator.rb

@@ -24,6 +24,8 @@ module Deface
               next
             end
 
+            override.parsed_document = doc
+
             if override.end_selector.blank?
               # single css selector
 
@@ -118,14 +120,11 @@ module Deface
 
               end
             else
-              # targeting range of elements as end_selector is present
-              starting    = doc.css(override.selector).first
-
-              if starting && starting.parent
-                ending = starting.parent.css(override.end_selector).first
-              else
-                ending = doc.css(override.end_selector).first
+              unless [:remove, :replace, :replace_contents, :surround, :surround_contents].include? override.action
+                raise Deface::NotSupportedError, ":#{override.action} action does not support :closing_selector"
               end
+              # targeting range of elements as end_selector is present
+              starting, ending = select_endpoints(doc, override.selector, override.end_selector)
 
               if starting && ending
                 if log
@@ -143,6 +142,43 @@ module Deface
                   when :replace_contents
                     elements[1..-2].map &:remove
                     starting.after(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
+                        start = elements[0].clone(1)
+                        original.replace start
+
+                        elements[1..-1].each do |element|
+                          element = element.clone(1)
+                          start.after element
+                          start = element
+                        end
+
+                        starting.before(new_source)
+                        elements.map &:remove
+
+
+                      elsif override.action == :surround_contents
+
+                        start = elements[1].clone(1)
+                        original.replace start
+
+                        elements[2...-1].each do |element|
+                          element = element.clone(1)
+                          start.after element
+                          start = element
+                        end
+
+                        starting.after(new_source)
+                        elements[1...-1].map &:remove
+                      end
+                    else
+                      #maybe we should log that the original wasn't found.
+                    end
                 end
               else
                 if starting.nil?
@@ -167,13 +203,31 @@ module Deface
         source
       end
 
-      private
+
+        def select_endpoints(doc, start, finish)
+          # targeting range of elements as end_selector is present
+          #
+          finish = "#{start} ~ #{finish}"
+          starting    = doc.css(start).first
+
+          ending = if starting && starting.parent
+            starting.parent.css(finish).first
+          else
+            doc.css(finish).first
+          end
+
+          return starting, ending
+
+        end
+
         # finds all elements upto closing sibling in nokgiri document
         #
         def select_range(first, last)
           first == last ? [first] : [first, *select_range(first.next, last)]
         end
 
+        private
+
         def normalize_attribute_name(name)
           name = name.to_s.gsub /"|'/, ''
 
@@ -183,10 +237,6 @@ module Deface
 
           name
         end
-
-        def set_attributes(match, name, value)
-
-        end
     end
   end
 end

data/lib/deface/dsl/context.rb

@@ -0,0 +1,67 @@
+module Deface
+  module DSL
+    class Context
+      def initialize(name)
+        @name = name
+        @options = {}
+      end
+
+      def create_override
+        options = {
+          :name => @name, 
+          :virtual_path => @virtual_path,
+        }.merge(@action || {}).merge(@source || {}).merge(@options)
+
+        Deface::Override.new(options)
+      end
+
+      def virtual_path(name)
+        @virtual_path = name
+      end
+
+      Deface::Override.actions.each do |action_name|
+        define_method(action_name) do |selector|
+          if @action.present?
+            Rails.logger.error "\e[1;32mDeface: [WARNING]\e[0m Multiple action methods have been called. The last one will be used."
+          end
+
+          @action = { action_name => selector }
+        end
+      end
+
+      Deface::Override.sources.each do |source_name|
+        define_method(source_name) do |value|
+          if @source.present?
+            Rails.logger.error "\e[1;32mDeface: [WARNING]\e[0m Multiple source methods have been called. The last one will be used."
+          end
+
+          @source = { source_name => value }
+        end
+      end
+
+      def original(markup)
+        @options[:original] = markup
+      end
+
+      def closing_selector(selector)
+        @options[:closing_selector] = selector
+      end
+
+      def sequence(value)
+        @options[:sequence] = value
+      end
+
+      def attributes(values)
+        @options[:attributes] = values
+      end
+
+      def enabled
+        @options[:disabled] = false
+      end
+
+      def disabled
+        @options[:disabled] = true
+      end
+    end
+  end
+end