Como crear bloques dinámicos con render_callback en PHP en WordPress

Introducción

Este artículo explica con todo detalle cómo crear bloques dinámicos en WordPress usando render_callback en PHP. Un bloque dinámico es aquel cuyo HTML se genera en el servidor cada vez que se renderiza (tanto en el editor como en el front), lo que permite mostrar contenido actualizado, ejecutar consultas a la base de datos, aplicar lógica condicional y usar caché en el servidor.

Conceptos clave

• render_callback: función PHP que se ejecuta para generar el HTML del bloque en tiempo de renderizado.
• Atributos: definidos en block.json o en la llamada de registro son enviados desde el editor al servidor y pasados a render_callback.
• Server-side rendering: renderizado en servidor el bloque no guarda HTML en el contenido (la función save generalmente devuelve null o no se define en la parte JS).

Requisitos previos

1. WordPress 5.5 (se recomienda versión reciente).
2. Conocimientos básicos de la API de bloques (registerBlockType), PHP y seguridad en WP.
3. Entorno para desarrollar plugins o un tema con soporte para bloques preferible usar WP-CLI o @wordpress/scripts para la parte JS.

Flujo general

1. Definir el bloque (block.json) con atributos y editorScript.
2. Registrar los scripts y estilos del editor en PHP o mediante block.json.
3. Registrar el bloque en PHP con register_block_type y proporcionar render_callback.
4. Implementar la función PHP para generar el HTML, cuidando seguridad y rendimiento (caché si procede).
5. En el editor, opcionalmente mostrar vista previa con ServerSideRender o un edit personalizado.

Ejemplo mínimo: estructura de archivos

• my-plugin/
  • block.json
  • build/editor.js (o src/editor.js)
  • my-plugin.php (archivo principal del plugin)

block.json (metadatos básicos)

{
  apiVersion: 2,
  name: mi-plugin/bloque-dinamico-ejemplo,
  title: Bloque Dinámico Ejemplo,
  category: widgets,
  attributes: {
    title: {
      type: string,
      default: Título por defecto
    },
    postsNumber: {
      type: number,
      default: 5
    }
  },
  editorScript: file:./build/editor.js
}

editor.js (registro en JavaScript, uso de ServerSideRender para previsualizar)

import { registerBlockType } from @wordpress/blocks
import { useBlockProps, InspectorControls } from @wordpress/block-editor
import { PanelBody, RangeControl, TextControl } from @wordpress/components
import ServerSideRender from @wordpress/server-side-render

registerBlockType(mi-plugin/bloque-dinamico-ejemplo, {
  edit: (props) => {
    const { attributes, setAttributes } = props
    const blockProps = useBlockProps()

    return (
      

        
          
             setAttributes({ title: val })}
            />
             setAttributes({ postsNumber: val })}
              min={1}
              max={10}
            />
          
        

        
      
    )
  },

  save: () => {
    // Renderizado en servidor, por tanto save devuelve null
    return null
  }
})

Registro del bloque y render_callback en PHP

La parte de PHP se encarga de registrar el bloque y definir la función que generará el HTML en el servidor. A partir de WP 5.5 se puede usar register_block_type pasándole la ruta al directorio con block.json WordPress registrará los assets automáticamente si en block.json se indica editorScript/file:…

Archivo principal del plugin (my-plugin.php)

Si prefieres registrar manualmente y especificar render_callback:

 mi-plugin-editor-script,
        render_callback => mi_plugin_render_bloque_dinamico,
        attributes      => array(
            title => array(
                type => string,
                default => Título por defecto,
            ),
            postsNumber => array(
                type => number,
                default => 5,
            ),
        ),
    ) )
}
add_action( init, mi_plugin_registrar_bloque_manual )

Implementación del render_callback en PHP

La función de renderizado recibirá los atributos (y opcionalmente el contenido ya guardado y el objeto block). Debes sanitizar y escapar cualquier dato antes de imprimirlo. A continuación un ejemplo que consulta posts y aplica caché por transient para mejorar rendimiento.

 posts_number,
        post_status    => publish,
        no_found_rows  => true,
    ) )

    // Construir salida (usar funciones de escape)
    html  = 

    html .= 
 . esc_html( title ) . 
    if ( query->have_posts() ) {
        html .= 

        while ( query->have_posts() ) {
            query->the_post()
            post_title = get_the_title()
            post_link  = get_permalink()
            html .= 

            html .=  . esc_html( post_title ) . 
            html .= 
        }
        html .= 
        wp_reset_postdata()
    } else {
        html .= 
 . esc_html__( No hay entradas disponibles., mi-plugin ) . 
    }
    html .= 

    // Guardar en transient por 5 minutos
    set_transient( cache_key, html, 5  MINUTE_IN_SECONDS )

    return html
}

Buenas prácticas y seguridad

Escapar salida: siempre usa esc_html, esc_url, wp_kses_post, etc., según el contexto.
Saneamiento de atributos: sanitize_text_field, intval, wp_kses_post (si aceptas HTML) antes de usarlos.
Uso de transients: para evitar consultas repetidas recuerda invalidar caché cuando cambien datos relevantes.
Capacidades: si el bloque muestra datos sensibles o controles de edición, valida current_user_can() donde proceda.
Internacionalización: usa __(), esc_html__() con dominio de texto.
Evitar consultas costosas: usa no_found_rows => true y limita los campos si es posible.

Depuración y pruebas

Activa WP_DEBUG en desarrollo para ver errores PHP.
Prueba distintos atributos desde el editor y comprueba la vista previa (ServerSideRender ayuda a ello).
Verifica que la caché se invalida cuando cambian parámetros críticos (p. ej. al guardar el bloque o al publicar un post que debería aparecer).
Usa herramientas de inspección (Network, consola) para comprobar que los assets se cargan correctamente.

Casos de uso típicos de bloques dinámicos

Listados de entradas recientes o relacionadas.
Widgets con datos externos (APIs) que precisan consultarse en cada render.
Bloques que deben mostrar contenido sensible al rol o estado del usuario (por ejemplo, contenido diferente para usuarios conectados).
Bloques que dependen de cálculos o datos que cambian frecuentemente y no conviene almacenar como HTML estático.

Notas finales y recomendaciones

Los bloques dinámicos con render_callback son muy potentes, pero traen responsabilidades: prestar atención a la seguridad, al rendimiento y a la experiencia en el editor. Utiliza transients o mecanismos de caché apropiados para no generar consultas innecesarias, y siempre sanea/escapa datos. Si usas build tools como @wordpress/scripts, aprovecha block.json para simplificar el registro de assets.

Enlaces útiles

Documentación del Block Editor
register_block_type()
hook init










	
	
Acepto donaciones de BAT's mediante el navegador Brave 🙂









¡Si  te  ha  servido  el  artículo  ayúdame  compartiendolo  en  algún  sitio!  Pero  si  no  te  ha  sido  útil  o  tienes  dudas  déjame  un  comentario! 🙂

				
				X
			

				
				Facebook
			

				
				WhatsApp
			

				
				Tumblr
			

				
				Reddit
			

				
				Pocket
			


	
Relacionado