Сторінки та шаблони
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 безпосередньо до атрибута content richtext зареєстрованого нетипового блоку Blockstudio. Цільовий блок має оголошувати атрибут із 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>