Saltar al contenido

Almacenamiento

De forma predeterminada, todos los valores de los campos se almacenan como atributos de bloque dentro del comentario del bloque en el contenido de la entrada. La función de almacenamiento también permite guardar valores en los metadatos de entradas (wp_postmeta) o en las opciones (wp_options), para que estén disponibles fuera del contexto del bloque.

¿Por qué usar el almacenamiento?

Los atributos de bloque se guardan dentro de comentarios HTML en el contenido de la entrada, lo que significa que solo están disponibles al analizar el contenido del bloque. Al usar ubicaciones de almacenamiento adicionales, puedes:

  • Consultar entradas por valores de campo usando meta_query
  • Acceder a los valores mediante REST API para configuraciones sin interfaz
  • Compartir datos con otros plugins, como SEO o plugins de caché
  • Crear ajustes globales que se conservan entre entradas

Tipos de almacenamiento

Tipo Ubicación Alcance Ideal para
postMeta Tabla wp_postmeta Por entrada Datos consultables específicos de una entrada
option Tabla wp_options Global (todo el sitio) Ajustes del sitio, valores compartidos

Nota

El almacenamiento de atributos de bloque (en el comentario HTML del contenido de la entrada) siempre se realiza automáticamente. La propiedad storage añade ubicaciones de almacenamiento adicionales; no sustituye el almacenamiento del bloque.

Configuración

Añade la propiedad storage a cualquier definición de campo:

JSON
{
  "name": "blockstudio/example",
  "title": "Example Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "subtitle",
        "type": "text",
        "label": "Subtitle",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "my_subtitle"
        }
      }
    ]
  }
}

Propiedades de almacenamiento

Propiedad Tipo Descripción
type string | string[] location(s) de almacenamiento adicional: "postMeta", "option"
postMetaKey string Clave de metadatos personalizada (predeterminada: {block_name}_{field_id})
optionKey string Clave de opción personalizada (predeterminada: {block_name}_{field_id})

Almacenamiento único o múltiple

JSON
// Add post meta storage
"storage": {
  "type": "postMeta"
}

// Add both post meta and option storage
"storage": {
  "type": ["postMeta", "option"]
}

Cómo funciona

  1. Registro: Cuando se carga WordPress, Blockstudio registra claves de metadatos y ajustes según la configuración de los campos
  2. Edición: Los valores se gestionan como atributos de bloque en el editor (siempre se almacenan en el bloque)
  3. Guardado: Los metadatos de la entrada se sincronizan al guardarla. Las opciones del sitio se sincronizan al publicar la entrada o cuando cambia el valor de un campo en una entrada publicada.

Los autoguardados y las revisiones tampoco sincronizan ninguna de las ubicaciones de almacenamiento. Las entradas en borrador, pendientes, privadas y programadas pueden actualizar sus propios metadatos, pero no modifican las opciones activas del sitio. Las opciones se sincronizan cuando WordPress publica una entrada programada.

Los valores se copian literalmente, incluidas las barras invertidas, las comillas y los valores de repetidores anidados. No añadas escapes a los valores de los campos para compensar el almacenamiento de metadatos WordPress; Blockstudio se encarga de ese límite. Las opciones del sitio conservan los mismos valores literales sin añadir barras.

Si una versión anterior eliminó las barras invertidas de la copia de metadatos de una entrada, vuelve a guardar la entrada después de actualizar. El valor original del campo en los atributos de bloque se usa para actualizar la copia de metadatos.

Guardar opciones del sitio

Las opciones se comparten en todo el sitio. Al publicar un bloque nuevo, se escriben los campos de opción incluidos en sus atributos guardados. En guardados posteriores, cada campo se compara con la versión guardada anterior de ese bloque y solo se escriben los valores que han cambiado. Guardar el título de una entrada o una copia antigua sin cambios del bloque en otra entrada no sobrescribe un valor de opción más reciente.

Si un campo no está en los atributos guardados, su opción queda intacta. Esto también protege las opciones existentes cuando se añade un campo nuevo a block.json. Un null explícito elimina una opción; las cadenas vacías, false, 0 y los arrays vacíos se guardan como valores. Eliminar un bloque no elimina sus opciones.

Use un bloque publicado designado para gestionar cada opción compartida. Si varios bloques cambian deliberadamente la misma opción, prevalece el último valor modificado que se guarde. El almacenamiento no carga la opción actual en cada bloque: cada bloque conserva sus propios valores de campo en el contenido de la entrada.

En las páginas basadas en archivos, un bloque persistente key permite a Blockstudio reconocer el mismo bloque después de moverlo dentro del documento. Los bloques sin clave se emparejan por nombre y posición.

Acceder a los valores almacenados

En plantillas de bloques

Dentro de la plantilla del bloque, los valores de campo están siempre disponibles mediante $attributes:

PHP

PHP
<div>
  <h1><?php echo $a['subtitle']; ?></h1>
</div>

Twig

Twig
<div>
  <h1>{{ a.subtitle }}</h1>
</div>

Metadatos de entrada (fuera del contexto del bloque)

Se puede acceder a los valores almacenados en postMeta desde cualquier lugar de WordPress:

PHP

PHP
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );

// Query posts by meta value
$posts = get_posts([
  'meta_key'   => 'my_subtitle',
  'meta_value' => 'Hello World',
]);

Twig

Twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}

{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}

Los metadatos de entrada también están disponibles mediante REST API:

Shell
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }

Opciones (valores globales)

Los valores almacenados en option están disponibles en todo el sitio:

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

Twig
{{ function('get_option', 'site_company_name') }}

Ejemplos

Campos de metadatos de SEO

Almacene datos de SEO en los metadatos de entrada para que sean compatibles con los plugins de SEO:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "seo_title",
        "type": "text",
        "label": "SEO Title",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_title"
        }
      },
      {
        "id": "seo_description",
        "type": "textarea",
        "label": "Meta Description",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_metadesc"
        }
      }
    ]
  }
}

Añada almacenamiento de metadatos de entrada para poder consultar entradas por el valor de un campo:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "featured",
        "type": "toggle",
        "label": "Featured",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "is_featured"
        }
      }
    ]
  }
}

Consultar entradas destacadas:

PHP
$featured_posts = get_posts([
  'meta_key'   => 'is_featured',
  'meta_value' => '1',
]);

Ajustes globales del sitio

Almacene la configuración de todo el sitio en las opciones:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "company_name",
        "type": "text",
        "label": "Company Name",
        "storage": {
          "type": "option",
          "optionKey": "site_company_name"
        }
      },
      {
        "id": "support_email",
        "type": "text",
        "label": "Support Email",
        "storage": {
          "type": "option",
          "optionKey": "site_support_email"
        }
      }
    ]
  }
}

Acceda a ellos desde cualquier lugar del sitio:

PHP
<footer>
  <p>&copy; <?php echo get_option( 'site_company_name' ); ?></p>
  <p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>

Metadatos de entrada y opciones

Para datos que necesitan estar disponibles tanto a nivel de entrada como de forma global:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "important_value",
        "type": "text",
        "label": "Important Value",
        "storage": {
          "type": ["postMeta", "option"],
          "postMetaKey": "important_meta",
          "optionKey": "important_option"
        }
      }
    ]
  }
}

Nombres de clave predeterminados

Si no especifica una clave personalizada, Blockstudio genera una automáticamente:

Tipo de almacenamiento Formato de clave predeterminado Ejemplo
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

El nombre del bloque se sanitiza (las barras se reemplazan por guiones bajos).

Advertencia

Se recomienda usar claves personalizadas en producción. Las claves predeterminadas pueden cambiar si cambia el nombre del bloque.