WordPress block themes (en español)

WordPress block themes, es un tema muy extenso y este post no es un post como tal sino que se ira extendiendo con el tiempo, tampoco es un post dedicado para usted el lector sino para razones internas de esta página, aunque sí que le puede servir.

En este post intentaremos entender los block themes como tal y tratar de sobrepasar algunas limitaciones con las que me he topado en ellos.

Al parecer los block themes deben hacerse a través del editor de WordPress estos deben de tener los siguientes archivos para poder funcionar.

• 📁Templates
  • 📄index.html
• 📄style.css
• 📄functions.php( este archivo es opcional en los block themes)  

En general los Block themes tienen la siguiente estructura:

• 📁parts/
  • 📄footer.html
  • 📄header.html
• 📁patterns/
  • 📄example.php
• 📁styles/
  • 📄example.json
• 📁templates/
  • 📄404.html
  • 📄archive.html
  • 📄index.html (required)
  • 📄singular.html
• 📄functions.php
• 📄screenshot.png
• 📄style.css (required)
• 📄theme.json  
• 📄README.txt

El archivo style.css

El archivo style.css debe de tener un header el cual es un comentario parecido al siguiente;

/**  * Theme Name:        Fabled Sunset  
* Theme URI:            https://example.com/fabled-sunset  
* Description:           Custom theme description...  
* Version:                  1.0.0  
* Author:                   Your Name  
* Author URI:            https://example.com  
* Tags:                        block-patterns, full-site-editing  
* Text Domain:          fabled-sunset  
* Domain Path:         /assets/lang  
* Tested up to:          6.4  
* Requires at least:  6.2  
* Requires PHP:        7.4  
* License:                   GNU General Public License v2.0 or later  
* License URI:            https://www.gnu.org/licenses/gpl-2.0.html  
*/

En caso de que el tema sea para la venta la licencia debe ser cambiada

¿Dónde se guardan los patterns y templates que creamos para nuestro Block Theme de WordPress?

Esa es una pregunta que deberíamos hacernos cuando estamos trabajando con temas de WordPress que son Block Themes.

Cuando creamos los archivos y carpetas, podríamos pensar que estos están siendo abiertos y guardados. Sin embargo, esto no es así, y está bien que no funcione de esa manera.

Estos en cambio son guardados en nuestra base de datos. Estos son guardado como los siguientes tipos de entrada:

• wp_template: Plantillas de página personalizadas.
• wp_template_part: Partes de plantilla reutilizables.
• wp_global_styles: Estilos globales del sitio.

¿Porque es asi y no directo en los archivos?

Si nos ponemos a pensar, esta es la manera más práctica de trabajar con temas de WordPress, ya que estas entradas pueden ser eliminadas. Y, en caso de que nos gusten, podemos copiar el pattern o el template a un archivo de nuestro tema en desarrollo.

Que te queden duplicados no hay problema; borras las que están en la base de datos y listo.

¿Cómo puedo borrar la versión que se encuentra en la base de datos?

Deberíamos de ir a Apparence > Editor.

Dentro de Editor, deberíamos de elegir Templates o Patterns. Luego, abre un pattern o un template. Arriba del todo debería de aparecerte el símbolo de una llave (Create Block Themes). Aquí tendrás una cantidad de opciones para el tema, la cual una de ellas es Reset Theme.

Recomendaciones para hacer temas de WordPress.

Mi recomendación personal es que, en vez de crear un solo tema, crees dos: el tema que vas a crear limpio y un tema auxiliar donde harás los diferentes patrones (patterns) y plantillas (templates). De este último, copia lo que te sirva al tema principal. Esto será mucho más prolijo que hacerlo directamente en el tema e ir limpiando la base de datos.

Código PHP y los block themes de WordPress

Por lo general en los block themes tenemos casi todo cubierto, tenemos el WordPress loop(query loop), y la paginacion(por general esta dentro del query loop), cubiertos.

por tanto se evita tener PHP en ellos pero no es una obligacion no tenerlo aunque esta no es la mejor de las ideas. Podriamos usar functions.php tambien pero hay una mejor opcion que es @wordpress/create-block.

Además de lo anteriormente expuesto, tenemos un problema, y es que si intentas crear esta clase de bloques desde WordPress con el bloque HTML, este comentará todo código PHP. Por ejemplo, supón que tienes una función breadcrumb e intentas llamarla así: <?php breadcrumb(); ?>. Este código será comentado por WordPress por motivos de seguridad.

Por tanto lo mejor seria hacer la estructura del bloque copiarla a un archivo por ejemplo en patterns/breadcrumb.php esto hara que cuando vayamos a edicion tengamos un pattern breadcrumb

Lo mejor seria crear nuestro bloque particular con @wordpress/create-block.

usando bloque y functions.php

ejemplo de pattern breadcrumb:

<?php
/**
 * Title: Breadcrumb
 * Slug: temaPracticasBLocks/breadcrumb
 * Categories: common
 */

 ?>
<!-- wp:columns {"style":{"border":{"width":"2px","color":"#000000","radius":"7px"}}} -->
<div class="wp-block-columns has-border-color" style="border-color:#000000;border-width:2px;border-radius:7px"> 
  <!-- wp:column -->
  <div class="wp-block-column">
  <?php mi_breadcrumb();?>
  </div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->

y en caso de nuestra funcion en functions.php seria la siguiente:

function mi_breadcrumb() {
    global $wp_query;
    $message = "";
    if (!is_front_page()) {
        
        if (is_category() || is_single()) {
            $message .= get_the_category().">";
        }
        if (is_single()) {
            the_title();
        } elseif (is_page()) {
            $message .= get_the_title()."";

        } elseif (is_search()) {
            $message = 'Resultados de búsqueda para: ' . esc_html(get_search_query());
        }
        

        $home = esc_url(home_url('/'));
        $html = <<<HTML
            <div class="breadcrumb">
                <a href="{$home}">Inicio</a> » $message
            <div>
        HTML;
        echo $html;
    }
}
add_action('wp', 'mi_breadcrumb');

ok si probamos algo que no esperamos pasara: Block contains unexpected or invalid

¿que a pasado? Bueno, esto realmente no es algo malo sino que es contenido que el editor no puede procesar lo, lo ideal seria que hicieramos contenido estatico para este comportamiento haciendo un if(is_admin)

function mi_breadcrumb() {
    if (is_admin()) {
        // Contenido estático para la vista previa en el editor
    } else {
        // contenido dinamico(logica de funcion)
    }
}

La herramienta @wordpress/create-block

Esta herramienta es un paquete de node.js la cual nos ayudara a crear bloques para nuestro tema, estos bloques son creados como un plugin y esta es una parte de las cuales no me gusta demasiado la parte de los block themes, si estas creando un block theme esperas un tema no un tema y un block que es un plugin.

En https://developer.wordpress.org/block-editor/getting-started/tutorial/ hay un buen tutorial de como hacer un block plugin.

En ese tutorial talvez te hable sobre  @wordpress/env esta es una manera diferente de levantar wordpress en tu maquina local con node

Aunque esto no me agrada demasiado por las razones que explique antes, de todos modos haremos un pequeño tutorial aqui mismo.

Crearemos el mismo breadcumb de antes pero esta vez con @wordpress/create-block.

Instalando Node.js

Para poder utilizar esta herramienta, necesitarás Node.js.

Linux

puedes instalarlo con el archivo binario. En ‘Instalación de Node en Linux‘ encontrarás una manera de instalarlo en Linux.

Windows

simplemente descarga el archivo de instalación e instálalo, o usa Chocolatey para instalarlo si ya lo tienes instalado en tu Windows.

choco install nodejs

Mac

baja el archivo de instalacion e instalalo o usa Hombrew para instalarlo.

brew install node

En todos los casos puedes usar NVM para instalar Node siempre y cuando lo tengas instalado.

La herramienta npx

Esta herramienta viene en forma de comando en la instalación de Node.js desde la versión 5.2.0 de npm y nos permite ejecutar un paquete npm, ya sea local o remoto

En pocas palabras, no tienes por qué instalar el paquete en tu sistema, ni globalmente en tu PC ni de forma local.

Volviendo a @wordpress/create-block, npx nos ayudará a crear nuestro block plugin sin necesidad de instalar el paquete permanentemente.(no dejara residuos)

¿Donde usaremos npx?

En nuestro caso deberiamos de usar el comando npx en la carpeta de plugins ya que lo haremos sobre una instalacion de WordPress para que esto sea lo mas simple de entender, pero tenga en cuenta que el usar npx @wordpress/create-block@latest podria ser usado en cualquier carpeta y luego levantado con wp-env para probar el plugin

ejemplo supongamos que tengo NGINX instalado en mi PC y esta instalado en la carpeta de usuario entonces la instalacion de WordPress sera wthemes deberia posicionarme en:

C:\Users\myuser\Nginx\html\wthemes\wp-content\plugins

y luego correr el siguiente comando

npx @wordpress/create-block@latest block_name

npx @wordpress/create-block@latest --help

Usage: wp-create-block [options] [slug]

Generates PHP, JS and CSS code for registering a WordPress plugin with blocks.

[slug] is optional. When provided, it triggers the quick mode where it is used as the block slug used for its identification, the output location for scaffolded files, and the name of the WordPress plugin.The rest of the configuration is set to all default values unless overridden with some options listed below.

Options:
  -V, --version                output the version number
  -t, --template         project template type name; allowed values: "standard", "es5", the name of an external
                               npm package, or the path to a local directory (default: "standard")
  --variant           the variant of the template to use
  --no-plugin                  scaffold only block files
  --target-dir      the directory where the files will be scaffolded, defaults to the slug
  --namespace           internal namespace for the block name
  --title               display title for the block and the WordPress plugin
  --short-description   short description for the block and the WordPress plugin
  --category             category name for the block
  --wp-scripts                 enable integration with `@wordpress/scripts` package
  --no-wp-scripts              disable integration with `@wordpress/scripts` package
  --wp-env                     enable integration with `@wordpress/env` package
  -h, --help                   display help for command

Examples:
  $ wp-create-block
  $ wp-create-block todo-list
  $ wp-create-block todo-list --template es5 --title "TODO List"

Comprendiendo lo creado

Recordemos que el ejemplo es un breadcrumb asi que lo que haremos sera correr el codigo npx @wordpress/create-block@latest breadcrumb pero ademas de esto tendremos que decirle que la variante es dinamica con la flag --variant=dynamic

De esta manera le indicaremos que se generará o modificará de manera dinámica, es decir, en tiempo de ejecución.

npx @wordpress/create-block@latest --variant=dynamic breadcrumb

una vez que cree al plugin si vamos a la carpeta de plugins deberiamos de ver una carpeta llamada breadcrumb

• 📁breadcrumb
  • 📁build
  • 📁node_modules
  • 📁src
  • 📄.editorconfig
  • 📄gitignore
  • 📄breadcrumb.php
  • 📄package.json
  • 📄package-lock.json
  • 📄readme.txt

Ahora, si vamos en nuestro WordPress al editor, deberíamos tener nuestro elemento breadcrumb. Sin embargo, aún no hemos terminado. Aún nos falta el código para este elemento.

Tal como está, es solo un elemento de decoración, no tiene utilidad alguna.

Pero antes de entrar a crear codigo debemos de entender las carpetas que tenemos

build:

• Es la carpeta donde tendremos la compilación, donde se genera el código final. Este es el código que, como plugin, deberíamos pasarle al usuario final.

node_modules:

• Contiene las librerías necesarias para el desarrollo.

src:

• Es la carpeta de «source» (fuente), es la carpeta donde estará nuestro código.

You can run several commands inside:

  $ npm start
    Starts the build for development.

  $ npm run build
    Builds the code for production.

  $ npm run format
    Formats files.

  $ npm run lint:css
    Lints CSS files.

  $ npm run lint:js
    Lints JavaScript files.

  $ npm run plugin-zip
    Creates a zip file for a WordPress plugin.

  $ npm run packages-update
    Updates WordPress packages to the latest version.

To enter the directory type:

  $ cd anotherblockplugin

You can start development with:

  $ npm start

Es probable que, una vez ejecutes npx @wordpress/create-block@latest, desees ejecutar npm start. Para ello, debes posicionarte en la carpeta de tu blockplugin.

Tambien debes de tener en cuenta que deberas utilizar el comando npm start cuando hagas cambios en tu css y javascript.

La carpeta src