Cómo compilar SCSS con PHP: agregue variables al personalizador de WordPress para compilar el CSS del tema

Este tutorial le mostrará cómo agregar configuraciones de tema, por ejemplo, colores de tema, en el Personalizador de WordPress y volver a compilar la hoja de estilo del tema con las variables elegidas. Al tener un estilo de tema en SCSS usando una biblioteca, puede permitir que los usuarios de temas personalicen fácilmente cualquier variable en la hoja de estilo del tema, sin que tengan que editar los archivos SCSS.

Cualquier buen tema debería permitir una buena cantidad de personalización. Como mínimo, debería ser posible establecer los colores del tema principal. En lugar de escribir una gran cantidad de CSS feo para anular los colores del tema en todas partes, puede volver a compilar la hoja de estilo completa directamente desde el Personalizador. ¡Este tutorial te enseñará cómo!

Lo que haremos y lo que necesitamos

Supongo que su tema ya tiene un poco de estilo en los archivos SCSS que ya compila en el archivo principal del tema style.css. Y al usar SCSS, lo más probable es que defina cosas recurrentes, como colores, tamaños o puntos de interrupción, como variables SCSS, y use esas variables en su diseño.

Puede crear cualquier configuración del Personalizador que desee para las variables en su archivo SCSS. Los selectores de colores, las entradas de números y de texto son perfectos para esto. Mientras el usuario cambia la configuración en el Personalizador de WordPress, verá una vista previa del tema con las variables modificadas. Y cuando hagan clic en "Guardar", el CSS final se compilará en el archivo CSS de la hoja de estilo principal utilizando los valores elegidos.

Como ejemplo para este tutorial, supondré que el archivo SCSS de la hoja de estilo principal del tema hace lo mismo que @importun variables.scssarchivo. Allí hemos definido tres variables que queremos que sean personalizables en el Personalizador: dos colores y un tamaño de texto en formato px.

$main: #594c74 !default;
$secondary: #555 !default;
$text-size: 12px !default;

Tenga en cuenta que para permitir que SCSS redefina variables, deben definirse con !default. Esta es una regla en SCSS. Para que este tutorial funcione; cualquier variable que desee personalizar debe definirse como predeterminada en sus archivos SCSS.

Depende de usted cuándo (o si) desea sobrescribir el archivo CSS. Este tutorial asume que cuando el usuario hace clic en "Guardar" en el Personalizador, se volverá a compilar y escribir en el CSS del tema. Sin embargo, mientras la vista previa del Personalizador está activa y el usuario está cambiando la configuración (antes de hacer clic en Guardar), simplemente mostramos el CSS compilado en el encabezado de la vista previa del sitio web. No queremos sobrescribir el archivo CSS de inmediato en caso de que el usuario desee cancelar cualquier cambio que haya realizado.

  Tenga en cuenta…

Este tutorial sobrescribirá el style.cssarchivo del tema cada vez que se guarde la configuración del personalizador.

Supongo que ya compila sus archivos SCSS con un programa compilador (por ejemplo, Koala o línea de comandos). Tener este código en su tema sobrescribirá el archivo CSS, pero no cambiará sus archivos SCSS de origen. Esto significa que cada vez que realice cambios en el Personalizador y luego vuelva a sus archivos SCSS originales y los vuelva a compilar, ¡se perderán los ajustes de Personalización!

Hay varios métodos para evitar esto y depende de su proyecto y de cómo trabaje. En la mayoría de los casos no sería un problema. Por lo general, es solo algo a tener en cuenta mientras desarrolla su tema. Si le está dando su tema finalizado a otra persona para que lo use, normalmente no tocaría sus archivos SCSS de todos modos.

Con eso fuera del camino, comencemos a ver cómo hacemos esto:

1. Familiarizarse con la biblioteca SCSSPHP e incluirla en nuestro tema
2. Crear configuraciones personalizadas para cada variable SCSS que queremos que sea personalizable
3. Asegurarse de que el Personalizador obtenga una vista previa de los cambios sobre la marcha
4. Al guardar la configuración del Personalizador, volvemos a compilar y sobrescribimos el archivo CSS del tema.

1 La biblioteca SCSSPHP

Para compilar los archivos SCSS usaremos una biblioteca SCSSPHP de leafo (licencia MIT). Tenga en cuenta que este tutorial es para la biblioteca SCSS. El autor de la biblioteca tiene una biblioteca LESS PHP similar si prefiere usar LESS, pero recuerde que el siguiente tutorial es para la biblioteca SCSS.

¡La biblioteca SCSSPHP es realmente fácil de usar! Aquí hay una descripción general simplificada de cómo usaremos la biblioteca en el PHP de nuestro tema:

• Incluimos la biblioteca
• Cree una nueva instancia de la clase de compilador de la biblioteca
• Cargue el contenido del archivo SCSS de origen y páselo al objeto compilador
• Defina una matriz asociativa; Nombres de variables SCSS (incluido el $) como claves y sus valores. Cualquier elemento de esta matriz anulará las variables del mismo nombre en el archivo SCSS proporcionado.
• Le pedimos al objeto compilador que compile y reciba el CSS compilado como una cadena a cambio. Luego podemos generar este CSS dentro heado podemos escribirlo en el style.cssarchivo del tema.

  ¿Qué tipo de variables SCSS podemos compilar?

La respuesta simple es: ¡cualquier tipo de variable SCSS válida!

La biblioteca SCSSPHP puede compilar cualquier tipo de variable SCSS válida, pero tenga en cuenta que debe asegurarse de que tengan el formato correcto desde el Personalizador. Por ejemplo, los colores deben tener el prefijo a #para los colores hexadecimales o tener el formato de definiciones rgb()o. rgba()Una variable de tamaño generalmente necesitaría agregarse con ‘ px‘, ‘ em‘, ‘ %‘, y así sucesivamente.

Si planea crear un sistema avanzado para compilar variables SCSS a través del tema del personalizador, ¡asegúrese de tener un buen sistema para formatear correctamente cada tipo de variable!

Dejemos el primer paso fuera del camino; descargando e incluyendo la biblioteca en nuestro tema:

Descargar e incluir la biblioteca SCSSPHP en su tema

El primer paso es descargar la biblioteca SCSSPHP. En la página vinculada, haga clic en el botón "Descargar" en la parte superior. Si prefiere usar Composer, el sitio proporciona una guía al respecto.

Extraiga el zip en una subcarpeta en algún lugar dentro de su tema. Como ejemplo lo estoy colocando dentro de la theme/inc/scssphp/carpeta.

Abra el archivo PHP donde desea agregar su código para compilar. Puede estar directamente dentro de su tema functions.phpo un archivo PHP incluido por functions.php. En aras de la simplicidad, estoy escribiendo todo dentro functions.php.

Antes de que podamos usar la biblioteca, debemos incluirla; al igual que:

require_once(get_stylesheet_directory(). '/inc/scssphp/scss.inc.php');

Ajuste la ruta a sus archivos en consecuencia. Necesitamos incluir el scss.inc.phparchivo que se encuentra dentro de la carpeta raíz de la biblioteca. ¡Ahora, después de esta línea podemos usar las clases de la biblioteca!

2 Creación de la configuración del Personalizador para las variables SCSS

Vamos a crear la configuración del personalizador de WordPress para nuestras variables. Por el bien del tutorial, agregaremos configuraciones para las variables SCSS mencionadas anteriormente: dos selectores de color y una entrada de número.

No entraré en detalles para explicar cómo agregar la configuración del Personalizador; hay muchos tutoriales para esto. En el ejemplo de código a continuación, creo una nueva sección y coloco las tres configuraciones dentro:

Este código se engancha customize_registery agrega una sección llamada "Variables de tema". Luego procede a agregar un selector de color ‘ theme-main‘, otro selector de color ‘ theme-secondary‘ y una entrada de número ‘ theme-text-size‘. Esta es toda la funcionalidad predeterminada de WordPress. También agrego establecer el valor predeterminado de cada configuración en los mismos valores definidos en el variables.scssarchivo. Esto es solo para garantizar que la configuración del Personalizador se inicie con los colores correctos.

¡Se ve genial! Pero a partir de ahora no pasa nada cuando ajustas estas variables. Continuemos con el paso 3; manejo de la vista previa en el Personalizador.

3 Compile CSS sobre la marcha en la vista previa del Personalizador

Este paso maneja la actualización de la vista previa del Personalizador mientras el usuario cambia la configuración y no escribirá en ninguno de nuestros archivos. En su lugar, mostraremos el CSS compilado en <head>la vista previa dentro de una <style>etiqueta. De esta manera, nos aseguramos de que el CSS en línea anule todos los estilos del archivo CSS original.

Para verificar si actualmente estamos usando la vista previa del Personalizador, usamos la función [is_customize_preview](https://developer.wordpress.org/reference/functions/is_customize_preview/)(). Cuando esto regresa true, creamos una función enganchada a wp_head. Dentro de la función, iniciamos y configuramos la biblioteca SCSSPHP, buscamos los valores de configuración actuales, compilamos el CSS y lo generamos en una <style>etiqueta.

En línea #7, definimos la ruta al archivo SCSS de origen y cargamos su contenido en una variable en #8. Y en línea configuramos la ruta de importación para la biblioteca para garantizar que cualquier #9correo electrónico funcione correctamente en nuestros archivos SCSS. Puede leer más sobre esto en el sitio de documentación de la biblioteca, bajo el título "Rutas de importación". Básicamente, la biblioteca SCSSPHP necesita conocer la ruta relativa de su carpeta SCSS para que todas las rutas sean correctas.#10``@import@import

En línea #12-16creamos la matriz para el compilador; una matriz asociativa con los nombres de las variables como claves. Para los valores que usamos [get_theme_mod](https://developer.wordpress.org/reference/functions/get_theme_mod/)()para obtener los valores del Personalizador. La función get_theme_mod()le permite definir un valor predeterminado como segundo parámetro si el valor no se guardó. Esto nos evita bloquear el compilador con valores como null. Por lo tanto, proporcionamos el mismo valor predeterminado que en nuestro archivo de variables SCSS y cuando registramos la configuración del Personalizador.

También tenga en cuenta que el código en la línea #15agrega un ‘ px‘, lo que garantiza que el valor de la variable real sea válido. De lo contrario, se compilaría como " $text-size: 12;" cuando necesitemos " $text-size: 12px;". Proporcionamos la matriz de variables al compilador en la línea #17, diciéndole que compile usando estas variables.

Luego, en línea #19-22, llamamos a la compile()función que debería devolver el CSS compilado como una cadena. Damos salida a una <style>etiqueta con la cadena CSS dentro. Debido a que estamos enganchados a wp_head, el Personalizador mostrará la vista previa con el CSS modificado cada vez que se realice un cambio.

4 Guardar el CSS compilado en la hoja de estilo del tema

El código para compilar el CSS es muy similar al paso anterior. La única diferencia es que ahora estamos escribiendo el CSS en un archivo en lugar de generarlo. Realmente debería considerar poner esto en una función para que no repita el código, pero en aras de la claridad, he elegido separar los dos.

Nos conectamos a [customize_save_after](https://developer.wordpress.org/reference/hooks/customize_save_after/)qué disparadores cada vez que alguien hace clic en Guardar en el Personalizador de WordPress. En este punto, buscamos el SCSS de origen, definimos los valores de las variables y lo compilamos en CSS. Con la cadena CSS, usamos una función PHP simple para escribirla en el archivo CSS del tema.

La única diferencia con respecto a antes está en la línea #8donde definimos el archivo de destino para escribir y la línea #19donde escribimos en el archivo.

  Conclusión

Ahora tenemos la configuración del Personalizador que controla las variables en el archivo SCSS del tema y sobrescribe la hoja de estilo principal del tema usando esas variables. ¡No hay límite para la cantidad o el tipo de configuraciones que desea permitir que los usuarios del tema personalicen! Invierta algo de tiempo en configurar un sistema adecuado para manejar el formato de diferentes tipos de variables (p. ej., prefijos o postfijos) y estructurar correctamente la configuración del Personalizador. ¡Los usuarios del tema apreciarán la flexibilidad y lo fácil que es personalizar su tema!

También puede descubrir diferentes formas de manejar la escritura de archivos del CSS final. Si no desea sobrescribir la hoja de estilo principal, tal vez desee enviarla a un archivo diferente. También puede considerar el uso de condicionales if-else en SCSS.

Este tutorial fue escrito para brindarle un trampolín sobre cómo puede personalizar su tema de WordPress desde el Personalizador. ¡Avíseme si le sirvió de algo, o si desea un tutorial más avanzado que asegure que la hoja de estilo del tema no se sobrescriba!