Aller au contenu

Stockage

Par défaut, toutes les valeurs des champs sont stockées comme attributs de bloc dans le commentaire de bloc du contenu de l’article. La fonctionnalité de stockage permet également de stocker les valeurs dans les métadonnées des articles (wp_postmeta) ou dans les options (wp_options), afin qu’elles soient accessibles en dehors du contexte du bloc.

Pourquoi utiliser le stockage ?

Les attributs de bloc sont stockés dans les commentaires HTML du contenu de l’article ; ils ne sont donc accessibles qu’en analysant le contenu des blocs. En utilisant d’autres emplacements de stockage, vous pouvez :

  • Rechercher des articles par valeur de champ avec meta_query
  • Accéder aux valeurs via REST API pour les configurations headless
  • Partager des données avec d’autres plugins, comme SEO ou des plugins de cache
  • Créer des réglages globaux qui persistent d’un article à l’autre

Types de stockage

Type Emplacement Portée Idéal pour
postMeta Table wp_postmeta Par article Données d’article pouvant être interrogées
option Table wp_options Globale (à l’échelle du site) Réglages du site, valeurs partagées

Remarque

Le stockage des attributs de bloc (dans le commentaire HTML du contenu de l’article) s’effectue toujours automatiquement. La propriété storage ajoute des emplacements de stockage supplémentaires ; elle ne remplace pas le stockage des blocs.

Configuration

Ajoutez la propriété storage à la définition de n’importe quel champ :

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

Propriétés de stockage

Propriété Type Description
type string | string[] Emplacements de stockage location(s) supplémentaires : "postMeta", "option"
postMetaKey string Clé de métadonnée personnalisée (par défaut : {block_name}_{field_id})
optionKey string Clé d’option personnalisée (par défaut : {block_name}_{field_id})

Stockage unique ou multiple

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

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

Fonctionnement

  1. Enregistrement : au chargement de WordPress, Blockstudio enregistre les clés de métadonnées et les réglages selon la configuration de vos champs
  2. Modification : les valeurs sont gérées comme attributs de bloc dans l’éditeur (elles sont toujours stockées dans le bloc)
  3. Enregistrement : les métadonnées de l’article sont synchronisées lorsque l’article est enregistré. Les options du site sont synchronisées lorsque l’article est publié ou que la valeur d’un champ d’un article publié est modifiée.

Les sauvegardes automatiques et les révisions ne synchronisent aucun des deux emplacements de stockage. Les articles à l’état de brouillon, en attente, privés ou planifiés peuvent mettre à jour leurs propres métadonnées, mais ne modifient pas les options actives du site. Les options sont synchronisées lorsqu’un article planifié est publié par WordPress.

Les valeurs sont copiées littéralement, y compris les barres obliques inverses, les guillemets et les valeurs imbriquées des répéteurs. N’ajoutez pas d’échappement aux valeurs des champs pour compenser le stockage des métadonnées WordPress ; Blockstudio gère cette étape. Les options du site conservent les mêmes valeurs littérales sans ajout de barres obliques.

Si une version antérieure a supprimé les barres obliques inverses de la copie des métadonnées d’un article, enregistrez à nouveau l’article après la mise à niveau. La valeur d’origine du champ dans les attributs de bloc est utilisée pour actualiser la copie des métadonnées.

Enregistrement des options du site

Les options sont partagées sur l’ensemble du site. La publication d’un nouveau bloc écrit les champs d’option fournis dans ses attributs enregistrés. Lors des enregistrements ultérieurs, chaque champ est comparé à la version précédente enregistrée de ce bloc et seules les valeurs modifiées sont écrites. L’enregistrement du titre d’un article, ou d’une ancienne copie inchangée du bloc sur un autre article, ne remplace pas une valeur d’option plus récente.

Un champ absent des attributs enregistrés laisse son option intacte. Cela protège également les options existantes lorsqu’un nouveau champ est ajouté à block.json. Une valeur explicite null supprime une option ; les chaînes vides, false, 0 et les tableaux vides sont enregistrés comme valeurs. La suppression d’un bloc ne supprime pas ses options.

Utilisez un bloc publié désigné pour gérer chaque option partagée. Si plusieurs blocs modifient volontairement la même option, la dernière valeur modifiée enregistrée l’emporte. Le stockage ne charge pas l’option actuelle dans chaque bloc : chaque bloc conserve ses propres valeurs de champ dans le contenu de l’article.

Pour les pages basées sur des fichiers, une clé de bloc persistante key permet à Blockstudio de reconnaître le même bloc après son déplacement dans le document. Les blocs sans clé sont associés selon leur nom et leur position.

Accéder aux valeurs stockées

Dans les modèles de blocs

Dans le modèle de votre bloc, les valeurs des champs sont toujours accessibles via $attributes :

PHP

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

Twig

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

Métadonnées d’article (hors contexte de bloc)

Les valeurs stockées dans postMeta sont accessibles partout dans 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) }}

Les métadonnées d’article sont également accessibles via REST API :

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

Options (valeurs globales)

Les valeurs stockées dans option sont accessibles sur l’ensemble du site :

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

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

Exemples

Champs de métadonnées SEO

Stockez les données SEO dans les métadonnées d’article pour assurer la compatibilité avec les extensions 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"
        }
      }
    ]
  }
}

Ajoutez le stockage des métadonnées d’article pour permettre de rechercher des articles par valeur de champ :

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

Recherchez les articles mis en avant :

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

Réglages globaux du site

Stockez la configuration à l’échelle du site dans les options :

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

Accédez-y partout sur votre site :

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

Métadonnées d’article et option

Pour les données qui doivent être accessibles à la fois au niveau de l’article et de façon globale :

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

Noms de clés par défaut

Si vous ne spécifiez pas de clé personnalisée, Blockstudio en génère une automatiquement :

Type de stockage Format de clé par défaut Exemple
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

Le nom du bloc est assaini (les barres obliques sont remplacées par des traits de soulignement).

Avertissement

Il est recommandé d’utiliser des clés personnalisées en production. Les clés par défaut peuvent changer si vous renommez votre bloc.