Tutorial de tema de WordPress para principiantes – Parte 6: Funciones de un tema.php
Hoy aprenderemos dónde y cómo agregar código fuera de las plantillas en nuestro tema. Hacemos esto agregando el functions.phparchivo del tema. En el camino, también aprenderemos cómo agregar sus hojas de estilo y scripts de la manera adecuada.
El archivo functions.php de un tema
Un tema necesita un lugar para colocar el código que no forma parte de las plantillas. Siempre hay un montón de código que todos los temas necesitan agregar para manejar la funcionalidad. Por ejemplo, habilitar la función de imágenes destacadas de WordPress (¿notó que faltaba?), Soporte para menús, widgets, agregar hojas de estilo y scripts (de la manera adecuada), y más.
Ese archivo es functions.php. WordPress automáticamente y siempre carga este archivo si existe en su tema. Siempre se carga tanto en el administrador como en la interfaz.
Agregar un archivo functions.php a nuestro tema
Vamos a crear un nuevo archivo vacío en nuestra carpeta de tema raíz y asígnele el nombre functions.php.
En ese archivo, comience inmediatamente con una etiqueta PHP de apertura (<?php) y no incluya la etiqueta de cierre. El functions.phparchivo está diseñado para código PHP, no para HTML. Su tema puede romperse (o incluso actuar de manera extraña) si tiene caracteres o saltos de línea fuera de las etiquetas PHP en este archivo. Obviamente, puede salir de las etiquetas de PHP para generar HTML, pero debe hacerse dentro de funciones o ganchos. Permítanme explicar esto con un experimento.
Probemos este archivo para ver cómo funciona. Dentro functions.phpescribe un eco de algún texto ficticio:
<?php
echo 'This is an experiment';Actualice su interfaz. Aparece el texto ficticio. Pero si inspecciona o ve la fuente HTML, verá que el texto aparece antes de abrir <html>. ¡Esto hace que el HTML sea completamente inválido!
Vaya a su panel de administración y presione actualizar. También hace lo mismo allí (puede estar oculto detrás de la barra de administración, pero está allí en el HTML).
Como puede ver, cualquier código en sus functions.phpcargas antes que cualquier otra cosa en nuestras plantillas. Por lo tanto, como regla, cualquier salida (HTML fuera de las etiquetas de PHP o echo) debe estar dentro de funciones que se ejecutarán en los momentos adecuados, normalmente enganchadas a acciones o filtros.
Recuerde cuando aprendimos y agregamos ganchos en la parte 3 del tutorial de temas de WordPress para principiantes. La forma en que ejecutamos el código en un enlace es adjuntar una función al enlace con add_action(). Probemos algo más; hagamos una función enganchada a un gancho que ya tenemos definido en nuestras plantillas; wp_footer.
En functions.phpelimine lo echoque agregamos con fines de prueba y en su lugar escriba:
<?php
add_action('wp_footer', 'wptutorial_print_footer');
function wptutorial_print_footer() {
echo 'This sentence will appear in footer!';
}Haga clic en Actualizar en la interfaz y vea que la cadena aparece bien en el lugar exacto que ha definido wp_footer, justo antes de cerrar </body>. Además, tenga en cuenta que esto no hará eco de nada en admin. Esto se debe wp_footera que es un enlace que solo se ejecuta en la interfaz.
¡Hagamos nuestras primeras operaciones propias en functions.php!
Nota: En PHP no es posible tener dos funciones con exactamente el mismo nombre. ¡Eso incluye nombres de funciones en WordPress, su tema y cualquier complemento activado! Siga las mejores prácticas y prefije sus funciones con su slug de tema, como en el ejemplo anterior: " wptutorial_<function_name>". Esto reduce en gran medida que WordPress se bloquee fatalmente debido a nombres de funciones idénticos.
Nota 2: no importa en qué orden agregue funciones y enlaces en su archivo functions.php. Recuerde que los ganchos se ejecutan en ciertos puntos de control de todos modos, no en el orden en que están functions.php. La única excepción es si incluye otros archivos o inicializa sus propias clases.
La forma correcta de agregar estilos y scripts frente a la forma incorrecta
Algunos de ustedes recordarán la parte 3, donde agregamos el wp_headgancho en nuestro archivo header.php. Después de que hicimos esto, WordPress pudo cargar sus estilos y scripts, incluida la barra de administración. Podría estar pensando que para agregar nuestras hojas de estilo necesitamos hacer una función enganchada wp_heady generar el <link>para la hoja de estilo … ¡Por lo general, tendría razón!
Sin embargo, en WordPress hay una forma especial de agregar scripts y estilos. Esto es principalmente para administrar el orden de carga y evitar cargar bibliotecas duplicadas. Por ejemplo, es posible que usted, como autor de un tema, desee agregar Javascripts que dependan de la jQuerybiblioteca. Luego, debe asegurarse de que jQueryse cargue antes que sus archivos. Pero WordPress y cualquier complemento tienen la misma necesidad, para asegurarse de que jQuerytambién se cargue antes de sus scripts. No puede cargar la jQuerybiblioteca varias veces porque eso causa problemas. Entonces, WordPress tiene una forma de administrar en qué orden se cargan los scripts y las hojas de estilo.
Agregar hojas de estilo (de la manera correcta)
Para agregar estilos y javascripts, usamos un gancho llamado wp_enqueue_scripts. Sí, también usas este gancho para estilos, a pesar de su nombre. Agregar secuencias de comandos y estilos se conoce como "poner en cola", como poner en una cola. Pongamos en cola (agreguemos) nuestra hoja de estilo usando la función wp_enqueue_style en nuestro functions.php:
<?php
add_action('wp_enqueue_scripts', 'wptutorial_enqueue_scripts');
function wptutorial_enqueue_scripts() {
wp_enqueue_style('theme-main-style', get_stylesheet_directory_uri().'/style.css');
}La wp_enqueue_stylefunción toma como mínimo dos parámetros. El primero es un nombre único (identificador o «ID de slug"), y el segundo es la ubicación del archivo. El identificador debe ser único, ya que este es el identificador que usa WordPress para determinar si hay duplicados.
En cuanto a devolver la ruta a tu tema, hay muchas funciones disponibles. Arriba utilicé get_stylesheet_directory_uri()which devuelve la URL a la carpeta de su tema, y luego agregué el resto de la ruta a nuestra hoja de estilo.
PD: WordPress ofrece una función separada para devolver la URL completa a su tema style.css: get_stylesheet_uri(). Usé la otra función anterior porque es más útil familiarizarse con ella. Lo usará para cualquier otro archivo que necesite poner en cola.
La función wp_enqueue_styleacepta parámetros más útiles, como dependencias (que otros archivos css deben cargarse antes) y el número de versión (útil para fines de almacenamiento en caché).
¡ Actualice su interfaz y vea que su hoja de estilo está cargada en <head>la etiqueta!
Si usted es uno de los que están ansiosos por hacer que su tema se vea más bonito mientras lo codifica, esta es su oportunidad. Lo animo a comenzar a definir su HTML, clases y contenedores y agregar algo de estilo en su archivo style.css. Agregaremos más contenido que requerirá estilo a medida que avanzamos en esta serie de tutoriales.
Agregar scripts (de la manera correcta)
Veamos cómo agregamos javascripts a nuestro tema. Se hace usando el mismo gancho (así que puedes ponerlo todo dentro de una función). Pero para los scripts usamos una función ligeramente diferente.
Para poner en cola un script, usa wp_enqueue_script(). Los parámetros son los mismos que wp_enqueue_style(). El primero es el identificador único y el segundo es la ruta al script. Tercero (opcional) es la matriz de dependencias. Como cuarto parámetro (opcional) establece el número de versión. Y finalmente, quinto (opcional) define si el script debe cargarse o no en la <head>etiqueta o al final de </body>.
WordPress viene con una amplia gama de bibliotecas ya incluidas. No siempre están todos cargados, pero están disponibles si los necesita. Si desea agregar un script de biblioteca común, primero verifique si WordPress ya lo tiene. Los ejemplos son jQuery, todos los módulos jQuery UI, Underscore y Backbone.
Si agrega uno de los scripts incluidos de WordPress como una dependencia, ¡no necesita poner en cola ese script! Hagamos esto en la práctica.
Cree una carpeta assetsy dentro de ella una subcarpeta en nuestra carpeta de temas, y luego agregue un nuevo archivo jsvacío. main.jsDigamos que este script requiere la jQuerybiblioteca, así que lo configuramos como dependencia. Sabemos que WordPress viene con jQuerypaquetes y su identificador es jquery. Pondremos en cola nuestro script así:
<?php
add_action('wp_enqueue_scripts', 'wptutorial_enqueue_scripts');
function wptutorial_enqueue_scripts() {
wp_enqueue_style('theme-main-style', get_stylesheet_directory_uri().'/style.css');
wp_enqueue_script('theme-main-script', get_stylesheet_directory_uri().'/assets/js/main.js', ['jquery']);
}Si actualiza la interfaz y verifica su código fuente, debería ver que main.jsse agrega su secuencia de comandos, pero también que jQueryse carga la biblioteca. ¡Y jQueryse carga antes que su archivo!
Ahora ha aprendido a agregar estilos y scripts. Para agregar más archivos, agregue un wp_enqueue_style()o wp_enqueue_script()para cada nuevo archivo.