Cómo hacer bloques de Gutenberg personalizados con Advanced Custom Fields Pro

Desde la versión 5.8 de Advanced Custom Fields (ACF) Pro, puede usar ACF para crear bloques de Gutenberg personalizados. Todo lo que necesita manejar son las plantillas de PHP. Esto hace que sea muy fácil para los desarrolladores que aún no tienen experiencia en el Javascript moderno requerido para crear bloques personalizados para Gutenberg con cualquiera de los tipos de campo que ACF tiene para ofrecer. Tenga en cuenta que esta funcionalidad solo está disponible en la versión paga (Pro) de Advanced Custom Fields. No está disponible en la versión gratuita, por lo que deberá comprar una licencia.

Si eres un editor de WordPress o un webmaster que no quiere profundizar en la codificación, esta publicación es definitivamente para ti. Sin embargo, si quieres ser un desarrollador de temas o complementos de WordPress, te recomiendo dar el paso para aprender a crear tus propios bloques personalizados. Sin embargo, el uso de campos personalizados avanzados para crear bloques puede proporcionar una buena introducción al manejo de bloques personalizados en Gutenberg.

Crear un bloque de Gutenberg con ACF

Básicamente, hay tres pasos simples para crear un bloque de Gutenberg personalizado con campos personalizados avanzados. El primero es fácil y probablemente familiar; configurando los campos (settings) que deseas tener en tu bloque. El segundo paso es usar la función de ACF para registrar un bloque de Gutenberg. Y el tercer paso es escribir la plantilla PHP para el bloque. Simplemente escriba el HTML y maneje la configuración como lo haría con los campos ACF de otra manera. ¡Y eso es! (Está bien, tal vez haya un cuarto paso: diseñar tu bloque. Pero no entraré en eso en esta publicación).

Crea tus configuraciones/campos

Si ha utilizado campos personalizados avanzados antes, probablemente sepa cómo configurar campos. Puede usar la interfaz de usuario de administración de Advanced Custom Field para hacer esto. O si desea que la configuración del bloque se incruste en su complemento o tema, escriba la configuración con PHP. Tengo una publicación de referencia completa sobre cómo agregar la configuración de ACF con PHP.

Lo más importante que debe hacer con su grupo es establecer la ubicación en "Bloquear". Pero debido a que aún no hemos registrado nuestro bloque, se establecerá de forma predeterminada en "Todos". Déjelo así, guarde sus campos y procedamos a registrando nuestro bloque.

Registrar un bloque de Gutenberg

En el código de su tema functions.phpo complemento, debe escribir una función vinculada acf/inity llamar [acf_register_block](https://www.advancedcustomfields.com/resources/acf_register_block_type/)()para registrar un bloque. Como esta función es bastante nueva en ACF y depende de que se active un complemento, le recomiendo que envuelva su código dentro de una verificación if para asegurarse de que su tema o complemento no bloquee su WordPress.

Registrar un bloque con ACF es similar a cómo registraríamos manualmente un bloque de Gutenberg personalizado. Con ACF, debe proporcionar un nombre slugified único para su bloqueo name. Recomiendo usar un nombre que se explique por sí mismo, por ejemplo, ctapara un bloque de llamada a la acción, o author-cardpara un bloque que muestre autores o similar. Si está algo familiarizado con Gutenberg, es posible que sepa que todos los bloques deben registrarse con un espacio de nombres, un /y luego su nombre de slug. Por ejemplo, el espacio de nombres de WordPress es core, por lo que, por ejemplo, el bloque de párrafo en WordPress se llama core/paragraph. Con ACF, el espacio de nombres será acf, por lo que, por ejemplo, el bloque anterior se registrará en Gutenberg como acf/yourblock. Si está registrando sus campos con PHP, como verá más adelante, debemos recordar esto.

En categorydefines en qué categoría de Gutenberg quieres que aparezca tu bloque. Por el momento los valores posibles son common, formatting, layout, widgetso embed. Si crea categorías personalizadas de Gutenberg, puede agregarlas si lo desea. En cuanto a iconproporcionar cualquier nombre de icono de WordPress Dashicons (menos los).

Para informar a ACF cómo renderizar este bloque, tiene dos opciones: proporcionar un nombre de función a la clave render_callback(como arriba), o proporcionar un nombre de plantilla en su tema a la clave render_template. Entonces, si prefiere referirse directamente a una plantilla, por ejemplo, template-parts/block-yourblock.phpen su tema, simplemente hágalo así y elimine render_callback:

Conecte su grupo de campo a su bloque registrado

Cuando esté satisfecho con su código de registro de bloque, es hora de conectar su bloque a la configuración que realizó anteriormente. Si creó los campos en admin, simplemente regrese y elija su bloque en Ubicación. Y si agregó el grupo de campo con PHP, en la ubicación proporcione el valor ‘ acf/yourblock‘ donde yourblockestá lo que proporcionó como se indicó nameanteriormente.

escribir la plantilla

¡El paso final, y el más divertido, es escribir la plantilla para la salida del bloque!

La ubicación de la salida de representación de su bloque depende de lo que haya decidido usar en el registro de su bloque, render_callbacko render_template.

Si proporcionó un nombre de función render_callback, debe definir esta función en el functions.phpcódigo de su tema o complemento. Obtiene cuatro parámetros para su función, como verá a continuación:

El primer parámetro, $blockcontiene cierta información de Gutenberg. Por ejemplo, cada bloque de Gutenberg casi siempre tendrá className, que debe establecer como clase en su contenedor más externo. $block['align']para la alineación también se puede configurar y algo que desee agregar también. El segundo parámetro, $contentsiempre estará vacío con ACF (esto se completaría si agregara bloques anidados, pero eso no es posible con ACF). El valor booleano $is_previewserá verdadero si actualmente estamos mirando el procesamiento de bloques en modo de vista previa en el editor de Gutenberg. Y finalmente $post_idestá la publicación en la que se agrega este bloque.

En cuanto a los campos, obtiene campos como lo haría normalmente, con get_field(). La salida HTML depende completamente de usted y de cómo desea generar sus campos.

Si proporcionó un archivo de plantilla en render_templatesu lugar, simplemente cree el archivo en la ubicación especificada en su tema. En su interior tiene acceso a las mismas variables globales exactas que con la función anterior (por ejemplo $block). Por ejemplo:

Y eso es todo lo que hay que hacer. Así de sencillo es crear tus bloques de Gutenberg personalizados con ACF.

Conclusión

Así de fácil fue, depender de un complemento, particularmente uno pagado, no es una buena solución final si desea desarrollar temas o complementos. Tenga en cuenta que sus bloques dejarán de funcionar si mueve el código de su tema a otro WordPress sin ACF Pro. O donde la configuración de su campo no se haya configurado (a menos que los incruste en su código con PHP o se asegure de exportarlos e importarlos). Como desarrollador de temas (o complementos) que distribuye código, no puede esperar que todos los usuarios compren su propia licencia de ACF Pro para que su tema funcione. Pero esta es una buena solución temporal para aquellos que no pueden o no necesitan codificar.

Si está convencido de que necesita dar el paso y aprender Javascript y Gutenberg, consulte mi introducción a la publicación de Gutenberg o la categoría de Gutenberg en este sitio para obtener más información.