Overrides в Synced Patterns

В WordPress 6.6 появились overrides (переопределения) в синхронизированных паттернах (Synced Patterns). Они позволяют вносить изменения контента, не меняя при этом разметку или дизайн паттерна.

В этом посте разберем, что такое Переопределения в синхронизированных паттернах, как они работают.

Оглавление:

Итак, что такое overrides?
Synced Patterns
Редактирование только контента
Включение
Block Bindings API
Собираем все вместе
Ограничения
Заключение

Итак, что такое overrides?

На изображении показан относительно простой дизайн карточки, но обратите внимание на тулбар блока и инспектор справа.

Вид редактора, показывающий синхронизированный паттерн карточки с overrides.

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

Хотя по изображению это не очевидно, обе карточки работают на одном и том же синхронизированном (synced) паттерне. Каждый редактируемый фрагмент контента внутри паттерна - это override.

Synced Patterns

Synced Patterns (раньше, до WP 6.3, назывались reusable blocks) создаются в редакторе - их код (дизайн) сохраняется в базе данных, и паттер переиспользуются на страницах, все изменения храняться в одном месте (синхронизированными).

Например, если у вас есть Synced Patterns на нескольких страницах, его обновление изменит его на каждой странице, где он используется.

Короткое видео о том, как создавать Synced Patterns:

https://videopress.com/embed/cJ2MyDB2?cover=1&autoPlay=0&controls=1&loop=1&muted=0&persistVolume=1&playsinline=0&preloadContent=metadata&useAverageColor=1&hd=0

Хотя у Synced Patterns много применений, часто хочется зафиксировать разметку и дизайн паттерна, но оставить контент редактируемым.

На примере карточки, скорее всего нужно, чтобы пользователи могли редактировать содержимое блоков: Heading, Paragraph и Button.

Но перед этим разберем второе требование для overrides - редактирование только контента.

Редактирование только контента

Появившееся в WordPress 6.1, редактирование только контента использует механизм блокировки contentOnly, чтобы разрешить редактировать только вложенный текст и медиа внутри блока или паттерна, сохраняя при этом общую структуру разметки и дизайна.

Эта функция, поддерживаемая блоками вроде "Columns", "Cover" и "Group", скрывает блоки без текстового или медиа-контента из "List View" и отключает контролы инспектора для настроек и стилей.

Включение

Чтобы включить редактирование только контента для блока, установите атрибут templateLock = contentOnly. В редакторе для этого нет UI, поэтому атрибут нужно добавлять вручную в разметку блока. Обычно это делают в файлах паттернов и шаблонов, но можно протестировать и через Code Editor. Попробуйте на демо WordPress Playground:

https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wptrainingteam/developer-blog-playground-demos/main/synced-pattern-overrides/blueprint.json

До и после:

Обратите внимание: все настройки в инспекторе блока исчезли. Пользователь теперь может редактировать только контент блоков Heading, Paragraph и Button.

Block Bindings API

Overrides появился только в WordPress 6.6, потому что до этого не хватало возможности "привязать" пользовательские изменения к паттерну. Это стало возможным благодаря Block Bindings API.

Block Bindings API позволяет разработчикам связывать атрибуты блоков с разными источниками данных:

кастомные поля (метаданные записи)
данные сайта
данные пользователя
и т.д.

Чтобы реализовать overrides, не обязательно глубоко знать Block Bindings API, но он помогает понять связь и текущие ограничения.

Посмотрим простой пример.

Предположим, вы хотите привязать метаполя поста к блокам Heading, Paragraph и Button, чтобы вместо их контанта в контенте блока, он хранился храниться в метаданных записи и отображаться в каждом блоке.

Сначала через register_meta() зарегистрируйте метаполя для каждого атрибута блока, назовем их: card_heading, card_description, card_button_text, card_button_url:

add_action( 'init', 'theme_slug_register_meta' );
function theme_slug_register_meta() {
	register_meta( 'post', 'card_heading', [
		'show_in_rest'      => true,
		'single'            => true,
		'type'              => 'string',
		'sanitize_callback' => 'wp_strip_all_tags',
		'default'           => 'Card heading',
	] );

	register_meta( 'post', 'card_description', [
		'show_in_rest'      => true,
		'single'            => true,
		'type'              => 'string',
		'sanitize_callback' => 'wp_strip_all_tags',
		'default'           => 'Card description. Lorem ipsum dolor sit amet.',
	] );

	register_meta( 'post', 'card_button_text', [
		'show_in_rest'      => true,
		'single'            => true,
		'type'              => 'string',
		'sanitize_callback' => 'wp_strip_all_tags',
		'default'           => 'Learn more',
	] );

	register_meta( 'post', 'card_button_url', [
		'show_in_rest'      => true,
		'single'            => true,
		'type'              => 'string',
		'sanitize_callback' => 'esc_url_raw',
		'default'           => 'https://wordpress.org',
	] );
}

Этот код регистрирует метаполя и делает их доступными в REST API, чтобы их можно было привязать к атрибутам блоков. Важный параметр: show_in_rest = true.

Далее, привяжите метаданные к блокам через атрибут metadata. Например, для Heading это выглядит так:

"metadata": {
  "bindings": {
	"content": {
	  "source": "core/post-meta",
	  "args": {
		"key": "card_heading"
	  }
	}
  }
}

Кратко по свойствам:

metadata: объект с метаданными блока
bindings: объект с одной или несколькими привязками
content: атрибут блока, который привязывается к источнику (зависит от блока)
source: источник данных (для метаполей это core/post-meta)
args: аргументы для источника (для метаполя укажите key как зарегистрированный meta key)

Пока в редакторе нет UI для применения bindings к блокам, поэтому это нужно делать вручную в разметке блока. Переключитесь в Code Editor и добавьте этот атрибут к Heading. Полная разметка будет такой:

<!-- wp:heading {"metadata":{"bindings":{"content":{"source":"core/post-meta","args":{"key":"card_heading"}}}}} -->
<h2 class="wp-block-heading">Card heading</h2>
<!-- /wp:heading -->

Обратите внимание: привязка нацелена на content - это атрибут content у Heading. Повторите это для Paragraph и Button.

Поддерживаемые блоки и атрибуты Block Bindings API (на момент WordPress 6.6):

Поддерживаемые блоки	Поддерживаемые атрибуты
Image	`url`, `alt`, `title`
Heading	`content`
Paragraph	`content`
Button	`url`, `text`, `linkTarget`, `rel`

Поскольку overrides в паттернах по сути являются bindings, список блоков для overrides совпадает со списком блоков для bindings. По мере добавления совместимости в новые блоки, они, вероятно, тоже станут "переопределяемыми".

Скриншот ниже показывает дизайн карточки, где каждый блок привязан к зарегистрированным кастомным полям. Визуально все похоже из-за дефолтного контента, но обратите внимание на новое значение card_heading и панель Bindings в инспекторе блока.

Подробнее про Block Bindings API:

Собираем все вместе

Теперь, когда мы разобрали Synced Patterns, редактирование только контента и bindings, пора создать несколько overrides.

Снова посмотрим на дизайн карточки:

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

Шаг 1 - превратите дизайн в synced pattern. Выберите внешний Stack блок и в меню опций в тулбаре блока выберите Create pattern.

В модалке задайте имя паттерна и убедитесь, что включен переключатель Synced.

Теперь в тулбаре появится фиолетовая иконка, а обводка блока станет фиолетовой вместо синей. Это означает, что контент синхронизирован. Обратите внимание, что вы больше не можете напрямую редактировать контент блоков.

Выберите Edit original в тулбаре блока, чтобы редактировать оригинал синхронизированного паттерна. Это откроет паттерн в отдельном экране.

Дальше нужно добавить overrides к блокам Heading, Paragraph и Button. Поскольку все три блока поддерживают bindings, они также поддерживают overrides.

Начните с Heading, откройте панель Advanced в инспекторе блока. Там будет кнопка Enable overrides.

Нажмите Enable overrides - откроется модалка.

Она попросит ввести уникальное имя override. Это нужно, чтобы WordPress мог сопоставить пользовательский контент с правильным блоком внутри паттерна.

Выберите любое имя. На изображении ниже используется "Card heading".

Повторите процесс для Paragraph и Button. Ваш паттерн будет похож на этот: обратите внимание на именованные блоки в List View и список overrides справа в инспекторе паттерна.

Финальный synced pattern со всеми overrides.

Перед тем как продолжить, переключитесь в Code Editor и посмотрите разметку. Вы увидите source для bindings у каждого блока, установленный в core/pattern-overrides. Это Block Bindings API в действии.

Пример разметки Paragraph:

<!-- wp:paragraph {
	"metadata":{
		"bindings":{
			"__default":{"source":"core/pattern-overrides"}
		},
		"name":"Card Description"},
		"fontSize":"small"
	}
-->
<p class="has-small-font-size">Card description. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
<!-- /wp:paragraph -->

Сохраните паттерн и вернитесь к записи, где размещен паттерн карточки. Он будет в первой колонке блока Columns. Вставьте тот же паттерн во вторую колонку и измените заголовки, чтобы увидеть работу overrides.

Далее измените сам synced pattern, чтобы увидеть, как он обновляет каждый экземпляр, сохраняя при этом ваши контентные изменения. Попробуйте добавить дополнительные overrides, например, изображение сверху карточки.

Видео:

https://videopress.com/embed/hhD0510P?cover=1&autoPlay=0&controls=1&loop=1&muted=0&persistVolume=1&playsinline=0&preloadContent=metadata&useAverageColor=1&hd=0

Ограничения

Overrides для Synced Patterns появятся в WordPress 6.6. При этом есть ограничения:

Число поддерживаемых блоков и атрибутов ограничено, и сейчас нет механизма opt-in для кастомных блоков.
Synced Patterns хранятся только в базе данных и не могут быть упакованы как pattern-файлы в вашей теме.

В будущих релизах будут поддерживаться дополнительные Core блоки и атрибуты.

Обсуждение opt-in механизма для кастомных блоков: https://github.com/WordPress/gutenberg/issues/59607

Заключение

Несмотря на ограничения, уже сейчас можно сделать многое. Стоит начать изучать overrides в WordPress 6.6, потому что они фундаментально меняют то, как многие владельцы сайтов будут управлять контентом в WordPress.

Дополнительно по теме:

Developer Hours от 11 июня 2024, запись доступна на WordPress.tv:

https://wordpress.tv/2024/06/11/developer-hours-exploring-synced-pattern-overrides-in-wordpress-6-6/