Contents
Introducción
En WordPress es buena práctica cargar archivos JavaScript únicamente cuando realmente se necesitan. Esto reduce el tamaño de las páginas, mejora la velocidad y evita conflictos. Este tutorial muestra, con todo detalle y ejemplos prácticos, cómo cargar un archivo JS solo en una plantilla específica usando condicionales de WordPress (is_page_template, is_singular, is_page, etc.). También incluye buenas prácticas: registro de scripts, versionado con filemtime, localización de variables y diferencias entre get_template_directory_uri() y get_stylesheet_directory_uri().
Requisitos y conceptos previos
- Acceso al theme: editar functions.php o crear un pequeño plugin.
- Hooks relevantes: wp_enqueue_scripts (front-end) y admin_enqueue_scripts (back-end).
- Funciones clave: wp_register_script(), wp_enqueue_script(), wp_localize_script().
- Condicionales: is_page_template(), is_page(), is_singular(), is_post_type_archive(), is_front_page(), is_home(), etc.
- Rutas: get_template_directory_uri() / get_template_directory() para themes padre get_stylesheet_directory_uri() / get_stylesheet_directory() para child themes.
Buenas prácticas antes de empezar
- Registrar antes de encolar si el script puede usarse en varios contextos.
- Usar filemtime() para pasar como versión y forzar bust de caché al actualizar el archivo en desarrollo.
- Colocar scripts en el footer (último parámetro true) salvo que sean críticos para el head.
- Usar wp_localize_script() para pasar datos de PHP a JS de forma segura.
- Evitar incluir scripts directamente en plantillas con etiquetas ltscriptgt — aprovechar el sistema de enqueued assets de WP.
Ejemplo 1 — Cargar JS solo en una plantilla de página concreta
Imagina que tienes una plantilla de página llamada template-contact.php ubicada en la carpeta raíz del tema. El siguiente fragmento, que va en functions.php del tema (o en tu plugin), encola contact.js únicamente cuando se cargue esa plantilla:
lt?php
function tema_enqueue_conditional_scripts() {
// Ruta física para filemtime y URI para browser
script_path = get_template_directory() . /js/contact.js
script_uri = get_template_directory_uri() . /js/contact.js
if ( is_page_template( template-contact.php ) ) {
// Registro opcional (permite encolar desde otros sitios si hace falta)
wp_register_script(
tema-contact-js,
script_uri,
array(jquery), // dependencias
file_exists( script_path ) ? filemtime( script_path ) : false,
true // cargar en footer
)
// Localizar datos para uso en JS (por ejemplo AJAX URL)
wp_localize_script( tema-contact-js, temaContactData, array(
ajax_url => admin_url( admin-ajax.php ),
nonce => wp_create_nonce( tema_contact_nonce ),
) )
// Encolar el script
wp_enqueue_script( tema-contact-js )
}
}
add_action( wp_enqueue_scripts, tema_enqueue_conditional_scripts )
?gt
Notas sobre el ejemplo
- Si tu tema hijo (child theme) aloja el archivo JS, sustituye get_template_directory_ por get_stylesheet_directory_.
- filemtime fuerza el versionado si el fichero no existe se evita una advertencia con file_exists.
- El condicional is_page_template() debe ejecutarse durante la petición front-end por eso es correcto usar wp_enqueue_scripts.
Ejemplo 2 — Registrar globalmente y encolar condicionalmente
Registrar primero puede ser útil si otros componentes podrían necesitar el mismo script:
lt?php
function tema_register_scripts() {
script_path = get_template_directory() . /js/shared.js
script_uri = get_template_directory_uri() . /js/shared.js
wp_register_script(
tema-shared-js,
script_uri,
array(),
file_exists( script_path ) ? filemtime( script_path ) : false,
true
)
}
add_action( wp_enqueue_scripts, tema_register_scripts )
function tema_conditional_enqueue_after_register() {
// Encolamos el script solo en la plantilla template-special.php
if ( is_page_template( template-special.php ) ) {
wp_enqueue_script( tema-shared-js )
}
}
add_action( wp_enqueue_scripts, tema_conditional_enqueue_after_register )
?gt
Ejemplo 3 — Cargar JS para un post type concreto
Si quieres cargar un script solo para los single pages de un custom post type (por ejemplo book):
lt?php
function tema_books_scripts() {
if ( is_singular( book ) ) {
path = get_template_directory() . /js/book-single.js
wp_enqueue_script(
tema-book-js,
get_template_directory_uri() . /js/book-single.js,
array(),
file_exists( path ) ? filemtime( path ) : false,
true
)
}
}
add_action( wp_enqueue_scripts, tema_books_scripts )
?gt
Ejemplo 4 — Cargar JS por ID o slug de página
En ocasiones necesitas cargar un archivo en una página específica identificada por ID o slug:
lt?php
function tema_page_id_or_slug_script() {
// Por ID
if ( is_page( 42 ) ) {
wp_enqueue_script( tema-page-42, get_template_directory_uri() . /js/page-42.js, array(), null, true )
}
// Por slug
if ( is_page( acerca-de ) ) {
wp_enqueue_script( tema-acerca, get_template_directory_uri() . /js/acerca.js, array(), null, true )
}
}
add_action( wp_enqueue_scripts, tema_page_id_or_slug_script )
?gt
Ejemplo 5 — Pasar datos desde PHP a JS
Una vez encolado el script, usa wp_localize_script para pasar variables. Ejemplo sencillo del archivo JS que usará esos datos:
// /js/contact.js
document.addEventListener(DOMContentLoaded, function() {
if ( typeof temaContactData !== undefined ) {
console.log(AJAX URL:, temaContactData.ajax_url)
// Usar el nonce: temaContactData.nonce
}
})
Consideraciones especiales y errores comunes
- is_page_template no funciona en admin: esos condicionales son para la parte pública. Para el admin usa admin_enqueue_scripts y condicionales como get_current_screen().
- Orden de hooks: wp_enqueue_scripts es el hook correcto para front-end. No uses init para encolar assets (aunque podrías registrar ahí y encolar después).
- Rutas en child themes: usa get_stylesheet_directory_uri() en lugar de get_template_directory_uri() para garantizar compatibilidad con child themes.
- Dependencias: declara correctamente dependencias (ej. jquery) para evitar errores de ejecución.
- Caché y versionado: filemtime es muy útil en desarrollo en producción puedes usar un número fijo o una estrategia de versionado basada en release.
Checklist rápido antes de desplegar
- ¿Registraste o encolaste el script con un handle único y descriptivo?
- ¿Usaste get_template_/get_stylesheet_ según corresponda?
- ¿Declaraste dependencias y colocaste en footer si es posible?
- ¿Comprobaste que el condicional elegido (is_page_template, is_singular, is_page…) cubre exactamente las páginas que quieres?
- ¿Localizaste datos sensibles (nonces) con wp_localize_script en vez de imprimirlos en el DOM?
Resumen final
Cargar un JS solo en una plantilla específica en WordPress implica:
- Elegir el hook correcto (wp_enqueue_scripts).
- Usar condicionales como is_page_template(), is_singular() o is_page() para detectar el contexto.
- Registrar/enqueue con get_template/get_stylesheet y versionado (filemtime).
- Localizar datos con wp_localize_script cuando sea necesario.
Ejemplo compacto de uso habitual
lt?php
function tema_compact_conditional() {
file = /js/special.js
abs = get_template_directory() . file
uri = get_template_directory_uri() . file
if ( is_page_template( template-special.php ) is_singular( book ) ) {
wp_enqueue_script( tema-special-js, uri, array(jquery), file_exists( abs ) ? filemtime( abs ) : null, true )
}
}
add_action( wp_enqueue_scripts, tema_compact_conditional )
?gt
Aplica estos ejemplos y adaptaciones para mantener tu sitio ligero y organizado. Con las prácticas descritas podrás cargar scripts únicamente cuando sean necesarios, mejorar tiempos de carga y reducir la posibilidad de conflictos entre assets.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |