iText7 7.1.8  Overview   Package   Class  Text Changes  Statistics  Help 
Generated by
JDiff
PREV PACKAGE    NEXT PACKAGE          FRAMES    NO FRAMES  

com.itextpdf.styledxmlparser.jsoup.safety Documentation Differences

This file contains all the changes in documentation in the package com.itextpdf.styledxmlparser.jsoup.safety as colored differences. Deletions are shown like this , and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a tag will cause all subsequent paragraphs to be displayed differently.
Class Cleaner

The whitelist based HTML cleaner. Use to ensure that end-user provided HTML contains only the elements and attributes that you are expecting; no junk, and no cross-site scripting attacks!

The HTML cleaner parses the input as HTML and then runs it through a white-list, so the output HTML can only contain HTML that is allowed by the whitelist.

It is assumed that the input HTML is a body fragment; the clean methods only pull from the source's body, and the canned white-lists only allow body contained tags.

Rather than interacting directly with a Cleaner object, generally see the {@code clean} methods in Jsoup.

Class Cleaner, constructor Cleaner(Whitelist)

Create a new cleaner, that sanitizes documents using the supplied whitelist. @param whitelist white-list to clean with
Class Cleaner, Document clean(Document)

Creates a new, clean document, from the original dirty document, containing only elements allowed by the whitelist. The original document is not modified. Only elements from the dirt document's body are used. @param dirtyDocument Untrusted base document to clean. @return cleaned document.
Class Cleaner, boolean isValid(Document)

Determines if the input document is valid, against the whitelist. It is considered valid if all the tags and attributes in the input HTML are allowed by the whitelist.

This method can be used as a validator for user input forms. An invalid document will still be cleaned successfully using the .clean(Document) document. If using as a validator, it is recommended to still clean the document to ensure enforced attributes are set correctly, and that the output is tidied. @param dirtyDocument document to test @return true if no tags or attributes need to be removed; false if they do

Class Whitelist

Whitelists define what HTML (elements and attributes) to allow through the cleaner. Everything else is removed.

Start with one of the defaults:

If you need to allow more through (please be careful!), tweak a base whitelist with: You can remove any setting from an existing whitelist with: The cleaner and these whitelists assume that you want to clean a body fragment of HTML (to add user supplied HTML into a templated page), and not to clean a full HTML document. If the latter is the case, either wrap the document HTML around the cleaned body HTML, or create a whitelist that allows html and head elements as appropriate.

If you are going to extend a whitelist, please be very careful. Make sure you understand what attributes may lead to XSS attack vectors. URL attributes are particularly vulnerable and require careful validation. See See http://ha.ckers.org/xss.html for some XSS attack examples. @author Jonathan Hedley

Class Whitelist, constructor Whitelist()

Create a new, empty whitelist. Generally it will be better to start with a default prepared whitelist instead. @see #basic() @see #basicWithImages() @see #simpleText() @see #relaxed()
Class Whitelist, Whitelist addAttributes(String, String[])

Add a list of allowed attributes to a tag. (If an attribute is not allowed on an element, it will be removed.)

E.g.: addAttributes("a", "href", "class") allows href and class attributes on a tags.

To make an attribute valid for all tags, use the pseudo tag :all, e.g. addAttributes(":all", "class"). @param tag The tag the attributes are for. The tag will be added to the allowed tag list if necessary. @param keys List of valid attributes for the tag @return this (for chaining)

Class Whitelist, Whitelist addEnforcedAttribute(String, String, String)

Add an enforced attribute to a tag. An enforced attribute will always be added to the element. If the element already has the attribute set, it will be overridden.

E.g.: addEnforcedAttribute("a", "rel", "nofollow") will make all a tags output as @param tag The tag the enforced attribute is for. The tag will be added to the allowed tag list if necessary. @param key The attribute key @param value The enforced attribute value @return this (for chaining)

Class Whitelist, Whitelist addProtocols(String, String, String[])

Add allowed URL protocols for an element's URL attribute. This restricts the possible values of the attribute to URLs with the defined protocol.

E.g.: addProtocols("a", "href", "ftp", "http", "https")

To allow a link to an in-page URL anchor (i.e. , add a #:
E.g.: addProtocols("a", "href", "#") @param tag Tag the URL protocol is for @param key Attribute key @param protocols List of valid protocols @return this, for chaining

Class Whitelist, Whitelist addTags(String[])

Add a list of allowed elements to a whitelist. (If a tag is not allowed, it will be removed from the HTML.) @param tags tag names to allow @return this (for chaining)
Class Whitelist, Whitelist basic()

This whitelist allows a fuller range of text nodes: a, b, blockquote, br, cite, code, dd, dl, dt, em, i, li, ol, p, pre, q, small, span, strike, strong, sub, sup, u, ul, and appropriate attributes.

Links (a elements) can point to http, https, ftp, mailto, and have an enforced rel=nofollow attribute.

Does not allow images. @return whitelist

Class Whitelist, Whitelist basicWithImages()

This whitelist allows the same text tags as .basic, and also allows img tags, with appropriate attributes, with src pointing to http or https. @return whitelist
Class Whitelist, Whitelist none()

This whitelist allows only text nodes: all HTML will be stripped. @return whitelist
Class Whitelist, Whitelist preserveRelativeLinks(boolean)

Configure this Whitelist to preserve relative links in an element's URL attribute, or convert them to absolute links. By default, this is false: URLs will be made absolute (e.g. start with an allowed protocol, like e.g. {@code http://}.

Note that when handling relative links, the input document must have an appropriate {@code base URI} set when parsing, so that the link's protocol can be confirmed. Regardless of the setting of the {@code preserve relative links} option, the link must be resolvable against the base URI to an allowed protocol; otherwise the attribute will be removed. @param preserve {@code true} to allow relative links, {@code false} (default) to deny @return this Whitelist, for chaining. @see #addProtocols

Class Whitelist, Whitelist relaxed()

This whitelist allows a full range of text and structural body HTML: a, b, blockquote, br, caption, cite, code, col, colgroup, dd, div, dl, dt, em, h1, h2, h3, h4, h5, h6, i, img, li, ol, p, pre, q, small, span, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, u, ul

Links do not have an enforced rel=nofollow attribute, but you can add that if desired. @return whitelist

Class Whitelist, Whitelist removeAttributes(String, String[])

Remove a list of allowed attributes from a tag. (If an attribute is not allowed on an element, it will be removed.)

E.g.: removeAttributes("a", "href", "class") disallows href and class attributes on a tags.

To make an attribute invalid for all tags, use the pseudo tag :all, e.g. removeAttributes(":all", "class"). @param tag The tag the attributes are for. @param keys List of invalid attributes for the tag @return this (for chaining)

Class Whitelist, Whitelist removeEnforcedAttribute(String, String)

Remove a previously configured enforced attribute from a tag. @param tag The tag the enforced attribute is for. @param key The attribute key @return this (for chaining)
Class Whitelist, Whitelist removeProtocols(String, String, String[])

Remove allowed URL protocols for an element's URL attribute.

E.g.: removeProtocols("a", "href", "ftp") @param tag Tag the URL protocol is for @param key Attribute key @param protocols List of invalid protocols @return this, for chaining

Class Whitelist, Whitelist removeTags(String[])

Remove a list of allowed elements from a whitelist. (If a tag is not allowed, it will be removed from the HTML.) @param tags tag names to disallow @return this (for chaining)
Class Whitelist, Whitelist simpleText()

This whitelist allows only simple text formatting: b, em, i, strong, u. All other HTML (tags and attributes) will be removed. @return whitelist