Conocer la forma adecuada de incluir archivos JavaScript y CSS en tus temas y plugins WordPress es muy importante para los diseñadores y los desarrolladores. Si no sigues las mejores prácticas, corres el riesgo de crear conflictos con otros temas y plugins, y crear potencialmente problemas que podrían haber sido evitados fácilmente. Este artículo pretende ser una referencia sobre como jugar limpio con los demás.
Antes de que empecemos, puedes visitar nuestra sección de Temas para WordPress y Plugins para WordPress, por si necesitas lanzar a toda velocidad tu próximo proyecto profesionalmente.
Y si, tras leer este tutorial, todavía no estás seguro sobre cómo incluir tus archivos JavaScript y CSS de forma correcta, puede que valga la pena que solicites algunos de los servicios WordPress disponibles en Envato Studio.
Desde la instalación a la personalización, e incluso el SEO y la optimización de la velocidad, puedes contactar con un experto en WordPress para que establezca las cosas de la forma correcta desde el principio.
Las buenas prácticas hacen feliz a todo el mundo
Si has desarrollado alguna vez un tema o un plugin para WordPress, o has trabajado con uno que ha creado otra persona, probablemente te hayas encontrado con distintos métodos para incluir JavaScript y CSS. Mientras que existen distintos métodos que podrían parecer funcionar en una conjunto de circunstancias específicas, hay un método principal recomendado en el Codex WordPress. Este método preferente asegurará que tu tema y tu plugin funcione en todos los casos, asumiendo que los demás también estén codificando correctamente.
También hay algunos malos entendidos sobre qué dice exactamente el Codex sobre esto, lo cual ayudaré a clarificar
¿Qué viene en la caja?
Cuando descargas WordPress, éste ya viene con una selección de habituales librerías JavaScript incluidas que puedes usar para tu desarrollo JavaScript. Puedes encontrar una lista de las librerías incluidas en el artículo sobre wp_enqueue_script del Codex de WordPress.
Todas estas librerías están incluídas, pero por defecto WordPress solo carga las que necesita, y en el admin sólo cuando las necesita. Si escribes JavaScript que utiliza una de estas librerías, necesitarás indicarle a WordPress que cargue primero la librería para que tu script funcione.
Indicarle a WordPress sobre tu script y sobre qué necesita
Algunas de las cosas sobre las que debes pensar cuando estás creando código JavaScript para WordPress son las siguientes:
- ¿Existe ya alguna librería incluída que pueda usar?
- ¿Puedo usar la versión incluída?
- ¿Necesito cargar mi script en el front-end y en el área de admin?
- ¿En qué páginas del front-end y de admin necesito cargar mi script?
Responder a estas preguntas te ayudará a conocer qué necesitas hacer para registrar y cargar tu script. Esto se hace usando una función de WordPress llamada wp_register_script, y aquí tienes cómo se debe usar según el Codex de WordPress:
|
1 |
wp_register_script( $handle, $src, $deps, $ver, $in_footer ); |
Entonces, ¿qué son estas variables?, ¿las necesitamos cada vez? (Esto se explica en la página del Codex, de manera que seré breve y usaré un lenguaje sencillo)
$handle– lo que necesitarás para referenciar este script concreto siempre que necesites encolarlo, y debes incluir esta variable como mínimo.$src– la ruta del archivo de origen dentro de tu plugin o tema$deps– es una cadena que contiene la variable$handlepara cualquier otro u otros scripts que necesite tu propio script para ejecutarse (es decir, sus dependencias).$ver– el número de versión de tu script, que puede usarse para cache-busting. Por defecto, WordPress usará su propio número de versión como número de versión para tu script.$in_footer– ¿quieres que tu script se cargue en el footer? Establece esta variable atrueofalse. El valor predeterminado esfalse, por tanto se carga en el header, donde aparezcawp_head(), y si especificastruese cargará cuandowp_footeraparezca en el tema.
¿Qué es “Caché-Busting”?
Los navegadores recuerdan qué scripts y hojas de estilo han descargado para un determinado sitio basándose en la URL del script y de la hoja de estilo. Si cambias la URL, aunque tan solo añadas una cadena de consulta, los navegadores asumirán que es un nuevo archivo y lo descargarán de nuevo.
Ok, probemos algunos ejemplos
Aquí tienes el ejemplo más sencillo para cargar un script:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
function wptuts_scripts_basic() { // Register the script like this for a plugin: wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ) ); // or // Register the script like this for a theme: wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' ); // For either a plugin or a theme, you can then enqueue the script: wp_enqueue_script( 'custom-script' ); } add_action( 'wp_enqueue_scripts', 'wptuts_scripts_basic' ); |
Primero registramos el script, de forma que WordPress sepa de qué estamos hablando. La forma de encontrar la ruta para nuestro archivo JavaScript es distinta dependiendo de si estamos creando código para un plugin o para un tema, por eso he incluido ejemplos de ambos aquí arriba. Después los encolamos para añadirlos al HTML de la página cuando esta es generada, por defecto en el <head>, exactamente donde esté situado wp_head() en el tema.
Lo que nos devuelve este básico ejemplo es lo siguiente:
|
1 |
<script type="text/javascript" src="http://yourdomain.com/wp-content/plugins/yourplugin/js/custom-script.js?ver=3.3.1"></script> |
Ahora, si tu script es dependiente de una de las librerías incluidas en WordPress, como jQuery, puedes hacer un cambio muy sencillo en el código:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
function wptuts_scripts_with_jquery() { // Register the script like this for a plugin: wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ), array( 'jquery' ) ); // or // Register the script like this for a theme: wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js', array( 'jquery' ) ); // For either a plugin or a theme, you can then enqueue the script: wp_enqueue_script( 'custom-script' ); } add_action( 'wp_enqueue_scripts', 'wptuts_scripts_with_jquery' ); |
Nota: Por defecto, jQuery se carga con noConflict para prevenir conflictos con otras librerías (como por ejemplo con Prototype). Consulta la sección noConflict del Codex si no sabes cómo gestionar este asunto.
¿Has visto lo que hice aquí? Añade simplemente una cadena con el handle ‘jquery’ como dependencia. Éste usa en este caso una cadena, ya que tu script podría tener múltiples dependencias. Si tu script usa jQuery y jQuery UI, debes añadir jQuery UI a la cadena de tus dependencias, como array( ‘jquey’, ‘jquery-ui-core’ ).
Por tanto lo que nos devuelve esto ha cambiado, y podemos ver que jQuery también ha sido añadido al <head> de la página:
|
1 2 |
<script type='text/javascript' src='http://yourdomain.com/wp-includes/js/jquery/jquery.js?ver=1.7.1'></script> <script type='text/javascript' src='http://yourdomain.com/wp-content/plugins/yourplugin/js/custom-script.js?ver=3.3.1'></script> |
Probemos con un ejemplo que contiene todos los elementos:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
function wptuts_scripts_with_the_lot() { // Register the script like this for a plugin: wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ), array( 'jquery', 'jquery-ui-core' ), '20120208', true ); // or // Register the script like this for a theme: wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js', array( 'jquery', 'jquery-ui-core' ), '20120208', true ); // For either a plugin or a theme, you can then enqueue the script: wp_enqueue_script( 'custom-script' ); } add_action( 'wp_enqueue_scripts', 'wptuts_scripts_with_the_lot' ); |
Ok, ahora hemos añadido una versión y hemos especificado que este script necesita ser cargado en el footer. Para el número de versión he elegido la fecha del día de hoy ya que es una pista fácil de seguir, pero puedes usar cualquier número de versión, el que prefieras. La línea que nos devuelve esto es también un poco distinta, jQuery es llamado en el <head> y nuestro script junto con jQuery UI es invocado justo antes de la etiqueta de cierre <body>, de la siguiente manera:
|
1 2 3 |
...... ... |
Algunas personas podrían preferir no usar los métodos adecuados para encolar sus scripts porque piensan que tienen menos control sobre el orden en el que estos son cargados. Por ejemplo, en un tema que usa modernizr, el autor del tema podría querer asegurarse de que modernizr sea cargado al principio.
Algo que no he mencionado antes son los detalles sobre cómo funciona la función add_action, ya que aquí es donde podemos ejercer algo de influencia sobre el orden de las cosas. Aquí tienes la forma de usar esta función según la página del Codex de WordPress:
|
1 |
add_action( $tag, $function_to_add, $priority, $accepted_args ); |
Advierte que con frecuencia, hasta ahora en este artículo, sólo hemos usado los parámetros $tag y $function_to_add. Por defecto el parámetro $priority está establecido a 10, y el valor predeterminado para $accepted_args es 1. Si queremos que nuestros scripts o estilos sean encolados antes, únicamente tenemos que indicar un valor inferior a al predeterminado para $priority. Por ejemplo:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
function wptuts_scripts_important() { // Register the script like this for a plugin: wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ) ); // or // Register the script like this for a theme: wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' ); // For either a plugin or a theme, you can then enqueue the script: wp_enqueue_script( 'custom-script' ); } add_action( 'wp_enqueue_scripts', 'wptuts_scripts_important', 5 ); |
El resultado de esto será el mismo que hemos visto antes, pero ocurrirá antes en el documento HTML.
Lo que te queda por leer:
-
Anular las librerías predeterminadas y usar una red de distribución de contenidos (CDN)
-
No seas codicioso
-
Esos scripts, ahora estilos
-
Entonces, ¿por qué no lo hace así todo el mundo?
-
Conclusión
Hola, gracias por tu post, me ha ayudado mucho.
Sólo una cosa, no veo ejemplos para CSS. ¿Se cargarían igual que los JS?
Gracias!
¡Hola Vicente! 🙂 Me alegro de que te haya resultado útil.
Sí para las hojas de estilo CSS sería igual salvo con una excepción, al registrar el estilo con
wp_register_style, ya no tenemos el parámetro$in_footerde los scripts, tenemos uno nuevo ($media) para especificar a qué tipo de medio afecta esa hoja de estilos. Acepta topos los tipos de medios definidos por W3C, como ‘all’, ‘print’, ‘speech’ y ‘screen’, e incluso media queries como ‘(orientation: portrait)’ y ‘(max-width: 640px)’.Si no indicas este parámetro, el valor predeterminado es ‘all’, es decir el estilo se cargará para todos los dispositivos, tamaños de pantalla, etc. Aquí tienes un ejemplo en el Codex de WordPress.
Saludos