Los detalles de la secuencia de comandos Enqueue para temas y plugins de WordPress

Spanish (Español) translation by Manuel (you can also view the original English article)

La función wp_enqueue_script es la mejor solución para cargar archivos JavaScript en tu sitio de WordPress. Si estás desarrollando un tema que utiliza JavaScript o Bibliotecas JavaScript, la función wp_enqueue_script es el camino a seguir. Sin embargo, si no has usado esto antes, puede ser confuso... así que hoy, vamos a echar un vistazo en profundidad a cómo cargar correctamente los scripts en tu tema o plugin usando la función enqueue.

Cambios posteriores en las técnicas y el software

Algunos aspectos de las aplicaciones o técnicas utilizadas en este tutorial han cambiado desde su publicación original. Esto puede dificultar un poco el seguimiento. Te recomendamos que veas estos tutoriales más recientes sobre el mismo tema:

Cómo incluir JavaScript y CSS en tus temas y plugins de WordPress

¿Por qué utilizamos la función Enqueue?

Si vienes de una formación básica en HTML, probablemente estés acostumbrado a cargar simplemente archivos Javascript (incluyendo cualquier cosa, desde jQuery hasta scripts de plugins) directamente en la cabecera o el pie de página de tu documento. Eso está bien cuando estás en un entorno independiente como una página HTML básica... pero una vez que introduces la miríada de otros scripts que podrían ejecutarse en una instalación de WordPress, se vuelve más complicado hacer lo que llamaré "gestión de multitudes" con tus scripts.

Entonces, ¿por qué no cargar tu JavaScript en la cabecera o en el pie de página? La respuesta es bastante sencilla: Al incluir tu JavaScript de esa manera, corres el riesgo de tener conflictos con tu JavaScript en toda tu instalación (piense, múltiples plugins tratando de cargar los mismos scripts, o diferentes versiones de ese script). Además, tu JavaScript se cargará en cada página, aunque no lo necesites. Esto causará un tiempo de carga innecesariamente más largo para tus páginas, y puede interferir con otro JavaScript, como el de un plugin o dentro del tablero... y eso es un No en el desarrollo de WP.

Utilizando la función wp_enqueue_script. Tendrás un mejor control sobre cómo y cuándo cargar tu JavaScript. Incluso puedes decidir si se carga en la cabecera o en el pie de página.

Comprender la función wp_enqueue_script

La función wp_enqueue_script es la que carga los scripts en tu sitio de WordPress. Normalmente lo vas a usar en tu archivo functions.php.

La función wp_enqueue_script es bastante sencilla, así que veamos su estructura.

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

$handle
- Este es el handle (el nombre) del script que se va a cargar. Debe estar en minúsculas.
- Esto es necesario
- Por defecto: Ninguno

$scr

Esta es la URL del script.

Si estás cargando localmente desde tu servidor, no deberías codificar la URL de los scripts en tu servidor. Es mejor utilizar content_url, bloginfo("template_url"), o get_template_directory_uri() (recomendado por la Referencia de Funciones de WordPress) para los temas, y plugins_url para los plugins.

<?php wp_enqueue_script('myscript', content_url('/myTheme/js/myScript.js'__FILE__)); // content_url ?>

<?php wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__); // bloginfo("template_url") ?>

<?php wp_enqueue_script('myscript', get_template_directory_uri().'/js/myScript.js'__FILE__); // get_template_directory_uri() ?>

<?php wp_enqueue_script('myscript', plugins_url('/myPlugin/js/myScript.js'__FILE__)); // plugins_url ?>

Si estás cargando tu script desde otro servidor. Por ejemplo, cargar la biblioteca jQuery desde el CDN de Google. Sólo tienes que poner la URL del archivo a cargar.
1

<?php wp_enqueue_script('myscript', 'https://www.url/of/file/script.js'__FILE__); ?>
Esto es opcional
Por defecto: falso

$deps

Este es una matriz que maneja cualquier dependencia de los scripts. Por ejemplo, si tu script fade.js requiere jQuery para funcionar. Este parámetro asociará tu script a la biblioteca jQuery.

Utiliza "false" si no quieres usar este parámetro, pero quieres usar otros parámetros.

1	<?php wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), false, '3.1' ); ?>

El script requerido debe ser cargado primero.

Utilizas el manejador del script requerido para la matriz.

1	<?php
2	wp_enqueue_script('jquerylib', 'https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js');
3	wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array('jquerylib'));
4	?>

Esto es opcional
Por defecto: array()

$ver
- Esta es la versión de tu script.
- La versión se concatena al final de la ruta como una cadena de consulta. La versión puede ser el número de versión, false, o NULL.
- Si utilizas false para la versión. Se utilizará la versión de WordPress.
- Si utilizas NULL. No se utilizará nada como versión. Esto no es recomendado por la Referencia de Funciones de WordPress.
- Si no utilizas el parámetro $ver, se utilizará por defecto la versión de WordPress.
  1
  
  <?php wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), false, '1.0' ); ?>
- Esto es opcional
- Por defecto: falso

$in_footer

Esto determinará en qué lugar de la página se coloca el script.
Este parámetro es un booleano ("verdadero" o "falso")

Por defecto tu script se colocará en el <head>, pero es mejor colocarlo justo antes del cierre de la etiqueta <body>. Esto se consigue pasando "true" al parámetro.

1	<?php
2	wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array(), 'version', false ); // placed in the head
3	wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array(), 'version', true ); // placed before body close tag
4	?>

Esto es opcional
Por defecto: falso

Como puedes ver, todos los parámetros excepto $handle son opcionales. A primera vista, esto puede parecer extraño. Especialmente el parámetro $scr. ¿Cómo puede WordPress localizar el script sin una url?

La razón detrás de esto es que WordPress viene con scripts incorporados. Por ejemplo, jQuery forma parte del núcleo de WordPress, y el equipo de desarrollo de WordPress ha hecho que sea muy sencillo cargar estos scripts incorporados. Todo lo que tienes que hacer es pasar el handle del script a wp_enqueue_script.

1	<?php wp_enqueue_script('jquery'); ?>

Para ver la lista completa de los scripts incorporados en WordPress y sus manejadores. Echa un vistazo a la Referencia de funciones de WordPress.

Uso del script Enqueue con tu tema de WordPress

Ahora que entiendes las partes de wp_enqueue_script. Veamos cómo se utiliza esto con el tema de WordPress.

Lo primero es lo primero

Hay otras funciones de WordPress que debes conocer antes de empezar a encauzar los scripts correctamente.

wp_register_script
- La función wp_register_script se utiliza para registrar tu script con WordPress. Lo que esto significa es que podrás utilizar wp_enqueue_script para tus scripts al igual que los scripts incorporados que vienen con WordPress
- La estructura de parámetros de wp_register_script es exactamente la misma que la de wp_enqueue_script, así que no voy a repetirla. Puedes consultar la sección anterior si lo necesitas.
- Solo tienes que configurar wp_register_script igual que lo harías con wp_enqueue_script. A continuación, pon en cola el script con wp_enqueue_script, pasándole el handle.
  1
  
  <?php
  
  2
  
  wp_register_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array(), 'version', false );
  
  3
  
  wp_enqueue_script('myscript');
  
  4
  
  ?>
wp_deregister_script
- El wp_deregister_script elimina un script registrado.
- Lo único que hay que hacer es pasarle la manilla.
  1
  
  <?php wp_deregister_script('myscript'); ?>
wp_deregister_script
- El wp_dequeue_script elimina un script registrado.
- Lo único que hay que hacer es pasarle la manilla.
  1
  
  <?php wp_dequeue_script('myscript'); ?>

Carga de los scripts

La forma más fácil de cargar tu script es colocar el wp_enqueue_script donde quieras en tu página.

1	<?php wp_enqueue_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), false, '1.0' ); ?>
2	<?php wp_head(); ?>

Bastante fácil, pero no muy elegante. Una mejor manera es utilizar tu archivo function.php para cargar tus scripts. Para ello es necesario crear una función personalizada. A continuación, utiliza add_action para inicializar tu función.

<?php 
function load_my_scripts() {
	wp_register_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), false, '1.0', true );
	wp_enqueue_script('myscript');
}
add_action('init', 'load_my_scripts');
?>

La línea 2 crea una función llamada load_my_scripts
La línea 3 registra el script myscript
La línea 4 pone en cola el script myscript
La línea 6 inicializa la función load_my_scripts

El script que acabamos de cargar necesita la versión actual de jQuery para ejecutarse, así que vamos a dar de baja la versión por defecto que viene con WordPress añadiendo la nueva versión a nuestra función.

<?php 
function load_my_scripts() {
	wp_deregister_script( 'jquery' );
	wp_register_script('jquery', 'https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js');
	wp_enqueue_script('jquery');
	wp_register_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array("jquery"), '1.0', true );
	wp_enqueue_script('myscript');
}
add_action('init', 'load_my_scripts');
?>

La línea 2 desregistra el jQuery por defecto que viene con WordPress
La línea 3 registra otra versión de jQuery
La línea 4 pone en cola el script myscript

Bien, las buenas prácticas de codificación de WordPress dictan que debemos comprobar si una función existe antes de ejecutarla. Esto se logra así.

1	<?php
2	if (function_exists('functionName')) {
3	}
4	?>

Esto comprueba si tu función ya existe. Si no es así, ejecutará tu función.

Añadamos esto a nuestra función load_my_scripts

<?php 
if (function_exists('load_my_scripts')) {
    function load_my_scripts() {
		wp_deregister_script( 'jquery' );
		wp_register_script('jquery', 'https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js');
		wp_enqueue_script('jquery');
		wp_register_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array('jquery'), '1.0', true );
		wp_enqueue_script('myscript');
    }
}
add_action('init', 'load_my_scripts');
?>

Ahora, si vas a tu página de administración no quieres que tu script se cargue. Podría causar un conflicto y romper la página de administración. Una regla general es que no quieres que tus scripts personalizados se carguen en la página de administración. Los scripts para los plugins son una historia diferente. I'll go over that later.

Vamos a comprobar si la página cargada no es la página de administración con !is_admin(). Si no es así, nuestros scripts se cargarán.

1	<?php
2	if (!is_admin()) {
3	}
4	?>

Ahora la función tiene este aspecto.

<?php 
if (function_exists('load_my_scripts')) {
    function load_my_scripts() {
    	if (!is_admin()) {
		wp_deregister_script( 'jquery' );
		wp_register_script('jquery', 'https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js');
		wp_enqueue_script('jquery');
		wp_register_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array('jquery'), '1.0', true );
		wp_enqueue_script('myscript');
    	}
    }
}
add_action('init', 'load_my_scripts');
?>

Ahí lo tienes. Una bonita plantilla para que utilices para poner en cola los scripts

Uso del script Enqueue para tus plugins

Bien, ahora que lo tienes claro. Vamos a añadir un script que solo se cargará en la página de administración de tu plugin.

En realidad es muy sencillo. Simplemente escribe tu función de script como la que hicimos en la sección anterior en el archivo de tu plugin. Solo que ahora en vez de usar 'init' en la add_action, usa 'admin_init'.

<?php 
if (function_exists('load_my_scripts')) {
    function load_my_scripts() {
    	if (!is_admin()) {
		wp_deregister_script( 'jquery' );
		wp_register_script('jquery', 'https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js');
		wp_enqueue_script('jquery');
		wp_register_script('myscript', bloginfo('template_url').'/js/myScript.js'__FILE__), array('jquery'), '1.0', true );
		wp_enqueue_script('myscript');
    	}
    }
}
add_action('admin_init', 'load_my_scripts');
?>

Eso es todo, ahora tu script solo se cargará cuando vayas a la página de administración de tu plugin.

Conclusión

Espero que esto te ayude a entender mejor los scripts de cola dentro de WordPress, ¡Así que ahora puedes salir y cargar algunos scripts propios!

Si hay algo que no entiendas o sobre lo que quieras leer. Te recomiendo que visites el WordPress Codex. Aquí hay una lista de otros enlaces de códices relevantes para ti también: