Vai al contenuto

Archiviazione

Per impostazione predefinita, tutti i valori dei campi vengono memorizzati come attributi del blocco nel commento del blocco all’interno del contenuto del post. La funzionalità di archiviazione consente di memorizzare i valori anche nei meta dei post (wp_postmeta) o nelle opzioni (wp_options), rendendoli accessibili al di fuori del contesto del blocco.

Perché usare l’archiviazione?

Gli attributi del blocco vengono memorizzati nei commenti HTML nel contenuto del post; sono quindi accessibili solo analizzando il contenuto del blocco. Usando altre posizioni di archiviazione, potete:

  • Interrogare i post in base ai valori dei campi usando meta_query
  • Accedere ai valori tramite REST API per configurazioni headless
  • Condividere dati con altri plugin, come SEO o plugin di caching
  • Creare impostazioni globali persistenti tra un post e l’altro

Tipi di archiviazione

Tipo Posizione Ambito Ideale per
postMeta tabella wp_postmeta Per post Dati specifici del post interrogabili
option tabella wp_options Globale (intero sito) Impostazioni del sito, valori condivisi

Nota

L’archiviazione degli attributi del blocco (nel commento HTML del contenuto del post) avviene sempre automaticamente. La proprietà storage aggiunge posizioni di archiviazione aggiuntive: non sostituisce l’archiviazione del blocco.

Configurazione

Aggiungete la proprietà storage a qualsiasi definizione di campo:

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

Proprietà di archiviazione

Proprietà Tipo Descrizione
type string | string[] Posizione di archiviazione location(s) aggiuntiva: "postMeta", "option"
postMetaKey string Chiave meta personalizzata (predefinita: {block_name}_{field_id})
optionKey string Chiave opzione personalizzata (predefinita: {block_name}_{field_id})

Archiviazione singola o multipla

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

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

Come funziona

  1. Registrazione: al caricamento di WordPress, Blockstudio registra le chiavi meta e le impostazioni in base alla configurazione dei campi
  2. Modifica: i valori sono gestiti come attributi del blocco nell’editor (vengono sempre memorizzati nel blocco)
  3. Salvataggio: i meta dei post vengono sincronizzati quando il post viene salvato. Le opzioni del sito vengono sincronizzate quando il post viene pubblicato o quando cambia il valore di un campo di un post pubblicato.

I salvataggi automatici e le revisioni non sincronizzano nessuna delle due posizioni di archiviazione. Le modifiche alle bozze e ai post in attesa, privati o programmati possono aggiornare i rispettivi meta, ma non modificano le opzioni attive del sito. Le opzioni vengono sincronizzate quando WordPress pubblica il post programmato.

I valori vengono copiati alla lettera, comprese barre rovesciate, virgolette e valori annidati dei repeater. Non aggiungete caratteri di escape ai valori dei campi per compensare l’archiviazione dei metadati WordPress; se ne occupa Blockstudio. Le opzioni del sito mantengono gli stessi valori letterali senza ulteriori caratteri di escape.

Se una versione precedente ha rimosso le barre rovesciate dalla copia dei metadati di un articolo, salvatelo di nuovo dopo l’aggiornamento. Il valore originale del campo negli attributi del blocco viene usato per aggiornare la copia dei metadati.

Salvataggio delle opzioni del sito

Le opzioni sono condivise in tutto il sito. Quando pubblicate un nuovo blocco, vengono scritti i campi opzione forniti nei suoi attributi salvati. I salvataggi successivi confrontano ciascun campo con la versione salvata precedente del blocco e scrivono solo i valori modificati. Salvare il titolo di un post o una copia meno recente e invariata del blocco presente in un altro post non sovrascrive un valore opzione più recente.

Un campo omesso dagli attributi salvati lascia invariata la relativa opzione. Questo protegge anche le opzioni esistenti quando viene aggiunto un nuovo campo a block.json. Un null esplicito elimina un’opzione; le stringhe vuote, false, 0 e gli array vuoti vengono salvati come valori. Rimuovere un blocco non elimina le sue opzioni.

Usate un blocco pubblicato designato per gestire ogni opzione condivisa. Se più blocchi modificano intenzionalmente la stessa opzione, prevale l’ultimo valore modificato e salvato. L’archiviazione non carica l’opzione corrente in ogni blocco: ciascun blocco conserva i propri valori dei campi nel contenuto dell’articolo.

Per le pagine basate su file, una chiave persistente del blocco key consente a Blockstudio di riconoscere lo stesso blocco dopo che è stato spostato nel documento. I blocchi senza chiave vengono abbinati in base al nome e alla posizione.

Accesso ai valori archiviati

Nei template dei blocchi

All’interno del template del blocco, i valori dei campi sono sempre disponibili tramite $attributes:

PHP

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

Twig

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

Metadati dell’articolo (fuori dal contesto del blocco)

È possibile accedere ovunque in WordPress ai valori archiviati in postMeta:

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) }}

I metadati dell’articolo sono disponibili anche tramite REST API:

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

Opzioni (valori globali)

I valori archiviati in option sono accessibili in tutto il sito:

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

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

Esempi

Campi meta SEO

Salvate i dati SEO nei metadati dell’articolo per garantire la compatibilità con i plugin 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"
        }
      }
    ]
  }
}

Aggiungete l’archiviazione nei metadati dell’articolo per consentire di interrogare gli articoli in base al valore di un campo:

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

Interrogate gli articoli in evidenza:

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

Impostazioni globali del sito

Salvate la configurazione globale del sito nelle opzioni:

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"
        }
      }
    ]
  }
}

Accedete ai valori da qualsiasi punto del sito:

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

Metadati dell’articolo e opzione

Per i dati che devono essere accessibili sia a livello di articolo sia a livello globale:

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

Nomi delle chiavi predefinite

Se non specificate una chiave personalizzata, Blockstudio ne genera una automaticamente:

Tipo di archiviazione Formato della chiave predefinita Esempio
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

Il nome del blocco viene normalizzato (le barre vengono sostituite con trattini bassi).

Avviso

Per l’uso in produzione si consigliano chiavi personalizzate. Le chiavi predefinite potrebbero cambiare se rinominate il blocco.