com.bernardomg.velocity.tool.Html5UpdateTool Maven / Gradle / Ivy

Go to download
/**
 * The MIT License (MIT)
 * 
 * Copyright (c) 2015-2023 the original author or authors.
 * 

 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 

 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

package com.bernardomg.velocity.tool;

import java.util.Objects;

import org.apache.velocity.tools.config.DefaultKey;
import org.jsoup.nodes.Element;
import org.jsoup.parser.Tag;

/**
 * Utilities class for upgrading XHTML code to HTML5.
 * 

 * This was created for Maven Sites. These are built through Doxia which supports XHTML, and not HTML5, and so this
 * library generates outdated pages.
 * 

 * The various methods contained in this class aim to fix this problem, and will transform several known mistakes into
 * valid HTML5, but they won't transform the full page. The end user should make sure that the template being used,
 * probably a Maven Skin, matches expectations.
 * 

 * The Docs Maven Skin and its requirements have dictated
 * the development of this class. For more generic methods use the {@link com.bernardomg.velocity.tool.HtmlTool
 * HtmlTool}.
 *
 * @author Bernardo Martínez Garrido
 */
@DefaultKey("html5UpdateTool")
public class Html5UpdateTool {

    /**
     * Constructs an instance of the utilities class.
     */
    public Html5UpdateTool() {
        super();
    }

    /**
     * Removes the points from the contents of the specified attribute.
     *
     * @param root
     *            root element for the selection
     * @param selector
     *            CSS selector for the elements
     * @param attr
     *            attribute to clean
     * @return transformed element
     */
    public final Element removePointsFromAttr(final Element root, final String selector, final String attr) {
        final Iterable elements; // Elements to fix

        Objects.requireNonNull(root, "Received a null pointer as root element");
        Objects.requireNonNull(selector, "Received a null pointer as selector");
        Objects.requireNonNull(attr, "Received a null pointer as attribute");

        // Selects and iterates over the elements
        elements = root.select(selector);
        for (final Element selected : elements) {
            removePointsFromAttr(selected, attr);
        }

        return root;
    }

    /**
     * Corrects table headers by adding a {@code } section where missing.
     * 
     * This serves to fix an error with tables created by Doxia, which will add the header rows into the {@code }
     * element, instead on a {@code
     * } element.
     *
     * @param root
     *            root element with tables to fix
     * @return transformed element
     */
    public final Element updateTableHeads(final Element root) {
        final Iterable tableHeadRows; // Heads to fix
        Element                 table;         // HTML table
        Element                 thead;         // Table's head for wrapping

        Objects.requireNonNull(root, "Received a null pointer as root element");

        // Table rows with  tags in a 
        tableHeadRows = root.select("table > tbody > tr:has(th)");
        for (final Element row : tableHeadRows) {
            // Gets the row's table
            // The selector ensured the row is inside a tbody
            table = row.parent()
                .parent();

            // Removes the row from its original position
            row.remove();

            // Creates a table header element with the row
            thead = new Element(Tag.valueOf("thead"), "");
            thead.appendChild(row);
            // Adds the head at the beginning of the table
            table.prependChild(thead);
        }

        return root;
    }

    /**
     * Removes the points from the contents of the specified attribute.
     *
     * @param element
     *            element with the attribute to clean
     * @param attr
     *            attribute to clean
     */
    private final void removePointsFromAttr(final Element element, final String attr) {
        final String value; // Content of the attribute

        // Takes and clean the old attribute value
        value = element.attr(attr)
            .replace(".", "");

        // Sets the cleaned value
        element.attr(attr, value);
    }

}