La jerarquía de archivos de un tema para WordPress

Hace un par de semanas estuvimos hablando de los diferentes tipos de temas que podemos encontrar en WordPress. Allí aprendimos todo sobre los temas WordPress: qué son los temas básicos, los temas premium y los temas multipropósito; cómo personalizar un tema cualquiera usando temas hijo; qué son los temas nieto; y también cómo crear un tema usando starter themes y framework themes. Una entrada de lo más completa, vaya.

Como algunos de vosotros os habéis interesado por conocer un saber un poco mejor cómo crear un tema WordPress (casi) desde cero, he pensado que sería interesante hablar de la jerarquía de archivos de un tema WordPress. En esta entrada aprenderás las bases necesarias para entender qué pinta tiene un tema de WordPress y, con suerte, tendrás todo lo que necesitas para animarte a crear tu primer tema.

Antes de empezar…

Cualquiera puede dibujar una casita en un papel, pero no todos somos arquitectos. Con suerte, quizás tengamos las habilidades suficientes para montar la casita del perro y un par de muebles de IKEA, pero no me pidas que monte una casa con cara y ojos. Pues lo mismo pasa con el diseño web… Así que no te voy a mentir: crear un tema no es sencillo. Crear un tema bonito, usable y amigable para el usuario menos aún.

Por lo tanto, en esta entrada voy a enseñarte «todo» lo que necesitas saber para crear un tema WordPress con dos particularidades:

1. Obviaremos absolutamente todo lo relacionado con el diseño del tema en si y nos centraremos únicamente en el apartado técnico. En otras palabras, veremos lo que vendría siendo la maquetación del tema.
2. No empezaremos el tema de cero y usaremos el tema starter Underscores. ¿Por qué? Porque no tiene sentido partir de cero cuando disponemos de un esqueleto de calidad que nos da parte del trabajo hecho y porque, si eso es lo que te interesa, la propia documentación de WordPress te da la información que necesitas.

Así pues, una vez hechos los disclaimers pertinentes… vamos a ello.

El starter theme «Underscores»

Underscores es un tema starter cuyo único objetivo es darnos una base mínima sobre la que desarrollar nuestro propio tema, ofreciendo plantillas HTML bien documentadas y algunos hacks adicionales. Con él, podemos acelerar muchísimo la creación de un nuevo tema, ya que buena parte de las tareas que debemos hacer para poner un tema en marcha nos vendrán dadas de serie.

Nelio Forms

Un plugin de contacto fantástico que usa el editor de bloques. En su simplicidad está la potencia del plugin. Me encanta, es muy versátil y funciona de maravilla para mí.

Wajari Velasquez

WordPress.org

Descarga gratis

Versión premium

Pasos previos

Como imagino que ya sabes, todo tema debe tener un nombre único e inconfundible. Más que nada porque todos los temas que instalas en WordPress acaban en el directorio wp-content/themes/ dentro de su propia carpeta (algo así como wp-content/themes/twenty-seventeen/, wp-content/temes/nelio/, wp-content/themes/tu-tema/, etc) y por lo tanto debemos evitar colisiones entre ellos. Por suerte, si vas a montar un tema con Underscores esto es gratis.

Si vas a la página que he enlazado anteriormente (https://underscores.me), verás que hay un campo de texto llamado Theme Name (nombre del tema) junto a un botón Generate (generar). Simplemente pon el nombre del tema que quieras (yo, por ejemplo, he puesto Nelio Software), dale al botón y se descargará un fichero .zip con tu configuración, incluyendo prefijos para las funciones que define para que sean únicas (por ejemplo, en lugar de tener una función llamada setup que pueda dar conflictos con una función igual de otro tema, la nuestra se llama nelio_software_setup).

Ahora que ya tienes tu tema, instálalo en tu instalación de desarrollo WordPress, actívalo y ¡pongámonos manos a la obra!

Fichero principal

Si abres el directorio de tu tema y echas un vistazo dentro, verás que existen varios ficheros y directorios en su interior. No te asustes; cuando los conoces, todo tiene sentido.

El primero que vamos a comentar es el fichero style.css. Como su nombre y tipo indican, es el fichero que contiene los estilos de nuestro tema, pero también es el fichero que contiene meta información sobre el tema:

Como puedes ver, este fichero empieza con un comentario bastante extenso que parece seguir un formato especial. Y es que, efectivamente, sigue un formato especial. De las líneas 2 a la 11 vemos un conjunto de pares Atributo, Valor donde se van definiendo diferentes propiedades del tema: el nombre del mismo, la URL, su autor, una descripción… Por defecto estos campos vienen rellenados con información de Underscores, pero eres libre de cambiarlos por lo que más te guste.

Si te estás preguntando para qué sirve esta información… bueno, es la que se muestra en tu escritorio de WordPress, en el apartado Apariencia » Temas, y creo que también en el directorio de temas de WordPress:

Fichero de funciones

Los temas pueden definir de forma opcional un fichero de funciones llamado, ¿cómo no?, functions.php. Lo normal es que en este fichero definamos los hooks típicos para encolar la hoja de estilos y los scripts que sean necesarios en el tema, así como cualquier función adicional que nos ayude con el tema (las típicas helper functions). Básicamente se comporta como un plugin: si el tema está activo, el fichero se carga automáticamente, ejecutando su contenido cuando sea necesario.

Si echas un vistazo al fichero functions.php que ha creado Underscores por nosotros, verás que tienes un montón de cosas predefinidas y activadas por defecto. Veamos algunos ejemplos de lo que incluye:

1. Función nelio_software_setup. Esta es una función que se invoca justo después de haber cargado el tema en WordPress a través del hook after_setup_theme. En ella el tema define varias propiedades de nuestro tema como, por ejemplo, el soporte para imágenes destacadas en las entradas del blog, un menú de navegación, la posibilidad de poner un icono en el tema, el dominio de internacionalización del mismo, etc. En mi opinión, lo más interesante de esta función es que está definida en un bloque condicional: de esta forma, si alguien crea un tema hijo del tema que estamos creando, podrían redefinir esta función y adaptarlo fácilmente a sus necesidades.
2. Función nelio_software_widgets_init. Underscores también nos muestra cómo podemos registrar áreas en las que poner widgets a través de esta función. Como ves, no es nada complicado: simplemente hay que invocar la función register_sidebar durante la ejecución de la acción widgets_init.
3. Función nelio_software_scripts. Se trata de una de las funciones más importantes del tema, puesto que se encarga de encolar los scripts y estilos que el tema necesita para funcionar.

Ya ves que no hay nada excesivamente extraño aquí dentro, más allá de cuatro funciones para tunear y adaptar el tema a nuestras necesidades.

Un punto interesante que merece mención especial son las sentencias require que aparecen al final del mismo. Si te fijas, se incluyen varios ficheros que están definidos en el subdirectorio inc/, como por ejemplo inc/custom-header.php o inc/customizer.php. Básicamente, estamos ante un ejemplo de cómo organizar y mantener nuestro código limpio y ordenado.

Como es obvio, nadie nos obliga a meter absolutamente todas las funciones y personalizaciones de nuestro tema en un único fichero, sino que podemos distribuirlo y organizarlo en ficheros más pequeños con propósitos más concretos. Te recomiendo que repases los ficheros que hay en el subdirectorio inc/ para que entiendas un poco qué está pasando. De hecho, incluso puedes probar a comentar los diferentes require que hay en el functions.php y descubras qué pasa cuando no están…

Plantillas

Vale, hasta aquí hemos visto lo más básico de todo: cómo establecer la meta información del tema en el fichero style.css y cómo configurarlo y definir cualquier función de ayuda que necesitemos mediante el fichero functions.php. Pero se supone que estamos creando un tema el cual debe definir la apariencia de nuestra web, así que… ¿dónde definimos las plantillas HTML? ¿Cómo podemos hacer que las cosas se vean de una u otra forma?

La respuesta a esta pregunta la encontramos en los demás ficheros que encontramos en la raíz de nuestro tema. Si te fijas, existen varios archivos cuyos nombres son bastante auto-explicativos:

1. index.php es la plantilla por defecto de nuestro tema. Sirve para renderizar cualquier contenido de nuestra web, siempre que dicho contenido no tenga una plantilla específica diseñada para él.
2. comments.php es la plantilla que usamos para renderizar la sección de comentarios en nuestras entradas y páginas.
3. single.php es la plantilla que usamos para renderizar entradas del blog y que, por lo tanto, sobrescribe a index.php para este tipo de contenido.
4. page.php es similar a la anterior, pero en este caso la usamos para renderizar páginas de nuestra web.

Nada complicado, ¿verdad? Si tienes curiosidad por ver todas las plantillas que puedes llegar a crear y sus nombres, te recomiendo que veas la página del Codex donde te explican cómo crear un tema junto con la página donde explican la jerarquía de plantillas en WordPress.

¿Qué hay dentro de cada una de estas plantillas? Pues lo lógico, HTML para maquetar la página mezclado con un poco de código PHP para recuperar los datos de la página, entrada o contenido que sea que se vaya a pintar con ella. Por ejemplo, si miramos el fichero single.php (que, recordemos, sirve para pintar una entrada del blog), veremos lo siguiente:

Veamos qué está pasando línea a línea:

1. Lo primero que vemos en la línea 10 es una llamada a la función get_header. Esto sirve para cargar el HTML inicial con el que abrimos cualquier página HTML. Es decir, abrir la etiqueta html, seguida del head, el title, el body… Un poco más adelante lo vemos en detalle.
2. De forma paralela, en la línea 37 vemos la llamada a get_footer que, como puedes imaginar, sirve para cerrar la página HTML (cerrando la etiqueta body, html, etc).
3. Entre las líneas 13 y 33 es donde la magia ocurre. Por un lado, vemos que la plantilla define un poco de HTML. En concreto, vemos que el contenido de nuestra entrada estará dentro de un par de etiquetas div y main, con unos identificadores y clases por defecto que probablemente ya nos estén bien. Lo demás es, precisamente, recuperar la información sobre la entrada.
4. En la línea 17 entramos dentro del loop de WordPress. Si no sabes qué es, no te pierdas esta serie de entradas de Antonio sobre el tema.
5. En la línea 20 cargamos el fichero template-parts/content.php, que nos sirve para renderizar nuestra entrada. Si lo miras, verás que pinta el título, la imagen destacada, el contenido, etc.
6. En la línea 22 añade las opciones de navegación para saltar a entradas anteriores y siguientes.
7. En la línea 25 carga los comentarios de la entrada invocando la función comments_template, pero solo si los comentarios están activados, claro.
8. Finalmente, en la línea 36 incluye la sidebar que define nuestro tema.

Sencillo, ¿verdad?

Cabecera y Pie de página

En la raíz de nuestro tema también encontramos los ficheros header.php y footer.php. Como ya te he adelantado, sirven para «abrir» y «cerrar» el HTML resultante de nuestro tema. Creo que es más fácil verlo que explicarlo, así que aquí tienes la cabecera:

y aquí tienes el footer.php:

Como ves, ninguno de los dos ficheros es excesivamente complicado o entraña mayores misterios. De todas formas, y siguiendo la estela de lo que llevamos haciendo hasta ahora, veamos los puntos más relevantes de cada fichero:

1. Todas las etiquetas que se abren en el header.php y no se cierran, se acaban cerrando en el footer.php.
2. Un punto importantísimo del header.php es la llamada a la función wp_head, en la línea 20. Esta llamada debe realizarse dentro de la etiqueta head del tema y sirve para que los plugins y el propio tema puedan volcar sus scripts y estilos en el frontend.
3. Las siguientes líneas del header.php definen la parte común de todas las páginas (como, por ejemplo, la imagen de cabecera o el menú de navegación) y ya.
4. El footer.php añade también un poco de HTML común a todas las páginas (con, por ejemplo, el típico pie de página de «Esta web ha sido creada con WordPress«) y cierra las etiquetas que el header.php abrió pero no cerró.
5. De forma análoga al header.php, el footer.php incluye una llamada a la función wp_footer para que los plugins que así lo deseen o el propio tema puedan añadir scripts al final de la página (en lugar de hacerlo en la cabecera).

Buenas prácticas

Para acabar la entrada de hoy y evitar enrollarme mucho más, me gustaría compartir contigo cuatro sencillos consejos que te harán mejor maquetador:

1. Encolar estilos y scripts. Si te fijas, ninguna de las plantillas incluyen scripts o estilos directamente en el HTML. De hecho, acabamos de ver que el fichero header.php incluye una llamada especial a wp_head para que los plugins y el propio tema puedan incluir sus estilos y scripts. Así pues, nunca metas una etiqueta script o style en tu web; confía siempre en las funciones wp_enqueue_script y wp_enqueue_style de WordPress.
2. Ajustes del tema. Aunque empecemos con un tema sencillo, lo más normal es que a medida que avancemos en el desarrollo este se complique ligeramente y queramos incluir opciones para personalizarlo. Colores, iconos, barras laterales, etc. son algunos de los ejemplos típicos que vienen en mente. WordPress tiene su propio mecanismo para permitir personalizar los temas con el llamado Customizer, así que si quieres que tu tema sea personalizable, hazlo usando su API y no otros hechos a medida (como pasa con algunos temas más cutres).
3. Escapar y sanear datos. Esto es de primero de informática, pero no por ello debemos dejarlo de lado. Es muy importante que todo lo que pintes por pantalla esté correctamente escapado y que todos los datos que recojas de un input del usuario estén correctamente saneados. Si no tienes ni idea de qué estoy hablando, lee esta entrada de la documentación de WordPress.
4. Internacionalización. Si quieres que tu tema sea usable para todo el mundo, ¿qué menos que permitir que pueda traducirse a cualquier idioma? Así que acostúmbrate a usar las funciones de internacionalización desde el primer momento para que todas las cadenas de texto que aparezcan en tu tema puedan ser traducidas y adaptadas a todos los idiomas.
5. Theme Check. Existe un plugin en el repositorio de WordPress llamado Theme Check que escanea tu tema y comprueba fallos típicos que puedes haber introducido en tu código sin darte cuenta. De hecho, este es el plugin que usan los validadores de temas de WordPress.org para decidir si un tema puede aparecer o no en el directorio de temas de WordPress, así que su utilidad está más que garantizada. Cuando estés trabajando en tu tema, ten este plugin activo y ve comprobando que todo esté en orden; te ahorrará quebraderos de cabeza en el futuro.

Resumiendo

Los temas en WordPress siguen una estructura bastante lógica y amigable. Al tratarse de código PHP, puedes organizar el código un poco como te dé la gana, si bien es cierto que hay un conjunto de ficheros que WordPress espera que estén para que todo funcione. Espero que la entrada de hoy te haya servido para entender un poco más dicha estructura y, sobretodo, para que valores la utilidad de un tema starter como Underscores para crear tu primer tema.

¡A maquetar!

Imagen destacada de Joe LIU en Unsplash.