Перейти до вмісту

Сторінки та шаблони

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>:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

Основні блоки

HTML
<!-- 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>

Користувацькі блоки

Той самий синтаксис працює з будь-яким зареєстрованим блоком:

HTML
<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:

HTML
<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="[&amp;>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:

PHP
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 );

Потім використовуйте його в будь-якому шаблоні:

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

Також можна перевизначити спосіб рендерингу основних блоків:

PHP
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. Повний порядок фільтрів і приклад контейнера наведено в розділі Власні рендерери.

Сигнатура функції побудовника

PHP
/**
 * @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:

PHP
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 і далі розбираються як внутрішні блоки.

Значення зіставлення також можуть бути функціями зворотного виклику, якщо цільовий блок залежить від атрибутів елемента:

PHP
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, тож внутрішні заголовки, зображення, теги блоків і абзаци стають нативними дочірніми блоками.

Повний приклад

Повний шаблон сторінки, що поєднує кілька типів блоків:

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>