Menambahkan keterangan alat di WordPress tanpa plugin

Istilah tooltip tidak memiliki terjemahan yang unik ke dalam bahasa Inggris, istilah ini dapat digambarkan sebagai "tooltip", "balon bantuan", "deskripsi pop-up", atau bahkan "teks bantuan", tergantung pada konteks penggunaannya.

Tooltip adalah pesan pop-up yang muncul ketika berinteraksi dengan suatu elemen, baik dengan mengekliknya, maupun dengan mengarahkan mouse. Tooltip ini digunakan untuk memberikan informasi tambahan tanpa menghabiskan ruang permanen. Ideal untuk menjelaskan ikon, istilah teknis, atau tindakan dalam antarmuka.

Apakah tooltips merugikan atau menguntungkan SEO?

Untuk hampir semua hal, jawabannya selalu tergantung. Meskipun para ahli SEO memperingatkan bahwa Google tidak menyukai konten yang "tersembunyi" atau disamarkan dan menghukum penggunaannya dengan keras, hal ini akan menjadi ekstrem untuk kasus penyalahgunaan yang dapat "mengkanibal" konten Anda. Namun, keterangan alat, yang digunakan dengan keseimbangan tertentu dan logika minimum, dapat bermanfaat.

Keuntungan menggunakan keterangan alat

Secara umum, pesan-pesan ini, jika ramah dan tidak mengganggu, dapat berkontribusi untuk meningkatkan berbagai aspek pengalaman pengguna. Di antaranya, pesan ini dapat mengurangi rasio pentalan dan meningkatkan aksesibilitas. Hal ini juga dapat memberikan kesempatan untuk menggunakan kata kunci tambahan yang tidak sesuai dengan konten utama, yang membantu SEO semantik.

Selain itu, mereka dapat meningkatkan rasio klik-tayang. Dengan menawarkan keterangan alat di navigasi atau tombol ajakan bertindak, mereka dapat memandu pengguna secara lebih efektif, sehingga menghasilkan rasio klik-tayang yang lebih tinggi. Tetapi agar semua ini dapat dilakukan, beberapa pedoman minimum harus diikuti.

Rekomendasi untuk tampilan, konten, dan pengoperasian

• Penggunaan elemen HTML dan atribut ARIA untuk memastikan bahwa pembaca layar dan mesin pencari dapat mengakses informasi yang ada di dalamnya.
• Keterangan alat harus singkat. Jelas, tidak ada orang yang akan membaca sejumlah besar informasi dalam pop-up dan Anda akan mencakup sebagian besar konten. Ini harus berisi informasi minimum, tepat dan perlu, dan ini tidak boleh penting bagi pengguna saat melakukan atau menyelesaikan tindakan.
• Konten tidak boleh berlebihan atau diulang-ulang, pastikan bahwa Anda memberikan informasi tambahan yang berguna dan perlu dan tidak diulang-ulang dalam konten Anda untuk menghindari "konten duplikat".
• Cobalah untuk menghindari sebisa mungkin keterangan alat yang menghilang ketika Anda menggerakkan kursor atau gunakan hanya pada pesan yang tidak mengandung banyak informasi dan/atau konten. Idealnya, tooltip harus ditampilkan per klik dan ditutup ketika Anda mengklik lagi di mana pun pada layar.
• Pastikan bahwa tulisan tersebut terbaca dan ukurannya benar.
• Jangan menambahkan dua puluh desain ikon tooltip atau tautan tooltip yang berbeda, yang hanya akan menimbulkan kebingungan. Desain yang tetap dan konsisten akan membantu pengunjung Anda mengidentifikasinya pada pandangan pertama.
• Jangan berlebihan, rencanakan strategi Anda dengan baik untuk menambahkannya hanya jika Anda merasa bahwa hal itu akan memudahkan akses ke informasi pelengkap yang relevan dan/atau diperlukan.

Fitur dan fungsi kode

Gambar.png dengan latar belakang transparan telah digunakan untuk kasus ini.

Di sini Anda dapat menguji hasil akhir yang berfungsi [tooltip text = "Contoh tooltip yang digunakan di jrmora.com" position = "auto"].

URL gambar ditambahkan di antara tanda kutip tunggal pada baris ini:

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

Jika Anda memilih untuk memodifikasi kode untuk menggunakan ikon HTML SVG, seperti yang ini, Anda akan dapat bermain dengan warna, latar belakang, ketebalan, dll. dengan lebih mudah.

Penyesuaian posisi otomatis yang cerdas untuk menghindari tepi layar. Misalnya, ketika mendekati tepi atas, keterangan alat ditampilkan di bagian bawah dan sebaliknya.

Tautan yang berfungsi penuh dapat ditambahkan dalam keterangan alat dengan gaya yang dapat disesuaikan. Meskipun tidak disarankan untuk menambahkan tautan, namun ada kemungkinan bahwa Anda mungkin perlu melakukannya sesekali. Apabila keterangan alat berisi tautan, akan ada penundaan 200 ms dalam penyembunyian otomatis untuk membuatnya lebih mudah diklik.

Dukungan HTML yang aman. Dukungan:

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

Posisi, atribut yang tetap dan mudah beradaptasi.

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

Atribut ARIA (aria-diperluas, role="tooltip").

Pembaruan. Menambahkan aria-hidden = "true" dan role = "presentation" ke gambar dan menyembunyikan ikon dekoratif untuk pembaca layar.

Redundansi dihindari dengan label aria yang memungkinkan penyesuaian teks yang dapat diakses dari shortocode.

[tooltip text="Contenido" aria_label="Ver detalles sobre este elemento"]

Solusi ini sesuai dengan WCAG 2.1 AA dan menyelesaikan peringatan PageSpeed Insights bahwa tombol tidak memiliki nama yang dapat diakses.

Desain yang responsif.

Dapat beradaptasi dengan seluler (tombol yang dapat diklik).

Mengatur ulang saat mengubah ukuran, memutar, atau menggeser

Kelas-kelas CSS utama:

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

Fungsi-fungsi utama dari JS:

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

Contoh kode pendek:

[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>"]

Dari segi performa:

1. Pemuatanaset: Gambar dan CSS yang dimuat sebelumnya.
2. Pemuatan malas: Atribut pemuatan = "malas" dan decoding = "asinkronisasi" untuk gambar.
3. Pemuatan bersyarat: JS hanya dimuat ketika shortcode digunakan.
4. Debounce: Optimalisasi peristiwa pengubahan ukuran dan gulir.
5. CSS yang dioptimalkan: Penggunaan unit yang akan berubah dan modern (min()).
6. Versi cache: Gunakan filemtime() untuk menghindari cache yang sudah usang.

Kode ini adalah kode yang saya gunakan untuk kebutuhan spesifik saya. Pahamilah sebagai titik awal. Kode ini dapat ditingkatkan. Anda bahkan dapat mempertimbangkannya tanpa menggunakan Javascript dan mengadaptasinya sehingga dapat juga diterapkan pada kata-kata dalam konten tanpa menampilkan ikon.

Untuk menggunakannya, seperti biasa, cukup tambahkan ke functions.php dan di folder assets/css/ dan asstes/js/ pada templat Anda atau tema anak Anda jika Anda ingin menyimpan perubahan saat memperbarui templat Anda.

Kode

Ini adalah struktur file:

your-template/
├── functions.php (tambahkan kode PHP di bagian akhir)
├── assets/
│ ├─── css/
│ │ └└── tooltip.css (Gaya CSS)
│ └└── js/
│ └└─── tooltip.js (JavaScript)

Kode untuk ditambahkan ke template functions.php

/**
 * Shortcode para tooltip accesible y optimizado
 * Uso: [tooltip text="Texto" position="auto" color="#6a0000" aria_label="Descripción"]
 */
function accessible_tooltip_shortcode($atts) {
    $default_image = 'https://jrmora.com/wp-content/uploads/2025/07/tooltip-negro.png';
    
    $atts = shortcode_atts(
        array(
            'text' => __('Información adicional', 'text-domain'),
            'position' => 'auto',
            'color' => '#6a0000',
            'shadow' => '#9c9c9c',
            'width' => '18px',
            'id' => 'tooltip-' . uniqid(),
            'aria_label' => __('Mostrar información adicional', 'text-domain')
        ),
        $atts,
        'tooltip'
    );

    // HTML permitido (seguro)
    $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']);
    $aria_label = esc_attr($atts['aria_label']);

    // Preload para la imagen (mejora rendimiento)
    add_action('wp_head', function() use ($default_image) {
        echo '<link rel="preload" href="' . esc_url($default_image) . '" as="image">';
    });

    return '
    <span class="tooltip-container" data-position="' . esc_attr($position) . '">
        <button class="tooltip-trigger" 
                aria-describedby="' . $id . '" 
                aria-expanded="false"
                aria-label="' . $aria_label . '">
            <img src="' . esc_url($default_image) . '" 
                 width="' . $width . '" 
                 alt=""
                 aria-hidden="true"
                 loading="lazy"
                 decoding="async"
                 role="presentation"/>
        </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>';
}
add_shortcode('tooltip', 'accessible_tooltip_shortcode');

/**
 * Carga optimizada de assets
 */
function load_tooltip_assets() {
    global $post;
    
    // CSS externo
    wp_enqueue_style(
        'tooltip-css',
        get_theme_file_uri('/assets/css/tooltip.css'),
        array(),
        filemtime(get_theme_file_path('/assets/css/tooltip.css'))
    );
    
    // JS solo si se usa el shortcode
    if (is_a($post, 'WP_Post') && has_shortcode($post->post_content, 'tooltip')) {
        wp_enqueue_script(
            'tooltip-js',
            get_theme_file_uri('/assets/js/tooltip.js'),
            array(),
            filemtime(get_theme_file_path('/assets/js/tooltip.js')),
            true
        );
    }
}
add_action('wp_enqueue_scripts', 'load_tooltip_assets');

CSS / tooltip.css (harus disimpan di jalur ini /assets/css/tooltip.css)

/* Contenedor principal */
.tooltip-container {
    display: inline-block;
    position: relative;
    vertical-align: middle;
}

/* Botón activador */
.tooltip-trigger {
    background: none;
    border: none;
    padding: 0;
    margin: 0 2px;
    cursor: pointer;
    line-height: 1;
}

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

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

/* Posiciones */
.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;
}

/* Interacción */
.tooltip-trigger:hover + .tooltip,
.tooltip-trigger:focus + .tooltip,
.tooltip-trigger[aria-expanded="true"] + .tooltip {
    visibility: visible;
    opacity: 1;
}

/* Enlaces dentro del tooltip */
.tooltip a {
    color: #fff !important;
    text-decoration: underline;
    pointer-events: auto !important;
}

/* Focus para accesibilidad */
.tooltip-trigger:focus {
    outline: 2px solid #005fcc;
    outline-offset: 2px;
}

Javascript / Tooltip.js (Harus disimpan di jalur /assets/js/tooltip.js)

document.addEventListener("DOMContentLoaded", () => {
    const tooltips = document.querySelectorAll('.tooltip-container[data-position="auto"]');
    if (!tooltips.length) return;

    // Debounce para optimización
    const debounce = (func, wait = 50) => {
        let timeout;
        return (...args) => {
            clearTimeout(timeout);
            timeout = setTimeout(() => func.apply(this, args), wait);
        };
    };

    // Configurar cada tooltip
    tooltips.forEach(container => {
        const tooltip = container.querySelector('.tooltip');
        const trigger = container.querySelector('.tooltip-trigger');
        let hoverTimeout;
        let isMouseIn = false;

        // Calcular mejor posición
        const calculatePosition = () => {
            const rect = trigger.getBoundingClientRect();
            const viewportHeight = window.innerHeight;
            return (rect.top < viewportHeight / 2) ? 'bottom' : 'top';
        };

        // Actualizar posición (optimizado)
        const updatePosition = debounce(() => {
            tooltip.dataset.position = calculatePosition();
        });

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

        // Ocultar con retraso (para enlaces)
        const hideTooltip = () => {
            if (!isMouseIn) {
                hoverTimeout = setTimeout(() => {
                    tooltip.style.visibility = 'hidden';
                    tooltip.style.opacity = '0';
                    trigger.setAttribute('aria-expanded', 'false');
                }, 200);
            }
        };

        // Eventos
        trigger.addEventListener('mouseenter', showTooltip);
        trigger.addEventListener('mouseleave', hideTooltip);
        trigger.addEventListener('focus', showTooltip);
        trigger.addEventListener('blur', hideTooltip);

        tooltip.addEventListener('mouseenter', () => {
            isMouseIn = true;
            clearTimeout(hoverTimeout);
        });

        tooltip.addEventListener('mouseleave', () => {
            isMouseIn = false;
            hideTooltip();
        });

        // Inicialización
        updatePosition();
        window.addEventListener('resize', updatePosition);
        window.addEventListener('scroll', updatePosition, { passive: true });
    });

    // Cerrar al hacer clic fuera
    document.addEventListener('click', (e) => {
        if (!e.target.closest('.tooltip-container') && !e.target.closest('.tooltip a')) {
            document.querySelectorAll('.tooltip').forEach(t => {
                t.style.visibility = 'hidden';
                t.style.opacity = '0';
            });
        }
    });
});