HTMLTextTools (MyTISM API Documentation)

java.lang.Object
- de.ipcon.tools.HTMLTextTools

```
public final class HTMLTextTools
extends java.lang.Object
```
This class provides utility methods for handling and manipulating text in the context of HTML.
It includes methods for:
- Escaping HTML entities to prevent cross-site scripting (XSS) vulnerabilities or HTML rendering.
- Converting HTML to plain text by removing tags and special characters.
- Stripping specific or all HTML tags from a string.
These methods are useful for safely displaying user-generated content, processing HTML input, and converting between HTML and plain text formats.

Field Summary

Fields
Modifier and Type	Field and Description
`static org.apache.log4j.Logger`	`log`
`static java.util.regex.Pattern`	`PATTERN_HTML_MESSAGE` Regular expression to match a string that starts with "<html>" and ends with "</html>", possibly with leading or trailing whitespace and content after the closing tag.
`static java.util.regex.Pattern`	`PATTERN_HTML_TAG` Compiled `Pattern` object for `PATTERN_HTML_TAG_STRING`.
`static java.lang.String`	`PATTERN_HTML_TAG_STRING` Regular expression to match any HTML tag, capturing the tag name in group 1.

Constructor Summary

Constructors
Constructor and Description

HTMLTextTools()

Constructors
Constructor and Description
`HTMLTextTools()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static java.lang.String`	`colorToHTML(java.awt.Color color)` Converts a `Color` object to its HTML hexadecimal color code representation.
`static java.lang.String`	`convertForHTMLInclusion(java.lang.String str)` Converts the given String `str` into a format suitable for inclusion in HTML messages.
`static java.lang.String`	`convertHTMLtoText(java.lang.String str)` Converts HTML to plain text by removing HTML tags, style elements, and converting special characters.
`static java.lang.String`	`disableHTML(java.lang.String str)` Escapes HTML tags in the given string by replacing '<' with "<" and '>' with ">".
`static java.lang.String`	`getColoredHtmlForValue(java.math.BigDecimal value, java.math.BigDecimal upperThreshold, java.math.BigDecimal lowerThreshold, java.lang.String valueFormatted)` Generates an HTML snippet for displaying a value with a foreground color interpolated between green, a darker yellow, and a brighter red based on the provided thresholds.
`static java.lang.String`	`getColoredHtmlForValue(java.math.BigDecimal value, java.math.BigDecimal upperThreshold, java.math.BigDecimal lowerThreshold, java.lang.String valueFormatted, ColorMode colorMode)` Generates an HTML snippet for displaying a value with a foreground color interpolated based on the provided thresholds and a specified color mode.
`static java.lang.String`	`replaceHtmlEntities(java.lang.String str)` Replaces characters with special meaning in HTML with the corresponding entities using a StringBuilder for efficiency.
`static java.lang.String`	`stripHTML(java.lang.String str)` Removes all HTML tags from the given string.
`static java.lang.String`	`stripHTMLTags(java.lang.String str, java.util.Collection<java.lang.String> tagNamesToRemove)` Removes specific HTML tags from a given string.
`static java.lang.String`	`stripHTMLTagsExcept(java.lang.String str, java.util.Collection<java.lang.String> tagNamesToKeep)` Removes all HTML tags from a string except for those specified in a collection.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - log
```
public static final org.apache.log4j.Logger log
```
  - PATTERN_HTML_TAG_STRING
```
public static final java.lang.String PATTERN_HTML_TAG_STRING
```
    Regular expression to match any HTML tag, capturing the tag name in group 1.
    This regex is case-insensitive and matches tags with or without a closing slash. It captures the tag name (e.g., "div", "span", "p") in the first capturing group. It does *not* match self-closing tags (e.g., <img/>). It is primarily intended for use in identifying and extracting tag names, not for robust HTML parsing.
    
    The regex breakdown is as follows:
    - (?i): Enables case-insensitive matching.
    - \\</?: Matches an optional closing slash ("/"). This allows matching both opening tags (e.g., <div>) and closing tags (e.g., </div>).
    - (\\w+): Matches one or more word characters (letters, numbers, and underscore). This represents the tag name and is captured in group 1.
    - \\s*: Matches zero or more whitespace characters. This allows for spaces around the tag name.
    - (?:[^\\>]\*\>): Matches the rest of the tag, including attributes.
      
      (?: ... ): This is a non-capturing group. We don't need to capture the attributes, just match them.
      
      [^\\>]*: Matches zero or more characters that are *not* a closing angle bracket (>). This allows for attributes within the tag.
      
      \\>: Matches the closing angle bracket (>).
    **Important Considerations:** This regex is a simplified approach and should *not* be used for robust HTML parsing. Parsing HTML with regular expressions can be complex and error-prone, especially with malformed or nested HTML. For reliable HTML parsing, consider using a dedicated HTML parser library.
    See Also:
    
    Constant Field Values
  - PATTERN_HTML_TAG
```
public static final java.util.regex.Pattern PATTERN_HTML_TAG
```
    Compiled Pattern object for PATTERN_HTML_TAG_STRING. Pre-compiling the pattern improves performance when it is used repeatedly.
  - PATTERN_HTML_MESSAGE
```
public static final java.util.regex.Pattern PATTERN_HTML_MESSAGE
```
    Regular expression to match a string that starts with "<html>" and ends with "</html>", possibly with leading or trailing whitespace and content after the closing tag.
    The regex is designed to capture the HTML content within the tags (group 1) and any content that follows the closing tag (group 2). It uses the following features:
    - (?s): Enables DOTALL mode, making the dot (.) match any character, including newline characters. This is essential for matching HTML content that spans multiple lines.
    - \\s*: Matches zero or more whitespace characters. This handles leading and trailing whitespace around the <html> tags and the trailing content.
    - <html>: Matches the literal start tag <html>.
    - (.*): Captures any characters (including newlines due to DOTALL mode) between the opening and closing HTML tags. This is the HTML content (group 1).
    - </html>: Matches the literal closing tag </html>.
    - (.*): Captures any characters following the closing HTML tag (including newlines due to DOTALL mode). This is the trailing content (group 2).
    - \\s*: Matches zero or more whitespace characters after the trailing content.
    This pattern allows for flexible matching of HTML strings, even if they have extra text outside the <html> tags.
- Constructor Detail
  - HTMLTextTools
```
public HTMLTextTools()
```
- Method Detail
  - convertForHTMLInclusion
```
public static final java.lang.String convertForHTMLInclusion(java.lang.String str)
```
    Converts the given String str into a format suitable for inclusion in HTML messages. This method handles cases where the string already contains HTML tags and replaces line breaks in trailing content with <br/> tags. If the string does not contain HTML tags, it replaces HTML entities to ensure proper rendering.
    **Handling HTML Content:** If str starts with "<html>" and contains "</html>" after that, the content between these tags is extracted. Trailing content after the closing "</html>" tag is appended to the result. Line breaks within the extracted trailing content are replaced with "<br/>" and the replaceHtmlEntities(String) method is called to replace HTML entities. This allows for mixed HTML and non-HTML content in messages, without corrupting the structure of the final HTML content.
    
    **Handling Non-HTML Content:** If str does *not* match the HTML pattern, the replaceHtmlEntities(String) method is called to replace HTML entities. This converts characters like <, >, &, and others into their corresponding HTML entities (< > &), ensuring correct rendering in the client.
    
    Parameters:
    
    str - The string to convert.
    
    Returns:
    
    The converted string, or null if the input is null.
  - replaceHtmlEntities
```
public static final java.lang.String replaceHtmlEntities(java.lang.String str)
```
    Replaces characters with special meaning in HTML with the corresponding entities using a StringBuilder for efficiency.
    
    Parameters:
    
    str - String to escape
    
    Returns:
    
    String with escaped HTML entities
  - disableHTML
```
public static final java.lang.String disableHTML(java.lang.String str)
```
    Escapes HTML tags in the given string by replacing '<' with "<" and '>' with ">".
    This method prevents HTML tags from being interpreted by the browser. It should be called before displaying the string in an HTML context, especially when the string originates from user input or other untrusted sources.
    
    Parameters:
    
    str - the string to escape, may be null
    
    Returns:
    
    the escaped string with '<' and '>' replaced by their respective entities, or null if the input is null
  - stripHTML
```
public static final java.lang.String stripHTML(java.lang.String str)
```
    Removes all HTML tags from the given string.
    This method uses a regular expression to identify and remove any text enclosed within '<' and '>'. It effectively strips all HTML tags from the input string.
    
    Parameters:
    
    str - the input string, may be null
    
    Returns:
    
    the input string with all HTML tags removed, or null if the input is null
  - convertHTMLtoText
```
public static final java.lang.String convertHTMLtoText(java.lang.String str)
```
    Converts HTML to plain text by removing HTML tags, style elements, and converting special characters.
    This method performs the following transformations:
    - Removes all style elements and their content.
    - Strips all HTML tags except for "br" tags.
    - Converts "br" tags to line feed characters (\n).
    - Replaces non-breaking spaces ( ) with regular spaces.
    Parameters:
    
    str - the input string containing HTML content, may be null
    
    Returns:
    
    the plain text representation of the input string, or null if the input is null
  - stripHTMLTags
```
public static final java.lang.String stripHTMLTags(java.lang.String str,
                                                   java.util.Collection<java.lang.String> tagNamesToRemove)
```
    Removes specific HTML tags from a given string.
    This method identifies and removes HTML tags specified in the tagNamesToRemove collection. It performs a case-insensitive comparison of tag names and removes the entire tag, including any attributes.
    
    Parameters:
    
    str - the input string containing HTML content, may be null
    
    tagNamesToRemove - a collection of tag names to be removed, may be null or empty
    
    Returns:
    
    the input string with the specified HTML tags removed, or the original string if no tags are tagNamesToRemove or the input is null
  - stripHTMLTagsExcept
```
public static final java.lang.String stripHTMLTagsExcept(java.lang.String str,
                                                         java.util.Collection<java.lang.String> tagNamesToKeep)
```
    Removes all HTML tags from a string except for those specified in a collection.
    This method identifies all HTML tags in the input string and removes any tag that is not present in the tagNamesToKeep collection. The comparison of tag names is case-insensitive.
    If the tagNamesToKeep collection is null, no tags are removed. To remove all tags, use an empty collection or the stripHTML(String) method.
    
    Parameters:
    
    str - the input string containing HTML content, may be null
    
    tagNamesToKeep - a collection of tag names to be kept, may be null
    
    Returns:
    
    the input string with all HTML tags removed except those specified in tagNamesToKeep, or the original string if tagNamesToKeep is null, or null if str is null
  - colorToHTML
```
public static final java.lang.String colorToHTML(java.awt.Color color)
```
    Converts a Color object to its HTML hexadecimal color code representation.
    
    Parameters:
    
    color - The Color object to convert.
    
    Returns:
    
    The HTML hexadecimal color code (e.g., "#ff8c00").
  - getColoredHtmlForValue
```
public static java.lang.String getColoredHtmlForValue(java.math.BigDecimal value,
                                                      java.math.BigDecimal upperThreshold,
                                                      java.math.BigDecimal lowerThreshold,
                                                      java.lang.String valueFormatted)
```
    Generates an HTML snippet for displaying a value with a foreground color interpolated between green, a darker yellow, and a brighter red based on the provided thresholds.
    This method visually represents evaluation results within a defined range using a standard red-yellow-green gradient:
    - At or below the lowerThreshold: Fully green.
    - In the lower part of the range: Rapid transition from green towards yellow.
    - Around the midpoint between lowerThreshold and upperThreshold: Darker, more visible yellow.
    - In the upper part of the range: Transition from yellow to brighter red.
    - At or above the upperThreshold: Brighter red.
    Parameters:
    
    value - The numerical value to display and use for color scaling.
    
    upperThreshold - The threshold at which the color will be "fully red".
    
    lowerThreshold - The threshold at which the color will be "fully green" (defaults to zero if null).
    
    valueFormatted - An optional String to display instead of the raw value. If null, the value is formatted using the default locale.
    
    Returns:
    
    An HTML snippet that uses a foreground color interpolated between green, darker yellow, and brighter red within the given thresholds, suitable for use in HTML elements like Labels. Returns " - " if the input value is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the upperThreshold is null or not greater than the lowerThreshold.
  - getColoredHtmlForValue
```
public static java.lang.String getColoredHtmlForValue(java.math.BigDecimal value,
                                                      java.math.BigDecimal upperThreshold,
                                                      java.math.BigDecimal lowerThreshold,
                                                      java.lang.String valueFormatted,
                                                      ColorMode colorMode)
```
    Generates an HTML snippet for displaying a value with a foreground color interpolated based on the provided thresholds and a specified color mode.
    This method visually represents evaluation results within a defined range using either a standard red-yellow-green gradient or a colorblind-friendly blue-yellow-orange gradient.
    
    Standard Color Mode:
    - At or below the lowerThreshold: Fully green.
    - In the lower part of the range: Rapid transition from green towards yellow.
    - Around the midpoint between lowerThreshold and upperThreshold: Darker, more visible yellow.
    - In the upper part of the range: Transition from yellow to brighter red.
    - At or above the upperThreshold: Brighter red.
    Colorblind-Friendly Mode:
    - At or below the lowerThreshold: Fully blue.
    - In the lower part of the range: Rapid transition from blue towards a darker yellow.
    - Around the midpoint between lowerThreshold and upperThreshold: Dark yellow.
    - In the upper part of the range: Transition from darker yellow to orange.
    - At or above the upperThreshold: Orange.
    Parameters:
    
    value - The numerical value to display and use for color scaling.
    
    upperThreshold - The threshold at which the color will be "fully red" (standard) or "fully orange" (colorblind-friendly).
    
    lowerThreshold - The threshold at which the color will be "fully green" (standard) or "fully blue" (colorblind-friendly) (defaults to zero if null).
    
    valueFormatted - An optional String to display instead of the raw value. If null, the value is formatted using the default locale.
    
    colorMode - The color mode to use for the interpolation (standard or colorblind-friendly).
    
    Returns:
    
    An HTML snippet that uses a foreground color interpolated within the given thresholds and color mode, suitable for use in HTML elements like Labels. Returns " - " if the input value is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the upperThreshold is null or not greater than the lowerThreshold.

Class HTMLTextTools

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

PATTERN_HTML_TAG_STRING

PATTERN_HTML_TAG

PATTERN_HTML_MESSAGE

Constructor Detail

HTMLTextTools

Method Detail

convertForHTMLInclusion

replaceHtmlEntities

disableHTML

stripHTML

convertHTMLtoText

stripHTMLTags

stripHTMLTagsExcept

colorToHTML

getColoredHtmlForValue

getColoredHtmlForValue