Перейти к содержимому

Хранение

По умолчанию все значения полей хранятся как атрибуты блока внутри комментария блока в содержимом записи. Функция хранения позволяет дополнительно сохранять значения в метаданных записи (wp_postmeta) или параметрах (wp_options), чтобы они были доступны вне контекста блока.

Зачем использовать хранение?

Атрибуты блока хранятся внутри комментариев HTML в содержимом записи, поэтому доступ к ним возможен только при разборе содержимого блока. Используя дополнительные места хранения, вы можете:

  • Фильтровать записи по значениям полей с помощью meta_query
  • Получать доступ к значениям через REST API в безголовых конфигурациях
  • Обмениваться данными с другими плагинами, например 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 и пустые массивы сохраняются как значения. Удаление блока не удаляет его параметры.

Назначьте один опубликованный блок для управления каждым общим параметром. Если несколько блоков намеренно изменяют один и тот же параметр, сохраняется последнее измененное значение. Хранилище не загружает текущее значение параметра в каждый блок: каждый блок хранит собственные значения полей в содержимом записи.

Для страниц, основанных на файлах, постоянный блок 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) }}

Метаданные записи также доступны через REST API:

Командная оболочка
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

Имя блока очищается от недопустимых символов (косые черты заменяются символами подчеркивания).

Предупреждение

Для использования в рабочей среде рекомендуется задавать собственные ключи. Ключи по умолчанию могут измениться при переименовании блока.