Package com.vaadin.flow.component

Class Html

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.Html
All Implemented Interfaces:
AttachNotifier, DetachNotifier, HasElement, HasStyle, Serializable
public class Html extends Component
A component which encapsulates a given HTML fragment with a single root element.

Note that it is the developer's responsibility to sanitize and remove any dangerous parts of the HTML before sending it to the user through this component. Passing raw input data to the user will possibly lead to cross-site scripting attacks.

To help with sanitization, every HTML-accepting method has an overload that additionally takes a jsoup Safelist. These overloads run the content through Jsoup.clean(String, Safelist) before using it, so any element or attribute that the safelist doesn't permit is removed: 

 new Html(untrustedHtml, Safelist.basic());
The safelist must permit the fragment's single root element; otherwise the root is stripped and the resulting fragment no longer has exactly one root element.

This component does not expand the HTML fragment into a server side DOM tree so you cannot traverse or modify the HTML on the server. The root element can be accessed through Component.getElement() and the inner HTML through getInnerHtml().

The HTML fragment cannot be changed after creation. You should create a new instance to encapsulate another fragment.

Note that this component doesn't support svg element as a root node. See separate Svg component if you want to display SVG images.

Since:
1.0
Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • Html

      public Html(InputStream stream)
      Creates an instance based on the HTML fragment read from the stream. The fragment must have exactly one root element.

      A best effort is done to parse broken HTML but no guarantees are given for how invalid HTML is handled.

      Any heading or trailing whitespace is removed while parsing but any whitespace inside the root tag is preserved.

      Parameters:
      stream - the input stream which provides the HTML in UTF-8
      Throws:
      UncheckedIOException - if reading the stream fails

    • Html

      public Html(InputStream stream, org.jsoup.safety.Safelist safelist)
      Creates an instance based on the HTML fragment read from the stream, sanitized using the given Safelist. The fragment must have exactly one root element after sanitization.

      The content is run through Jsoup.clean(String, Safelist) before being used, so any element or attribute that the safelist doesn't permit is removed. The safelist must permit the root element.

      A best effort is done to parse broken HTML but no guarantees are given for how invalid HTML is handled.

      Any heading or trailing whitespace is removed while parsing but any whitespace inside the root tag is preserved.

      Parameters:
      stream - the input stream which provides the HTML in UTF-8
      safelist - the safelist of permitted elements and attributes, not null
      Throws:
      UncheckedIOException - if reading the stream fails

    • Html

      public Html(String outerHtml)
      Creates an instance based on the given HTML fragment. The fragment must have exactly one root element.

      A best effort is done to parse broken HTML but no guarantees are given for how invalid HTML is handled.

      Any heading or trailing whitespace is removed while parsing but any whitespace inside the root tag is preserved.

      Parameters:
      outerHtml - the HTML to wrap

    • Html

      public Html(String outerHtml, org.jsoup.safety.Safelist safelist)
      Creates an instance based on the given HTML fragment, sanitized using the given Safelist. The fragment must have exactly one root element after sanitization.

      The content is run through Jsoup.clean(String, Safelist) before being used, so any element or attribute that the safelist doesn't permit is removed. The safelist must permit the root element.

      A best effort is done to parse broken HTML but no guarantees are given for how invalid HTML is handled.

      Any heading or trailing whitespace is removed while parsing but any whitespace inside the root tag is preserved.

      Parameters:
      outerHtml - the HTML to wrap
      safelist - the safelist of permitted elements and attributes, not null

    • Html

      public Html(Signal<String> htmlSignal)
      Creates an instance based on the given HTML fragment signal. The signal's current value must have exactly one root element. Subsequent changes to the signal will update the component's content (root tag cannot be changed after creation).
      Parameters:
      htmlSignal - the signal that provides the HTML outer content
      Throws:
      IllegalArgumentException - if the signal is null or its current value is null or empty, or doesn't have exactly one root element

    • Html

      public Html(Signal<String> htmlSignal, org.jsoup.safety.Safelist safelist)
      Creates an instance based on the given HTML fragment signal, with every value sanitized using the given Safelist. The signal's current value must have exactly one root element after sanitization. Subsequent changes to the signal will update the component's content (root tag cannot be changed after creation).

      Both the initial value and every subsequent value are run through Jsoup.clean(String, Safelist), so any element or attribute that the safelist doesn't permit is removed. The safelist must permit the root element.

      Parameters:
      htmlSignal - the signal that provides the HTML outer content
      safelist - the safelist of permitted elements and attributes, not null
      Throws:
      IllegalArgumentException - if the signal is null or its current value is null or empty, or doesn't have exactly one root element

  • Method Details

    • setHtmlContent

      public void setHtmlContent(String html)
      Sets the content based on the given HTML fragment. The fragment must have exactly one root element, which matches the existing one.

      A best effort is done to parse broken HTML but no guarantees are given for how invalid HTML is handled.

      Any heading or trailing whitespace is removed while parsing but any whitespace inside the root tag is preserved.

      Parameters:
      html - the HTML to wrap

    • setHtmlContent

      public void setHtmlContent(String html, org.jsoup.safety.Safelist safelist)
      Sets the content based on the given HTML fragment, sanitized using the given Safelist. The fragment must have exactly one root element after sanitization, which matches the existing one.

      The content is run through Jsoup.clean(String, Safelist) before being used, so any element or attribute that the safelist doesn't permit is removed. The safelist must permit the root element.

      A best effort is done to parse broken HTML but no guarantees are given for how invalid HTML is handled.

      Any heading or trailing whitespace is removed while parsing but any whitespace inside the root tag is preserved.

      Parameters:
      html - the HTML to wrap
      safelist - the safelist of permitted elements and attributes, not null

    • getInnerHtml

      public String getInnerHtml()
      Gets the inner HTML, i.e. everything inside the root element.
      Returns:
      the inner HTML, not null

    • bindHtmlContent

      public SignalBinding<String> bindHtmlContent(Signal<String> htmlSignal)
      Binds a Signal's value to this component's HTML content (outer HTML). The content is set immediately with the current signal value when the binding is created, and is kept synchronized with any subsequent signal value changes while the component is attached. When the component is detached, signal value changes have no effect.

      While a Signal is bound to the HTML content, any attempt to set the HTML content manually via setHtmlContent(String) throws BindingActiveException. The same happens when trying to bind a new Signal while one is already bound.

      The first value of the signal must have exactly one root element. When updating the content, the root tag name must remain the same as the component's current root tag.

      Parameters:
      htmlSignal - the signal to bind, not null
      Throws:
      BindingActiveException - thrown when there is already an existing binding

    • bindHtmlContent

      public SignalBinding<String> bindHtmlContent(Signal<String> htmlSignal, org.jsoup.safety.Safelist safelist)
      Binds a Signal's value to this component's HTML content (outer HTML), sanitizing every value using the given Safelist. The content is set immediately with the current signal value when the binding is created, and is kept synchronized with any subsequent signal value changes while the component is attached. When the component is detached, signal value changes have no effect.

      Every value is run through Jsoup.clean(String, Safelist), so any element or attribute that the safelist doesn't permit is removed. The safelist must permit the root element.

      While a Signal is bound to the HTML content, any attempt to set the HTML content manually via setHtmlContent(String) throws BindingActiveException. The same happens when trying to bind a new Signal while one is already bound.

      The first value of the signal must have exactly one root element. When updating the content, the root tag name must remain the same as the component's current root tag.

      Parameters:
      htmlSignal - the signal to bind, not null
      safelist - the safelist of permitted elements and attributes, not null
      Throws:
      BindingActiveException - thrown when there is already an existing binding