is removed.
By default, the following elements are included in the
:whitespace_elements
array:
address article aside blockquote br dd div dl dt footer h1 h2 h3 h4 h5
h6 header hgroup hr li nav ol p pre section ul
=== Transformers
Transformers allow you to filter and modify nodes using your own custom logic,
on top of (or instead of) Sanitize's core filter. A transformer is any object
that responds to
call()
(such as a lambda or proc).
To use one or more transformers, pass them to the
:transformers
config setting. You may pass a single transformer or an array of transformers.
Sanitize.clean(html, :transformers => [transformer_one, transformer_two])
==== Input
Each registered transformer's
call()
method will be called once for
each node in the HTML (including elements, text nodes, comments, etc.), and will
receive as an argument an environment Hash that contains the following items:
[
:config
]
The current Sanitize configuration Hash.
[
:is_whitelisted
]
true
if the current node has been whitelisted by a previous
transformer,
false
otherwise. It's generally bad form to remove a
node that a previous transformer has whitelisted.
[
:node
]
A Nokogiri::XML::Node object representing an HTML node. The node may be an
element, a text node, a comment, a CDATA node, or a document fragment. Use
Nokogiri's inspection methods (
element?
,
text?
,
etc.) to selectively ignore node types you aren't interested in.
[
:node_name
]
The name of the current HTML node, always lowercase (e.g. "div" or "span").
For non-element nodes, the name will be something like "text", "comment",
"#cdata-section", "#document-fragment", etc.
[
:node_whitelist
]
Set of Nokogiri::XML::Node objects in the current document that have been
whitelisted by previous transformers, if any. It's generally bad form to
remove a node that a previous transformer has whitelisted.
[
:traversal_mode
]
Current node traversal mode, either
:depth
for depth-first (the
default mode) or
:breadth
for breadth-first.
==== Output
A transformer doesn't have to return anything, but may optionally return a Hash,
which may contain the following items:
[
:node_whitelist
]
Array or Set of specific Nokogiri::XML::Node objects to add to the document's
whitelist, bypassing the current Sanitize config. These specific nodes and all
their attributes will be whitelisted, but their children will not be.
If a transformer returns anything other than a Hash, the return value will be
ignored.
==== 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
document()
method. Any changes made to the current node or to the document 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. By
default, depth-first traversal is used, meaning that markup is traversed from
the deepest node upward (not from the first node to the last node):
html = '
foo
'
transformer = lambda{|env| puts env[:node_name] }
# Prints "text", "span", "div", "#document-fragment".
Sanitize.clean(html, :transformers => transformer)
You may use the
:transformers_breadth
config to specify one or more
transformers that should traverse nodes in breadth-first mode:
html = '
foo
'
transformer = lambda{|env| puts env[:node_name] }
# Prints "#document-fragment", "div", "span", "text".
Sanitize.clean(html, :transformers_breadth => transformer)
Transformers have a tremendous amount of power, including the power to
completely bypass Sanitize's built-in filtering. Be careful! Your safety is in
your own hands.
==== Example: Transformer to whitelist YouTube video embeds
The following example demonstrates how to create a depth-first Sanitize
transformer that will safely whitelist valid YouTube video embeds without having
to blindly allow other kinds of embedded content, which would be the case if you
tried to do this by just whitelisting all