Como encolar javascript en WordPress

Cuando desarrollamos plugins o temas para WordPress, uno de los aspectos más importantes es cómo encolar javascript en nuestros plugins o temas de wordpress. Un uso incorrecto de wp_enqueue_script() puede provocar problemas de rendimiento, errores de caché y advertencias en herramientas de validación como Theme Check o PHPCS.

En este artículo te explico cómo usar wp_enqueue_script() correctamente, qué significan sus parámetros, y cómo evitar los errores más comunes.

Indice

¿Qué es wp_enqueue_script()?
Problemas comunes y cómo solucionarlos
- No establecer $in_footer explícitamente
- No establecer la versión ($ver)
🛠️ Caso práctico: Encolando Font Awesome en tu plugin

¿Qué es `wp_enqueue_script()`?

wp_enqueue_script es la función que WordPress nos ofrece para encolar scripts JavaScript en nuestras páginas de forma segura y ordenada. Cuando encolamos un estilo o script usando esta funcion, las personalizaciones se podran ver en el front-end. Un ejemplo podria ser el estilo y las funciones que permiten que el menu de navegacion de un tema sean funcionales, permitiendo al usuario poder navegar el sitio sin problemas.

Su sintaxis es:

wp_enqueue_script(
  $handle, 
  $src,    
  $deps,   
  $ver     
  $in_footer  
);

⚠️ Problemas comunes y cómo solucionarlos

1. No establecer `$in_footer` explícitamente

Si no defines este parámetro, WordPress lo carga por defecto en el header. Esto puede ralentizar el renderizado de la página, provocando cargas mas lentas.

Que solución es recomendada: Asegurate de agregar «true» en tu script.

wp_enqueue_script('mi-script', $url, array(), '1.0.0', true);

✅ Cargar scripts en el footer mejora el rendimiento y evita bloqueos en la carga del DOM.

2. No establecer la versión (`$ver`)

Si usas null o lo omites, WordPress no añade la cadena ?ver=1.0.0 al final del script. Esto impide que el navegador sepa cuándo debe actualizar el archivo en caché.

Ejemplo incorrecto:

wp_enqueue_script('mi-script', $url, array(), null, true);

Ejemplo correcto:

wp_enqueue_script('mi-script', $url, array(), '1.2.3', true);

💡 También puedes usar la versión de tu plugin:

Para encolar la version de tu plugin or tema, define primero una variable con la version, y luego agregala a wp_enqueue_script().


define('MI_PLUGIN_VERSION', '2.0.1');

wp_enqueue_script('mi-script', $url, array(), MI_PLUGIN_VERSION, true);

🛠️ Caso práctico: Encolando Font Awesome en tu plugin

Supongamos que quieres incluir Font Awesome desde su Kit URL. Lo primero es que para usar el codigo, debemos agregarlo, en caso de estar creando un tema, en el fichero function.php. Si estamos trabajando en un plugin, agregaremos directamente en el fichero principal del plugin.

Primero vamos a crear la base con esta funcion la cual permite encolar Font Awesome Kit.

Configurando la funcion usando la documentacion oficial de Font Awesome: Agrega esto a tu fichero function.php o a tu fichero principal de tu plugin tu-plugin.php.


if (! function_exists('fa_custom_setup_kit') ) {
  function fa_custom_setup_kit($kit_url = '') {
    foreach ( [ 'wp_enqueue_scripts', 'admin_enqueue_scripts', 'login_enqueue_scripts' ] as $action ) {
      add_action(
        $action,
        function () use ( $kit_url ) {
          wp_enqueue_script( 'font-awesome-kit', $kit_url, [], null );
        }
      );
    }
  }
}

Luego debes llamar la funcion pero usando tu propio kit.

fa_custom_setup_kit('https://kit.fontawesome.com/yourkitcode.js');

Aqui otra forma para usar lo mismo pero usando todas las recomendaciones descritas en este articulo. A diferencia de agregar una accion, vamos a retornar wp_enqueue_script.


if(!function_exists('plugin_add_fa_library')){
    function plugin_add_fa_library($kit_url = '') {
        return wp_enqueue_script('font-awesome-kit', $kit_url, array(), MI_PLUGIN_VERSION, true);
    }
}

Ahora agregaremos la funcion a a la funcion para encolar las los scripts y los estilos:

function tu_enqueue_scripts(){
  ...
  plugin_add_fa_library('https://kit.fontawesome.com/yourkitcode.js');
  ...
}
add_action('wp_enqueue_scripts', 'tu_enqueue_scritps');

Con esto, terminamos por hoy espero les sea util la informacion. Nos vemos en el proximo articulo.

The Digital Mike