Към съдържанието

Страници и шаблони

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) и файл с шаблон.

Шаблонизиращи енджини

Шаблоните могат да бъдат обикновен markup в 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 директно към атрибута за richtext content на регистриран блок 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>