コンテンツへスキップ

ストレージ

既定では、すべてのフィールド値は投稿コンテンツ内のブロックコメントにブロック属性として保存されます。ストレージ機能を使うと、値を投稿メタ(wp_postmeta)またはオプション(wp_options)にも保存でき、ブロックのコンテキスト外からアクセスできます。

ストレージを使う理由

ブロック属性は投稿コンテンツ内のHTMLコメントに保存されるため、ブロックコンテンツを解析するときにしかアクセスできません。保存先を追加すると、次のことができます。

  • meta_queryを使ってフィールド値で投稿をクエリする
  • ヘッドレス環境でRESTAPI経由で値にアクセスする
  • SEOやキャッシュプラグインなど、他のプラグインとデータを共有する
  • 投稿をまたいで保持されるグローバル設定を作成する

ストレージの種類

種類 保存場所 範囲 適した用途
postMeta wp_postmetaテーブル 投稿ごと クエリ可能な投稿固有データ
option wp_optionsテーブル グローバル(サイト全体) サイト設定、共有値

注

ブロック属性の保存(投稿コンテンツ内のHTMLコメント)は常に自動で行われます。storageプロパティは保存先を追加するものであり、ブロック保存を置き換えるものではありません。

設定

任意のフィールド定義にstorageプロパティを追加します。

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

ストレージのプロパティ

プロパティ 型 説明
type string | string[] 追加のストレージlocation(s): "postMeta"、"option"
postMetaKey string カスタムメタキー(既定値: {block_name}_{field_id})
optionKey string カスタムオプションキー(既定値: {block_name}_{field_id})

単一ストレージと複数ストレージ

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

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

動作の仕組み

  1. 登録: WordPressの読み込み時に、Blockstudioがフィールド設定に基づいてメタキーと設定を登録します
  2. 編集: 値はエディター内でブロック属性として管理されます(常にブロックに保存されます)
  3. 保存: 投稿の保存時に投稿メタが同期されます。サイトオプションは、投稿の公開時または公開済み投稿のフィールド値が変更されたときに同期されます

自動保存とリビジョンでは、どちらの保存先も同期されません。下書き、保留中、非公開、予約済みの投稿では独自の投稿メタを更新できますが、公開中のサイトオプションは変更されません。予約投稿では、WordPressによる公開時にオプションが同期されます。

値はバックスラッシュ、引用符、ネストされたリピーター値を含め、そのままコピーされます。WordPressのメタデータ保存に合わせてフィールド値をエスケープしないでください。この境界はBlockstudioが処理します。サイトオプションも、追加のスラッシュ処理なしで同じリテラル値を保持します。

以前のバージョンで投稿のメタデータコピーからバックスラッシュが削除されていた場合は、アップグレード後に投稿を再保存してください。ブロック属性にある元のフィールド値を使って、メタデータコピーが更新されます。

サイトオプションの保存

オプションはサイト全体で共有されます。新しいブロックを公開すると、保存済みの属性に含まれるオプションフィールドが書き込まれます。その後の保存では、各フィールドをそのブロックの前回保存時の内容と比較し、変更された値だけを書き込みます。投稿タイトルの保存や、別の投稿にある同じブロックの古いコピーを変更せずに保存しても、新しいオプション値が上書きされることはありません。

保存済み属性に含まれないフィールドのオプションは変更されません。新しいフィールドをblock.jsonに追加したときも、既存のオプションは保護されます。明示的なnullはオプションを削除します。空文字列、false、0、空の配列は値として保存されます。ブロックを削除しても、そのオプションは削除されません。

共有オプションごとに、管理用の公開済みブロックを1つ指定してください。複数のブロックが意図的に同じオプションを変更する場合、最後に保存された変更値が優先されます。ストレージは現在のオプションを各ブロックに読み込みません。各ブロックは投稿コンテンツ内の独自のフィールド値を保持します。

ファイルベースのページでは、永続的なブロックkeyを使うと、ドキュメント内でブロックを移動した後もBlockstudioが同じブロックとして認識できます。キーのないブロックは、ブロック名と位置で照合されます。

保存した値へのアクセス

ブロックテンプレート内

ブロックテンプレート内では、フィールド値は常に$attributesから利用できます。

PHP

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

Twig

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

投稿メタ(ブロックコンテキスト外)

postMetaに保存された値は、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) }}

投稿メタはRESTAPIからも利用できます。

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

オプション(グローバル値)

optionに保存された値は、サイト全体からアクセスできます。

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

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

例

SEOメタフィールド

SEOプラグインとの互換性のため、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"
        }
      }
    ]
  }
}

フィールド値で投稿をクエリできるよう、投稿メタへの保存を追加します。

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

おすすめ投稿をクエリします。

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

グローバルサイト設定

サイト全体の設定をオプションに保存します。

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

サイト内のどこからでもアクセスできます。

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

投稿メタとオプション

投稿単位とグローバルの両方からアクセスする必要があるデータに使います。

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

既定のキー名

カスタムキーを指定しない場合、Blockstudioが自動的にキーを生成します。

ストレージの種類 既定のキー形式 例
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

ブロック名はサニタイズされます(スラッシュはアンダースコアに置き換えられます)。

警告

本番環境ではカスタムキーの使用をおすすめします。ブロック名を変更すると、既定のキーも変わる可能性があります。