elements.
:attributes => {
'div' => [:data]
}
```
#### :css (Hash)
Hash of the following CSS config settings to be used when sanitizing CSS (either
standalone or embedded in HTML).
##### :css => :allow_comments (boolean)
Whether or not to allow CSS comments. The default value is `false`.
##### :css => :allow_hacks (boolean)
Whether or not to allow browser compatibility hacks such as the IE `*` and `_`
hacks. These are generally harmless, but technically result in invalid CSS. The
default is `false`.
##### :css => :at_rules (Array or Set)
Names of CSS [at-rules][at-rules] to allow that may not have associated blocks,
such as `import` or `charset`. Names should be specified in lowercase.
[at-rules]:https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule
##### :css => :at_rules_with_properties (Array or Set)
Names of CSS [at-rules][at-rules] to allow that may have associated blocks
containing CSS properties. At-rules like `font-face` and `page` fall into this
category. Names should be specified in lowercase.
##### :css => :at_rules_with_styles (Array or Set)
Names of CSS [at-rules][at-rules] to allow that may have associated blocks
containing style rules. At-rules like `media` and `keyframes` fall into this
category. Names should be specified in lowercase.
##### :css => :properties (Array or Set)
Whitelist of CSS property names to allow. Names should be specified in
lowercase.
##### :css => :protocols (Array or Set)
URL protocols to allow in CSS URLs. Should be specified in lowercase.
If you'd like to allow the use of relative URLs which don't have a protocol,
include the symbol `:relative` in the protocol array.
#### :elements (Array or Set)
Array of HTML element names to allow. Specify all names in lowercase. Any
elements not in this array will be removed.
```ruby
:elements => %w[
a abbr b blockquote br cite code dd dfn dl dt em i kbd li mark ol p pre
q s samp small strike strong sub sup time u ul var
]
```
#### :protocols (Hash)
URL protocols to allow in specific attributes. If an attribute is listed here
and contains a protocol other than those specified (or if it contains no
protocol at all), it will be removed.
```ruby
:protocols => {
'a' => {'href' => ['ftp', 'http', 'https', 'mailto']},
'img' => {'src' => ['http', 'https']}
}
```
If you'd like to allow the use of relative URLs which don't have a protocol,
include the symbol `:relative` in the protocol array:
```ruby
:protocols => {
'a' => {'href' => ['http', 'https', :relative]}
}
```
#### :remove_contents (boolean or Array or Set)
If set to `true`, Sanitize will remove the contents of any non-whitelisted
elements in addition to the elements themselves. By default, Sanitize leaves the
safe parts of an element's contents behind when the element is removed.
If set to an array of element names, then only the contents of the specified
elements (when filtered) will be removed, and the contents of all other filtered
elements will be left behind.
The default value is `false`.
#### :transformers (Array or callable)
Custom HTML transformer or array of custom transformers. See the Transformers
section below for details.
#### :whitespace_elements (Hash)
Hash of element names which, when removed, should have their contents surrounded
by whitespace to preserve readability.
Each element name is a key pointing to another Hash, which provides the specific
whitespace that should be inserted `:before` and `:after` the removed element's
position. The `:after` value will only be inserted if the removed element has
children, in which case it will be inserted after those children.
```ruby
:whitespace_elements => {
'br' => { :before => "\n", :after => "" },
'div' => { :before => "\n", :after => "\n" },
'p' => { :before => "\n", :after => "\n" }
}
```
## Transformers
Transformers allow you to filter and modify HTML 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.
```ruby
Sanitize.fragment(html, :transformers => [
transformer_one,
transformer_two
])
```
### Input
Each 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 a 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.
### 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.
Sanitize performs top-down traversal, meaning that nodes are traversed in the
same order you'd read them in the HTML, starting at the top node, then its first
child, and so on.
```ruby
html = %[
]
transformer = lambda do |env|
puts env[:node_name] if env[:node].element?
end
# Prints "header", "span", "strong", "p", "footer".
Sanitize.fragment(html, :transformers => 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 image URLs by domain
The following example demonstrates how to remove image elements unless they use
a relative URL or are hosted on a specific domain. It assumes that the `
![]()
`
element and its `src` attribute are already whitelisted.
```ruby
require 'uri'
image_whitelist_transformer = lambda do |env|
# Ignore everything except
![]()
elements.
return unless env[:node_name] == 'img'
node = env[:node]
image_uri = URI.parse(node['src'])
# Only allow relative URLs or URLs with the example.com domain. The
# image_uri.host.nil? check ensures that protocol-relative URLs like
# "//evil.com/foo.jpg".
unless image_uri.host == 'example.com' || (image_uri.host.nil? && image_uri.relative?)
node.unlink # `Nokogiri::XML::Node#unlink` removes a node from the document
end
end
```
### Example: Transformer to whitelist YouTube video embeds
The following example demonstrates how to create a 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 `