Contents
Introducción
Este tutorial explica, paso a paso y con ejemplos prácticos, cómo usar el editor de bloques (Gutenberg) para leer y escribir metadatos (post meta) usando JavaScript. Verás cómo registrar los metadatos en PHP para que estén disponibles en la REST API, y varias formas de manipular esos metadatos desde el editor con APIs modernas de Gutenberg: useEntityProp, useSelect/useDispatch y la vinculación de atributos de bloque a metadatos.
Requisitos y consideraciones
- WordPress 5.3 (se recomienda la última versión estable).
- Conocimientos básicos de PHP y JavaScript (React/JSX moderno).
- Acceso para añadir código a un plugin o al tema (recomendado crear un plugin pequeño para esto).
- Tener en cuenta seguridad y permisos: define capability o auth_callback al registrar metadatos.
Paso 1 — Registrar el meta en PHP
Para que el editor pueda leer y escribir el meta vía REST API debemos registrarlo usando register_post_meta (o register_meta). Asegúrate de exponerlo con show_in_rest y definir su tipo y callbacks para sanitizar y autorizar.
Ejemplo mínimo en PHP (colócalo en tu plugin o en functions.php):
true,
single => true,
type => string,
auth_callback => function() {
return current_user_can( edit_posts )
},
sanitize_callback => sanitize_text_field,
) )
}
?>
Notas:
- post puede cambiarse por el post type que necesites (ej. page, my_custom_post).
- single indica si es un valor único o un array.
- auth_callback evita que usuarios no autorizados lean o escriban el meta.
- También puedes usar register_meta si necesitas un scope más genérico.
Paso 2 — Preparar la carga del script del editor
Enlaza un script que se cargue en el editor usando enqueue_block_editor_assets o registrando tu bloque con register_block_type y especificando editor_script. Aquí un ejemplo sencillo usando enqueue_block_editor_assets para un script que añadirá una interfaz en el editor.
Paso 3 — Leer y escribir meta desde JavaScript
A continuación se muestran varias formas para interactuar con metadatos desde el editor.
Opción A — useEntityProp (recomendada para manipular meta de la entrada)
useEntityProp es la forma más directa y declarativa de obtener y actualizar propiedades de una entidad (post) como el meta. Importa la función desde @wordpress/core-data.
/
Ejemplo: un panel en la barra lateral que muestra y edita mi_meta_clave
/
import { useEntityProp } from @wordpress/core-data
import { PanelBody, TextControl } from @wordpress/components
import { PluginDocumentSettingPanel } from @wordpress/edit-post
import { useState } from @wordpress/element
function MiMetaSidebarPanel() {
// postType y post se usan para la entidad de la entrada actual
const [ meta, setMeta ] = useEntityProp( postType, post, meta )
// Acceder al valor actual
const valor = meta[mi_meta_clave]
// Actualizar el meta: setMeta recibe un objeto completo de meta
const actualizar = ( nuevo ) => {
setMeta( { ...meta, mi_meta_clave: nuevo } )
}
return (
)
}
export default MiMetaSidebarPanel
Con esto, cada cambio se guarda en el estado del editor y, cuando se guarda la entrada, WordPress enviará la actualización al REST API y persistirá el meta.
Opción B — useSelect / useDispatch (select dispatch)
Alternativa para obtener el meta y actualizarlo explícitamente mediante la store de datos.
import { useSelect, useDispatch } from @wordpress/data
import { TextControl, PanelBody } from @wordpress/components
import { PluginDocumentSettingPanel } from @wordpress/edit-post
function MiMetaConDispatch() {
const meta = useSelect( ( select ) => {
return select( core/editor ).getEditedPostAttribute( meta )
}, [] )
const { editPost } = useDispatch( core/editor )
const valor = meta ? meta[mi_meta_clave] :
return (
editPost( { meta: { ...meta, mi_meta_clave: nuevo } } ) }
/>
)
}
export default MiMetaConDispatch
Este patrón usa la API de store core/editor. Es funcional y muy usado en ejemplos y en plugins antiguos, aunque useEntityProp es más cómodo para metadatos.
Opción C — Asignar meta a atributos de bloque (block.json)
Si creas un bloque que necesita leer/escribir meta vinculado al post, puedes mapear un atributo del bloque al meta usando la fuente meta. Esto permite que el bloque reciba el valor del meta como atributo y lo actualice automáticamente al guardar el bloque (útil para bloques que representan datos post-meta).
{
apiVersion: 2,
name: mi/mi-bloque-meta,
title: Bloque con Meta,
category: widgets,
icon: admin-post,
editorScript: file:./build/index.js,
attributes: {
miMeta: {
type: string,
source: meta,
meta: mi_meta_clave
}
}
}
En el código del bloque (editor.js), el atributo miMeta estará disponible en props.attributes y al editar el atributo Gutenberg sincronizará con el meta del post (siempre que el meta esté registrado con show_in_rest).
Paso 4 — Ejemplo completo: plugin pequeño que añade panel lateral
Aquí un esquema de archivos y ejemplos de código para crear un plugin sencillo:
- mi-plugin/
- mi-plugin.php (main)
- build/editor.js (compilado por bundler o un archivo simple si usas ES5)
mi-plugin.php:
true,
single => true,
type => string,
auth_callback => function() {
return current_user_can( edit_posts )
},
sanitize_callback => sanitize_text_field,
) )
} )
add_action( enqueue_block_editor_assets, function() {
wp_enqueue_script(
mi-plugin-editor,
plugins_url( build/editor.js, __FILE__ ),
array( wp-plugins, wp-edit-post, wp-element, wp-data, wp-components, wp-core-data ),
filemtime( plugin_dir_path( __FILE__ ) . build/editor.js )
)
} )
?>
Un ejemplo mínimo de build/editor.js (no olvides transpilar si usas JSX):
( function( wp ) {
const { registerPlugin } = wp.plugins
const { PluginDocumentSettingPanel } = wp.editPost
const { TextControl } = wp.components
const { useEntityProp } = wp.coreData
const { createElement, Fragment } = wp.element
function MiPanel() {
const [ meta, setMeta ] = useEntityProp( postType, post, meta )
const valor = meta meta[mi_meta_clave] ? meta[mi_meta_clave] :
return wp.element.createElement(
PluginDocumentSettingPanel,
{ name: mi-meta-panel, title: Mi Meta },
wp.element.createElement( TextControl, {
label: Mi meta,
value: valor,
onChange: ( nuevo ) => setMeta( { ...meta, mi_meta_clave: nuevo } )
} )
)
}
registerPlugin( mi-meta-plugin, { render: MiPanel } )
} )( window.wp )
Pruebas y comprobaciones
- Abrir el editor de una entrada: deberías ver el panel lateral con el campo.
- Al escribir y guardar, comprueba en la base de datos o con get_post_meta que el valor se ha persistido.
- Puedes usar la REST API /wp/v2/posts/ID y comprobar que en la respuesta hay la propiedad meta si tienes permisos.
Buenas prácticas y consejos
- Define correctamente sanitize_callback y auth_callback al registrar el meta para evitar inyecciones y accesos no autorizados.
- Usa type en register_post_meta (string, boolean, integer, object) para que la REST API valide el schema.
- Para valores complejos usa single => false o define un JSON en un solo campo (pero recuerda sanitizar/validar).
- Si el meta debe ser editable por bloques, considera mapearlo en block.json para que sea parte del estado del bloque.
- Si vas a compartir metadatos entre bloques y sidebar panels, usa useEntityProp para evitar duplicidad de lógica.
Errores comunes
- No registrar show_in_rest => true: el editor no podrá ver ni actualizar el meta.
- No definir auth_callback y confiar solo en la REST: puede permitir modificaciones indeseadas.
- Usar nombres de meta con caracteres extraños o sin prefijo: recomienda usar prefijos para evitar colisiones (ej. mi_plugin_mi_meta).
- No transpilar JSX/ESNext: asegúrate de compilar tu build/editor.js para compatibilidad con el editor.
Resumen
Trabajar con metadatos desde el editor de bloques implica dos pasos clave: exponer el meta en PHP con register_post_meta y usar las APIs de JavaScript de Gutenberg para leer y escribir esos valores. Las opciones principales son useEntityProp (muy recomendable), o usar select/dispatch con core/editor. Además, puedes mapear atributos de bloque a metadatos usando block.json para integrarlos directamente en bloques.
Recursos adicionales
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |