Adicionar dicas de ferramentas no WordPress sem plugins

As dicas de ferramentas prejudicam ou beneficiam a SEO?

O termo tooltip não tem uma tradução única para inglês, podendo ser descrito como "dica de ferramenta", "balão de ajuda", "descrição pop-up" ou mesmo "texto de ajuda", consoante o contexto em que é utilizado.

Uma dica de ferramenta é uma mensagem pop-up que aparece quando se interage com um elemento, quer clicando nele quer passando o rato por cima dele. Estas dicas de ferramentas são utilizadas para fornecer informações adicionais sem ocupar espaço permanente. Ideal para explicar ícones, termos técnicos ou acções em interfaces.

As dicas de ferramentas prejudicam ou beneficiam a SEO?

Bem, como para quase tudo, a resposta é sempre "depende". Embora os puristas de SEO alertem para o facto de o Google não gostar de conteúdos "escondidos" ou mascarados e penalizar severamente a sua utilização, isto seria um extremo para casos de abuso que poderiam "canibalizar" o seu conteúdo. No entanto, as tooltips, utilizadas com um certo equilíbrio e um mínimo de lógica, podem ser benéficas.

Vantagens da utilização de dicas de ferramentas

Em termos gerais, estas mensagens, se forem amigáveis e discretas, podem contribuir para melhorar diferentes aspectos da experiência do utilizador. Entre outras coisas, reduzem as taxas de rejeição e melhoram a acessibilidade. Podem também proporcionar oportunidades para utilizar palavras-chave adicionais que não se enquadram naturalmente no conteúdo principal, o que ajuda na SEO semântica.

Além disso, podem melhorar as taxas de cliques. Ao oferecerem dicas de ferramentas na navegação ou botões de chamada para ação, podem orientar os utilizadores de forma mais eficaz, conduzindo a taxas de cliques mais elevadas. Mas para que tudo isto seja possível, devem ser seguidas algumas diretrizes mínimas.

Recomendações relativas ao aspeto, conteúdo e funcionamento

Utilização de elementos HTML e atributos ARIA para garantir que os leitores de ecrã e os motores de busca possam aceder às informações que contêm.
Uma dica de ferramenta deve ser breve. Obviamente, ninguém vai ler uma grande quantidade de informação num banner pop-up e, além disso, estará a cobrir uma grande parte do conteúdo. Deve conter a informação mínima, precisa e necessária, e esta não deve ser crítica para o utilizador ao realizar ou completar qualquer ação.
O conteúdo não deve ser redundante ou repetido. Certifique-se de que está a fornecer informações adicionais úteis e necessárias e de que estas não são repetidas no seu conteúdo para evitar "conteúdo duplicado".
Tente evitar ao máximo as dicas de ferramentas que desaparecem quando se move o cursor ou utilize-as apenas em mensagens que não contenham muita informação e/ou conteúdo. Idealmente, devem ser apresentadas por clique e fechadas quando se clica novamente em qualquer parte do ecrã.
Certifique-se de que são legíveis e de que têm o tamanho correto.
Não adicione vinte designs diferentes de ícones de dicas de ferramentas ou de links de dicas de ferramentas, pois isso só cria confusão. Um design fixo e consistente ajudará os seus visitantes a identificá-los à primeira vista.
Não exagere, planeie bem a sua estratégia para os adicionar apenas quando considerar que facilitam o acesso a informações complementares relevantes e/ou necessárias.

Caraterísticas e funcionalidades do código

Para este caso, foi utilizada esta imagem.png com fundo transparente.

Aqui pode testar o resultado final a funcionar [tooltip text="Exemplo de tooltip utilizado em jrmora.com" position="auto"].

O URL da imagem é adicionado entre as aspas simples nesta linha:

$default_image = 'URL-de-tu-imagen';

Se optar por modificar o código para utilizar um ícone SVG HTML, como este, poderá brincar mais facilmente com a cor, o fundo, a espessura, etc.

Ajuste automático inteligente da posição para evitar as margens do ecrã. Ou seja, quando se aproxima da margem superior, a dica de ferramenta é apresentada na parte inferior e vivecersa.

Podem ser adicionadas hiperligações totalmente funcionais na dica de ferramenta com estilos personalizáveis. Embora não seja aconselhável adicionar hiperligações, é possível que tenha de o fazer ocasionalmente. No caso de uma dica de ferramenta conter um link, há um atraso de 200ms na ocultação automática para facilitar o clique.

Suporte HTML seguro. Suporta:

<strong>, <em>, <a>, <br>, <span>

Posição, atributos fixos e adaptáveis.

Atributos de posición disponibles:  position="auto" (default), top, bottom, left, right

Atributos ARIA (aria-expanded, role="tooltip").

Conceção reactiva.

Adaptável a telemóveis (alternância clicável).

Reposição ao redimensionar, rodar ou deslocar

Principais classes CSS:

.tooltip-container /* Contenedor principal */
.tooltip-trigger  /* Botón/icono que activa el tooltip */
.tooltip          /* Caja del mensaje emergente */
.tooltip-arrow    /* Flecha indicadora */

Principais funções do JS:

calculateBestPosition() // Determina si colocar el tooltip arriba, abajo, etc.
showTooltip()          // Muestra el tooltip
hideTooltip()          // Oculta el tooltip con retraso

Exemplos de shortcodes:

[tooltip text="Texto a mostrar"] 

[tooltip text="Texto a mostrar <strong>en negrita</strong> donde sea" position="auto"] 

[tooltip text="Texto <strong>importante</strong> y <em>énfasis</em>"]

[tooltip text="<a href='https://ejemplo.com' target='_blank'>Visite nuestro sitio</a>"]

Este código é o que utilizei para as minhas necessidades específicas. Entenda-o como um ponto de partida. É muito suscetível de ser melhorado. Pode separar o CSS e o JS (ou mesmo considerá-lo sem utilizar o Javascript) e adaptá-lo para que também possa ser aplicado a palavras no conteúdo sem mostrar o ícone.

Para o utilizar, como sempre, basta adicioná-lo ao functions.php do seu modelo ou do seu tema filho se quiser manter as alterações quando o seu modelo for atualizado.

Código

/**
 * Shortcode para tooltip con ajuste automático 
 * Un ejemplo de uso: [tooltip text="Texto <a href='#'>enlace</a>" position="auto"]
 */
function custom_tooltip_shortcode($atts) {
    $default_image = 'URL-de-tu-imagen';
    
    $atts = shortcode_atts(
        array(
            'text' => __('Información adicional', 'text-domain'),
            'position' => 'auto',
            'color' => '#6a0000',
            'shadow' => '#9c9c9c',
            'width' => '18px',
            'id' => 'tooltip-' . uniqid()
        ),
        $atts,
        'tooltip'
    );

    // HTML permitido
    $allowed_html = array(
        'strong' => array(),
        'b' => array(),
        'em' => array(),
        'i' => array(),
        'br' => array(),
        'span' => array(
            'style' => array(),
            'class' => array()
        ),
        'a' => array(
            'href' => array(),
            'title' => array(),
            'target' => array(),
            'style' => array(),
            'rel' => array()
        )
    );
    
    $text = wp_kses($atts['text'], $allowed_html);
    $position = in_array($atts['position'], ['top', 'bottom', 'left', 'right', 'auto']) ? $atts['position'] : 'auto';
    $color = sanitize_hex_color($atts['color']);
    $shadow = sanitize_hex_color($atts['shadow']);
    $width = esc_attr($atts['width']);
    $id = sanitize_html_class($atts['id']);

    $output = '
    <span class="tooltip-container" data-position="' . esc_attr($position) . '">
        <button class="tooltip-trigger" aria-describedby="' . $id . '" aria-expanded="false">
            <img src="' . esc_url($default_image) . '" width="' . $width . '" alt="" aria-hidden="true"/>
        </button>
        <span id="' . $id . '" role="tooltip" class="tooltip" style="background-color: ' . $color . '; box-shadow: 0 5px 10px ' . $shadow . ';">
            ' . $text . '
            <span class="tooltip-arrow"></span>
        </span>
    </span>';

    return $output;
}
add_shortcode('tooltip', 'custom_tooltip_shortcode');

/**
 * Estilos CSS optimizados para enlaces
 */
function add_tooltip_styles() {
    echo '
    <style>
    .tooltip-container {
        display: inline-block;
        position: relative;
        vertical-align: middle;
    }

    .tooltip-trigger {
        background: none;
        border: none;
        padding: 0;
        margin: 0 2px;
        cursor: pointer;
        line-height: 1;
    }

    .tooltip {
        position: absolute;
        color: #fff;
        padding: 10px 12px;
        border-radius: 4px;
        font-size: 14px;
        line-height: 1.5;
        width: 220px;
        max-width: 90vw;
        text-align: left;
        visibility: hidden;
        opacity: 0;
        transition: opacity 0.25s ease;
        z-index: 100000;
        pointer-events: none;
    }

    .tooltip a {
        color: #fff !important;
        text-decoration: underline;
        pointer-events: auto !important;
    }

    .tooltip * {
        pointer-events: auto;
    }

    .tooltip-arrow {
        position: absolute;
        width: 0;
        height: 0;
        border: 7px solid transparent;
    }

    /* Posiciones dinámicas */
    .tooltip[data-position="top"] {
        bottom: 100%;
        left: 50%;
        transform: translateX(-50%);
        margin-bottom: 10px;
    }
    .tooltip[data-position="top"] .tooltip-arrow {
        top: 100%;
        left: 50%;
        transform: translateX(-50%);
        border-top-color: inherit;
    }

    .tooltip[data-position="bottom"] {
        top: 100%;
        left: 50%;
        transform: translateX(-50%);
        margin-top: 10px;
    }
    .tooltip[data-position="bottom"] .tooltip-arrow {
        bottom: 100%;
        left: 50%;
        transform: translateX(-50%);
        border-bottom-color: inherit;
    }

    .tooltip[data-position="left"] {
        top: 50%;
        right: 100%;
        transform: translateY(-50%);
        margin-right: 10px;
    }
    .tooltip[data-position="left"] .tooltip-arrow {
        top: 50%;
        right: 0;
        transform: translate(50%, -50%);
        border-left-color: inherit;
    }

    .tooltip[data-position="right"] {
        top: 50%;
        left: 100%;
        transform: translateY(-50%);
        margin-left: 10px;
    }
    .tooltip[data-position="right"] .tooltip-arrow {
        top: 50%;
        left: 0;
        transform: translate(-50%, -50%);
        border-right-color: inherit;
    }

    /* Interacción */
    .tooltip-trigger:hover + .tooltip,
    .tooltip-trigger:focus + .tooltip,
    .tooltip-trigger[aria-expanded="true"] + .tooltip {
        visibility: visible;
        opacity: 1;
    }
    </style>
    ';
}
add_action('wp_head', 'add_tooltip_styles');

/**
 * JavaScript corregido para enlaces clickeables con retraso
 */
function add_tooltip_scripts() {
    echo '
    <script>
    document.addEventListener("DOMContentLoaded", function() {
        // Configurar todos los tooltips
        document.querySelectorAll(".tooltip-container").forEach(function(container) {
            const tooltip = container.querySelector(".tooltip");
            const trigger = container.querySelector(".tooltip-trigger");
            let hoverTimeout;
            let isMouseInTooltip = false;
            const position = container.getAttribute("data-position");

            // Función para calcular posición automática
            function calculateBestPosition() {
                const rect = trigger.getBoundingClientRect();
                const viewportHeight = window.innerHeight;
                const viewportWidth = window.innerWidth;
                const tooltipHeight = 150; // Altura estimada
                const tooltipWidth = 220; // Ancho estimado
                
                const space = {
                    top: rect.top,
                    bottom: viewportHeight - rect.bottom,
                    left: rect.left,
                    right: viewportWidth - rect.right
                };
                
                // Determinar mejor posición disponible
                if (space.top >= tooltipHeight || (space.top >= space.bottom && space.top > 50)) {
                    return "top";
                } else if (space.bottom >= tooltipHeight) {
                    return "bottom";
                } else if (space.right >= tooltipWidth) {
                    return "right";
                } else if (space.left >= tooltipWidth) {
                    return "left";
                }
                return "top"; // Default
            }

            // Actualizar posición (solo para "auto")
            function updatePosition() {
                if (position === "auto") {
                    tooltip.setAttribute("data-position", calculateBestPosition());
                }
            }

            // Mostrar tooltip
            function showTooltip() {
                clearTimeout(hoverTimeout);
                tooltip.style.visibility = "visible";
                tooltip.style.opacity = "1";
                trigger.setAttribute("aria-expanded", "true");
            }

            // Ocultar tooltip con retraso de 200ms
            function hideTooltip() {
                if (!isMouseInTooltip) {
                    hoverTimeout = setTimeout(() => {
                        tooltip.style.visibility = "hidden";
                        tooltip.style.opacity = "0";
                        trigger.setAttribute("aria-expanded", "false");
                    }, 200); // Retraso clave para enlaces
                }
            }

            // Inicializar posición
            updatePosition();

            // Eventos para el botón
            trigger.addEventListener("mouseenter", showTooltip);
            trigger.addEventListener("mouseleave", hideTooltip);
            trigger.addEventListener("focus", showTooltip);
            trigger.addEventListener("blur", hideTooltip);

            // Eventos para el tooltip (mejorados para enlaces)
            tooltip.addEventListener("mouseenter", function() {
                isMouseInTooltip = true;
                clearTimeout(hoverTimeout); // Cancelar ocultamiento
            });

            tooltip.addEventListener("mouseleave", function() {
                isMouseInTooltip = false;
                hideTooltip(); // Iniciar retraso para ocultar
            });

            // Click en el botón (para móviles)
            trigger.addEventListener("click", function(e) {
                e.preventDefault();
                if (tooltip.style.visibility === "visible") {
                    hideTooltip();
                } else {
                    showTooltip();
                }
            });

            // Reajustar posición en eventos
            if (position === "auto") {
                window.addEventListener("resize", updatePosition);
                window.addEventListener("scroll", updatePosition, { passive: true });
            }
        });

        // Cerrar tooltips al hacer clic fuera (excepto en enlaces)
        document.addEventListener("click", function(e) {
            if (!e.target.closest(".tooltip-container") && !e.target.closest(".tooltip a")) {
                document.querySelectorAll(".tooltip").forEach(function(tooltip) {
                    tooltip.style.visibility = "hidden";
                    tooltip.style.opacity = "0";
                });
                document.querySelectorAll(".tooltip-trigger").forEach(function(trigger) {
                    trigger.setAttribute("aria-expanded", "false");
                });
            }
        });
    });
    </script>
    ';
}
add_action('wp_footer', 'add_tooltip_scripts');