Package org.sentrysoftware.maven.skin

Class HtmlTool

java.lang.Object
org.apache.velocity.tools.generic.SafeConfig
org.sentrysoftware.maven.skin.HtmlTool
@DefaultKey("htmlTool") public class HtmlTool extends org.apache.velocity.tools.generic.SafeConfig
An Apache Velocity tool that provides utility methods to manipulate HTML code using jsoup HTML5 parser.

The methods utilise CSS selectors to refer to specific elements for manipulation.

Since:
1.0
Author:
Bertrand Martin (originally inspired by Andrius Velykis)
See Also:

  • Field Summary

    Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

    LOCK_CONFIG_KEY, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

  • Constructor Summary

    Constructors
    Constructor
    Description
    HtmlTool()
    Create a new instance

  • Method Summary

    Modifier and Type
    Method
    Description
    org.jsoup.nodes.Element
    addClass(org.jsoup.nodes.Element body, String selector, String className)
    Adds given class to the elements in HTML.
    org.jsoup.nodes.Element
    addClass(org.jsoup.nodes.Element body, String selector, List<String> classNames)
    Adds given class names to the elements in HTML.
    org.jsoup.nodes.Element
    addClass(org.jsoup.nodes.Element body, String selector, List<String> classNames, int amount)
    Adds given class names to the elements in HTML.
    org.jsoup.nodes.Element
    append(org.jsoup.nodes.Element body, String selector, String appendHtml, int amount)
    Append HTML elements to specified elements in the given HTML.
    static List<String>
    concat(List<String> elements, String text, boolean append)
    Utility method to concatenate a String to a list of Strings.
    org.jsoup.nodes.Element
    ensureHeadingIds(org.jsoup.nodes.Element body)
    Transforms the given HTML content by adding IDs to all heading elements (h1-6) that do not have one.
    org.jsoup.nodes.Element
    fixIds(org.jsoup.nodes.Element body)
    Transforms the given HTML content to replace IDs that have symbols not allowed in CSS selectors, e.g.
    org.jsoup.nodes.Element
    fixProtocolRelativeUrls(org.jsoup.nodes.Element body)
    Replace all <a href="//..."> links with protocol-relative URLs with proper HTTPS URLs
    org.jsoup.nodes.Element
    fixTableHeads(org.jsoup.nodes.Element body)
    Fixes table heads: wraps rows with <th> (table heading) elements into <thead> element if they are currently in <tbody>.
    List<String>
    getAttr(org.jsoup.nodes.Element body, String selector, String attributeKey)
    Retrieves attribute value on elements in HTML.
    org.jsoup.nodes.Element
    headingAnchorToId(org.jsoup.nodes.Element body)
    Transforms the given HTML content by moving anchor (<a name="myheading">) names to IDs for heading elements.
    org.jsoup.nodes.Element
    parseContent(String content)
    Parses HTML fragment
    org.jsoup.nodes.Element
    prepend(org.jsoup.nodes.Element body, String selector, String prependHtml, int amount)
    Prepend HTML elements to specified elements in the given HTML.
    org.jsoup.nodes.Element
    remove(org.jsoup.nodes.Element body, String selector)
    Removes elements from HTML.
    org.jsoup.nodes.Element
    replace(org.jsoup.nodes.Element body, String selector, String replaceHtml, int amount)
    Replace selected elements with specified elements in the given HTML.
    org.jsoup.nodes.Element
    setAttr(org.jsoup.nodes.Element body, String selector, String attributeKey, String value)
    Sets attribute to the given value on elements in HTML.
    static String
    slug(String input)
    Creates a slug (latin text with no whitespace or other symbols) for a longer text (i.e.
    List<String>
    text(org.jsoup.nodes.Element body, String selector)
    Retrieves text content of the selected elements in HTML.
    org.jsoup.nodes.Element
    wrap(org.jsoup.nodes.Element body, String selector, String wrapHtml, int amount)
    Wraps elements in HTML with the given HTML.

    Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

    configure, isConfigLocked, isSafeMode

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • HtmlTool

      public HtmlTool()
      Create a new instance

  • Method Details

    • setAttr

      public org.jsoup.nodes.Element setAttr(org.jsoup.nodes.Element body, String selector, String attributeKey, String value)
      Sets attribute to the given value on elements in HTML.
      Parameters:
      body - HTML content to set attributes on
      selector - CSS selector for elements to modify
      attributeKey - Attribute name
      value - Attribute value
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.
      Since:
      1.0

    • parseContent

      public org.jsoup.nodes.Element parseContent(String content)
      Parses HTML fragment
      Parameters:
      content - HTML fragment to parse
      Returns:
      Element of the specified HTML fragment

    • getAttr

      public List<String> getAttr(org.jsoup.nodes.Element body, String selector, String attributeKey)
      Retrieves attribute value on elements in HTML. Will return all attribute values for the selector, since there can be more than one element.
      Parameters:
      body - HTML content to read attributes from
      selector - CSS selector for elements to find
      attributeKey - Attribute name
      Returns:
      Attribute values for all matching elements. If no elements are found, empty list is returned.
      Since:
      1.0

    • addClass

      public org.jsoup.nodes.Element addClass(org.jsoup.nodes.Element body, String selector, List<String> classNames, int amount)
      Adds given class names to the elements in HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements to add classes to
      classNames - Names of classes to add to the selected elements
      amount - Maximum number of elements to modify
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.
      Since:
      1.0

    • addClass

      public org.jsoup.nodes.Element addClass(org.jsoup.nodes.Element body, String selector, List<String> classNames)
      Adds given class names to the elements in HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements to add classes to
      classNames - Names of classes to add to the selected elements
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.
      Since:
      1.0

    • addClass

      public org.jsoup.nodes.Element addClass(org.jsoup.nodes.Element body, String selector, String className)
      Adds given class to the elements in HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements to add the class to
      className - Name of class to add to the selected elements
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.
      Since:
      1.0

    • wrap

      public org.jsoup.nodes.Element wrap(org.jsoup.nodes.Element body, String selector, String wrapHtml, int amount)
      Wraps elements in HTML with the given HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements to wrap
      wrapHtml - HTML to use for wrapping the selected elements
      amount - Maximum number of elements to modify
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.
      Since:
      1.0

    • append

      public org.jsoup.nodes.Element append(org.jsoup.nodes.Element body, String selector, String appendHtml, int amount)
      Append HTML elements to specified elements in the given HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements that will get the appendice
      appendHtml - HTML to append to the selected elements
      amount - Maximum number of elements to modify
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.

    • prepend

      public org.jsoup.nodes.Element prepend(org.jsoup.nodes.Element body, String selector, String prependHtml, int amount)
      Prepend HTML elements to specified elements in the given HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements that will get the "pre-pendice"
      prependHtml - HTML to prepend to the selected elements
      amount - Maximum number of elements to modify
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.

    • remove

      public org.jsoup.nodes.Element remove(org.jsoup.nodes.Element body, String selector)
      Removes elements from HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements to remove
      Returns:
      HTML content with removed elements. If no elements are found, the original content is returned.
      Since:
      1.0

    • replace

      public org.jsoup.nodes.Element replace(org.jsoup.nodes.Element body, String selector, String replaceHtml, int amount)
      Replace selected elements with specified elements in the given HTML.
      Parameters:
      body - HTML content to modify
      selector - CSS selector for elements that will get the appendice
      replaceHtml - HTML to append to the selected elements
      amount - Maximum number of elements to modify (-1 for unlimited)
      Returns:
      HTML content with modified elements. If no elements are found, the original content is returned.

    • text

      public List<String> text(org.jsoup.nodes.Element body, String selector)
      Retrieves text content of the selected elements in HTML. Renders the element's text as it would be displayed on the web page (including its children).
      Parameters:
      body - HTML content with the elements
      selector - CSS selector for elements to extract contents
      Returns:
      A list of element texts as rendered to display. Empty list if no elements are found.
      Since:
      1.0

    • headingAnchorToId

      public org.jsoup.nodes.Element headingAnchorToId(org.jsoup.nodes.Element body)
      Transforms the given HTML content by moving anchor (<a name="myheading">) names to IDs for heading elements.

      The anchors are used to indicate positions within a HTML page. In HTML5, however, the name attribute is no longer supported on <a>) tag. The positions within pages are indicated using id attribute instead, e.g. <h1 id="myheading">.

      The method finds anchors inside, immediately before or after the heading tags and uses their name as heading id instead. The anchors themselves are removed.

      Parameters:
      body - HTML content to modify
      Returns:
      HTML content with modified elements. Anchor names are used for adjacent headings, and anchor tags are removed. If no elements are found, the original content is returned.
      Since:
      1.0

    • concat

      public static List<String> concat(List<String> elements, String text, boolean append)
      Utility method to concatenate a String to a list of Strings. The text can be either appended or prepended.
      Parameters:
      elements - list of elements to append/prepend the text to
      text - the given text to append/prepend
      append - if true, text will be appended to the elements. If false, it will be prepended
      Returns:
      list of elements with the text appended/prepended
      Since:
      1.0

    • ensureHeadingIds

      public org.jsoup.nodes.Element ensureHeadingIds(org.jsoup.nodes.Element body)
      Transforms the given HTML content by adding IDs to all heading elements (h1-6) that do not have one.

      IDs on heading elements are used to indicate positions within a HTML page in HTML5. If a heading tag without an id is found, its "slug" is generated automatically based on the heading contents and used as the ID.

      Parameters:
      body - HTML content to modify
      Returns:
      HTML content with all heading elements having id attributes. If all headings were with IDs already, the original content is returned.
      Since:
      1.0

    • fixIds

      public org.jsoup.nodes.Element fixIds(org.jsoup.nodes.Element body)
      Transforms the given HTML content to replace IDs that have symbols not allowed in CSS selectors, e.g. ":", ".", etc. The symbols are removed.

      Naturally, the references to these IDs (in <a href="#my_id">) are also modified.

      Parameters:
      body - HTML content to modify
      Returns:
      HTML content fixed IDs.
      Since:
      1.0

    • fixTableHeads

      public org.jsoup.nodes.Element fixTableHeads(org.jsoup.nodes.Element body)
      Fixes table heads: wraps rows with <th> (table heading) elements into <thead> element if they are currently in <tbody>.
      Parameters:
      body - HTML content to modify
      Returns:
      HTML content with all table heads fixed. If all heads were correct, the original content is returned.
      Since:
      1.0

    • slug

      public static String slug(String input)
      Creates a slug (latin text with no whitespace or other symbols) for a longer text (i.e. to use in URLs). Uses "-" as a word separator.
      Parameters:
      input - The string (free) to be transformed into a valid element ID
      Returns:
      the proper slug

    • fixProtocolRelativeUrls

      public org.jsoup.nodes.Element fixProtocolRelativeUrls(org.jsoup.nodes.Element body)
      Replace all <a href="//..."> links with protocol-relative URLs with proper HTTPS URLs
      Parameters:
      body - HTML content to modify
      Returns:
      HTML content fixed linkss