@@ -2,7 +2,9 @@ Sanitize History ================================================================================ Version 1.2.0.dev (git) - * ? + * Added support for transformers, which allow you to filter and alter nodes + using your own custom logic, on top of (or instead of) Sanitize's core + filter. See the README for details. Version 1.1.1.dev (git) * Requires Nokogiri >= 1.4.0. HISTORY @@ -38,7 +38,8 @@ Latest development version: == Usage If you don't specify any configuration options, Sanitize will use its strictest -settings by default, which means it will strip all HTML. +settings by default, which means it will strip all HTML and leave only text +behind. require 'rubygems' require 'sanitize' @@ -145,6 +146,72 @@ include the symbol <code>:relative</code> in the protocol array: 'a' => {'href' => ['http', 'https', :relative]} } +=== Transformers + +Transformers allow you to filter and alter nodes using your own custom logic, on +top of (or instead of) Sanitize's core filter. A transformer is any object that +responds to <code>call()</code> (such as a lambda or proc) and returns either +<code>nil</code> or a Hash containing certain optional response values. + +To use one or more transformers, pass them to the <code>:transformers</code> +config setting: + + Sanitize.clean(html, :transformers => [transformer_one, transformer_two]) + +==== Input + +Each registered transformer's <code>call()</code> method will be called once for +each element node in the HTML, and will receive as an argument an environment +Hash that contains the following items: + +[<code>:config</code>] + The current Sanitize configuration Hash. + +[<code>:node</code>] + A Nokogiri::XML::Node object representing an HTML element. + +==== Processing + +Each transformer has full access to the Nokogiri::XML::Node that's passed into +it and to the rest of the document via the node's <code>document()</code> +method. Any changes will be reflected instantly in the document and passed on to +subsequently-called transformers and to Sanitize itself. A transformer may even +call Sanitize internally to perform custom sanitization if needed. + +Nodes are passed into transformers in the order in which they're traversed. It's +important to note that Nokogiri traverses markup from the deepest node upward, +not from the first node to the last node: + + html = '<div><span>foo</span></div>' + transformer = lambda{|env| puts env[:node].name } + + # Prints "span", then "div". + Sanitize.clean(html, :transformers => transformer) + +Transformers have a tremendous amount of power, including the power to +completely bypass Sanitize's built-in filtering. Be careful! + +==== Output + +A transformer may return either +nil+ or a Hash. A return value of +nil+ +indicates that the transformer does not wish to act on the current node in any +way. A returned Hash may contain the following items, all of which are optional: + +[<code>:attr_whitelist</code>] + Array of attribute names to add to the whitelist for the current node, in + addition to any whitelisted attributes already defined in the current config. + +[<code>:node</code>] + A Nokogiri::XML::Node object that should replace the current node. All + subsequent transformers and Sanitize itself will receive this new node. + +[<code>:whitelist</code>] + If _true_, the current node (and only the current node) will be whitelisted, + regardless of the current Sanitize config. + +[<code>:whitelist_nodes</code>] + Array of specific Nokogiri::XML::Node objects to whitelist, anywhere in the + document, regardless of the current Sanitize config. == Contributors README.rdoc @@ -56,7 +56,7 @@ class Sanitize sanitize.clean!(html) end - # Sanitizes the specified Nokogiri::XML::Node. + # Sanitizes the specified Nokogiri::XML::Node and all its children. def self.clean_node!(node, config = {}) sanitize = Sanitize.new(config) sanitize.clean_node!(node) @@ -70,6 +70,7 @@ class Sanitize def initialize(config = {}) # Sanitize configuration. @config = Config::DEFAULT.merge(config) + @config[:transformers] = Array(@config[:transformers]) # Specific nodes to whitelist (along with all their attributes). This array # is generated at runtime by transformers, and is cleared before and after @@ -88,7 +89,7 @@ class Sanitize def clean!(html) @whitelist_nodes = [] fragment = Nokogiri::HTML::DocumentFragment.parse(html) - fragment.traverse {|node| clean_node!(node) } + clean_node!(fragment) @whitelist_nodes = [] output_method_params = {:encoding => 'utf-8', :indent => 0} @@ -112,16 +113,19 @@ class Sanitize return result == html ? nil : html[0, html.length] = result end - # Sanitizes the specified Nokogiri::XML::Node. + # Sanitizes the specified Nokogiri::XML::Node and all its children. def clean_node!(node) raise ArgumentError unless node.is_a?(Nokogiri::XML::Node) - if node.element? - clean_element!(node) - elsif node.comment? - node.unlink unless @config[:allow_comments] - elsif node.cdata? - node.replace(Nokogiri::XML::Text.new(node.text, node.document)) + node.traverse do |traversed_node| + if traversed_node.element? + clean_element!(traversed_node) + elsif traversed_node.comment? + traversed_node.unlink unless @config[:allow_comments] + elsif traversed_node.cdata? + traversed_node.replace(Nokogiri::XML::Text.new(traversed_node.text, + traversed_node.document)) + end end node lib/sanitize.rb @@ -1,3 +1,3 @@ class Sanitize - VERSION = '1.2.0.dev.20091102' + VERSION = '1.2.0.dev.20091104' end lib/sanitize/version.rb @@ -2,11 +2,11 @@ Gem::Specification.new do |s| s.name = %q{sanitize} - s.version = "1.1.1.dev.20091102" + s.version = "1.2.0.dev.20091104" s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version= s.authors = ["Ryan Grove"] - s.date = %q{2009-11-02} + s.date = %q{2009-11-04} s.email = %q{ryan@wonko.com} s.files = ["HISTORY", "LICENSE", "README.rdoc", "lib/sanitize/config/basic.rb", "lib/sanitize/config/relaxed.rb", "lib/sanitize/config/restricted.rb", "lib/sanitize/config.rb", "lib/sanitize/version.rb", "lib/sanitize.rb"] s.homepage = %q{http://github.com/rgrove/sanitize/} sanitize.gemspec @@ -306,20 +306,23 @@ end describe 'transformers' do # YouTube transformer youtube = lambda do |env| - node = env[:node] - name = node.name.to_s.downcase + node = env[:node] + parent = node.parent + name = node.name.to_s.downcase return nil unless name == 'param' || name == 'embed' - return nil unless node.parent.name.to_s.downcase == 'object' + return nil unless parent.name.to_s.downcase == 'object' if name == 'param' - return nil unless movie_node = node.parent.search('param[@name="movie"]')[0] + return nil unless movie_node = parent.search('param[@name="movie"]')[0] url = movie_node['value'] elsif name == 'embed' url = node['src'] end - Sanitize.clean_node!(node.parent, { + return nil unless url && url =~ /^http:\/\/(?:www\.)?youtube\.com\/v\// + + Sanitize.clean_node!(parent, { :elements => ['embed', 'object', 'param'], :attributes => { 'embed' => ['allowfullscreen', 'allowscriptaccess', 'height', 'src', 'type', 'width'], @@ -328,24 +331,20 @@ describe 'transformers' do } }) - if url && url =~ /^http:\/\/(?:www\.)?youtube\.com\/v\// - return { - :whitelist_nodes => [node, node.parent] - } - end + {:whitelist_nodes => [node, parent]} end should 'allow youtube video embeds via the youtube transformer' do - input = '<div><object height="344" width="425"><param name="movie" value="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="344"></embed></object></div>' - output = Nokogiri::HTML::DocumentFragment.parse('<object height="344" width="425"><param name="movie" value="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="344"></embed></object>').to_xhtml(:encoding => 'utf-8', :indent => 0, :save_with => Nokogiri::XML::Node::SaveOptions::AS_XHTML) + input = '<div><object foo="bar" height="344" width="425"><b>test</b><param foo="bar" name="movie" value="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="344"></embed></object></div>' + output = Nokogiri::HTML::DocumentFragment.parse('<object height="344" width="425">test<param name="movie" value="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/a1Y73sPHKxw&hl=en&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="344"></embed></object>').to_xhtml(:encoding => 'utf-8', :indent => 0, :save_with => Nokogiri::XML::Node::SaveOptions::AS_XHTML) - Sanitize.clean!(input, :transformers => [youtube]).should.equal(output) + Sanitize.clean!(input, :transformers => youtube).should.equal(output) end should 'not allow non-youtube video embeds via the youtube transformer' do input = '<div><object height="344" width="425"><param name="movie" value="http://www.eviltube.com/v/a1Y73sPHKxw&hl=en&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.eviltube.com/v/a1Y73sPHKxw&hl=en&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="344"></embed></object></div>' output = '' - Sanitize.clean!(input, :transformers => [youtube]).should.equal(output) + Sanitize.clean!(input, :transformers => youtube).should.equal(output) end end test/spec_sanitize.rb c50099b28da11ab8dd0dbfe70b8bfc9cd9b17fd6 Ryan Grove ryan@wonko.com http://github.com/rgrove/sanitize/commit/3597b24156d0d2e347af2b999988a42ad6deffce 3597b24156d0d2e347af2b999988a42ad6deffce 2009-11-04T18:01:27-08:00 2009-11-04T18:01:27-08:00 Transformer refinements and (gasp!) documentation. 722c46a6311d57ecfa08421f4baf468cc7768d8d Ryan Grove ryan@wonko.com