Страницы и шаблоны
Blockstudio позволяет задавать страницы WordPress, шаблоны блоков и шаблоны редактора сайта в виде файлов темы. Пишите шаблоны в стиле HTML, а парсер Blockstudio преобразует их в нативные блоки WordPress.
- Страницы синхронизируются с базой данных как записи WordPress, благодаря чему файловые шаблоны остаются согласованными с содержимым страниц.
- Шаблоны регистрируются в памяти через
register_block_pattern()и доступны в окне вставки блоков, откуда пользователи могут размещать их где угодно. - Шаблоны сайта предоставляют файловые источники
wp_templateиwp_template_partдля редактора сайта WordPress.
Все три возможности используют один и тот же парсер HTML и синтаксис блоков.
Создание страниц на основе файлов
Практическое руководство по файловым шаблонам страниц, синхронизации и блокировке.
Структура папок
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
В каждой подпапке находится файл конфигурации JSON (page.json, pattern.json, template.json или part.json) и файл шаблона.
Шаблонизаторы
Шаблоны можно писать как обычную разметку в index.php, а также в Twig или Blade:
| Файл | Движок | Требование |
|---|---|---|
index.php |
Нет (читается без изменений, код PHP не выполняется) | Нет |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Если доступно несколько файлов шаблонов, применяется такой порядок приоритета: index.php > index.blade.php > index.twig.
Поскольку шаблоны компилируются при инициализации (до появления контекста запроса), шаблоны Twig и Blade не имеют доступа к динамическим переменным. Они подходят для встроенных функций и фильтров, таких как {{ "text"|upper }} или {{ strtoupper("text") }}.
Сопоставление HTML с блоками
Стандартные элементы HTML автоматически преобразуются в соответствующие блоки WordPress.
Текст
| HTML | Блок |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (маркированный) |
<ol> |
core/list (нумерованный) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Списки сохраняют структуру. Элемент <ul> или <ol> внутри <li> становится
внутренним блоком core/list этого core/list-item — именно такую структуру сохраняет редактор,
поэтому списки могут иметь любую глубину вложенности. class для списка или его элемента становится его
className — так, например, для страницы задаётся стиль блока вроде is-style-checks; то же самое делает <block name="core/list" className="...">.
Медиафайлы
| HTML | Блок |
|---|---|
<img> |
core/image |
<figure> |
core/image (с подписью) |
<audio> |
core/audio |
<video> |
core/video |
Макет
| HTML | Блок |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group, сохраняющий элемент как собственный tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Синтаксис блоков
Для блоков, у которых нет прямого эквивалента HTML, используйте элемент <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Основные блоки
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Пользовательские блоки
Для любого зарегистрированного блока подходит тот же синтаксис:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Атрибуты
Атрибуты HTML у элементов <block> передаются как атрибуты блока. Поддерживаются значения JSON:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
Значения атрибутов декодируются один раз так же, как браузер считывает их, поэтому
data-animate="[&>span]:fade" и data-animate="[&>span]:fade" сохраняют
одно и то же значение.
У элемента, сопоставленного блоку Blockstudio, все атрибуты сохраняются вместе
с блоком. Объявленные поля доступны шаблону; глобальные атрибуты, которые блок
не объявляет (id, style, role, title, lang, dir, hidden,
tabindex, aria-* и data-*), выводятся на корневом элементе блока при его
рендеринге — так же, как у тегов блоков таких. В исходниках
страниц и шаблонов префикс html- может обозначать только один из этих глобальных
атрибутов: например, html-role="note" передаётся как role, а обработчики событий,
такие как html-onclick, никогда не выводятся. Всё остальное, включая необъявленный
class, остаётся в содержимом записи и не попадает на страницу; wp bs pages sync сообщает
о нём для каждой разобранной страницы.
Обработчики пользовательских блоков
Парсер HTML построен на архитектуре с реестром. Добавьте построитель для пользовательского
блока с помощью blockstudio/block_tags/builders:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Затем используйте его в любом шаблоне:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Также можно переопределить способ отображения основных блоков:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Функции обратного вызова построителя получают разобранные атрибуты и исходное внутреннее содержимое. Они должны возвращать массив блоков WordPress. Полный порядок фильтров и пример контейнера см. в разделе Пользовательские обработчики.
Сигнатура функции построителя
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Сопоставление элементов
По умолчанию стандартные элементы HTML, такие как <h1>, <p> и <img>, сопоставляются с основными блоками WordPress. Это сопоставление можно переопределить и направить любой элемент HTML в другой блок с помощью фильтра blockstudio/parser/element_mapping:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
При включённом фильтре каждый <h1> в ваших шаблонах будет создавать блок custom/heading вместо core/heading. Атрибуты элемента передаются целевому блоку. Если для его имени зарегистрирован обработчик, будет использоваться он. Иначе создаётся общая структура блока.
Это полезно, когда тема или плагин предоставляет пользовательские типы блоков, которые должны заменять стандартные во всех шаблонах страниц и блоков.
Для простых сопоставлений <p> Blockstudio может напрямую передавать внутреннее содержимое HTML зарегистрированному пользовательскому блоку Blockstudio в атрибут форматированного текста content. В целевом блоке должен быть объявлен атрибут с id: "content" и type: "richtext".
Встроенное форматирование (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) сохраняется в передаваемом значении, даже если тот же тег по умолчанию сопоставлен с элементом, как code и img. Абзац, единственный дочерний элемент которого — изображение, становится блоком, с которым сопоставляется <img>, что и создаёт Markdown для отдельного изображения. Вложенные блочные теги и блочное HTML по-прежнему разбираются как внутренние блоки.
Значения сопоставления также могут быть вызываемыми объектами, если целевой блок зависит от атрибутов элемента:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
Пользовательские блоки, сопоставленные контейнерным элементам, таким как <section> и <div>,
рекурсивно разбирают вложенные дочерние элементы HTML, поэтому внутренние заголовки, изображения, теги блоков
и абзацы становятся нативными дочерними блоками.
Полный пример
Полный шаблон страницы, объединяющий несколько типов блоков:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>