Przejdź do treści

Strony i wzorce

Blockstudio pozwala definiować strony WordPress, wzorce bloków i szablony Edytora witryny jako pliki w motywie. Pisz szablony podobne do HTML, a parser Blockstudio przekształci je w natywne bloki WordPress.

  • Strony są synchronizowane z bazą danych jako wpisy WordPress, dzięki czemu szablony plików i treść stron pozostają zgodne.
  • Wzorce są rejestrowane w pamięci przez register_block_pattern() i dostępne w inserterze bloków, skąd użytkownicy mogą wstawiać je w dowolnym miejscu.
  • Szablony witryny udostępniają oparte na plikach źródła wp_template i wp_template_part dla Edytora witryny WordPress.

Wszystkie trzy funkcje korzystają z tego samego parsera HTML i składni bloków.

Tworzenie stron opartych na plikach

Praktyczny przewodnik po szablonach stron opartych na plikach, synchronizacji i blokowaniu.

Struktura folderów

Kod
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

Każdy podfolder zawiera plik konfiguracyjny JSON (page.json, pattern.json, template.json lub part.json) oraz plik szablonu.

Silniki szablonów

Szablony można zapisywać jako zwykły kod znaczników w index.php albo w Twig lub Blade:

Plik Silnik Wymaganie
index.php Brak (odczyt bez zmian, kod PHP nie jest wykonywany) Brak
index.twig Twig Timber
index.blade.php Blade illuminate/view

Jeśli istnieje kilka plików szablonów, obowiązuje kolejność priorytetów: index.php > index.blade.php > index.twig.

Ponieważ szablony są kompilowane podczas inicjalizacji (przed utworzeniem kontekstu żądania), szablony Twig i Blade nie mają dostępu do zmiennych dynamicznych. Przydają się do korzystania z wbudowanych funkcji i filtrów, takich jak {{ "text"|upper }} lub {{ strtoupper("text") }}.

Mapowanie HTML na bloki

Standardowe elementy HTML są automatycznie konwertowane na odpowiadające im bloki WordPress.

Tekst

HTML Blok
<p> core/paragraph
<h1>–<h6> core/heading
<ul> core/list (nieuporządkowana)
<ol> core/list (uporządkowana)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Listy zachowują swoją strukturę. Element <ul> lub <ol> wewnątrz <li> staje się wewnętrznym blokiem core/list tego core/list-item — taką strukturę zapisuje edytor, dzięki czemu listy mogą być zagnieżdżane na dowolną głębokość. class na liście lub jej elemencie staje się jego className, co pozwala ustawić styl bloku, taki jak is-style-checks, w pliku strony; <block name="core/list" className="..."> działa tak samo.

Multimedia

HTML Blok
<img> core/image
<figure> core/image (z podpisem)
<audio> core/audio
<video> core/video

Układ

HTML Blok
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, który zachowuje element jako tagName
<hr> core/separator
<details> core/details
<table> core/table

Składnia bloków

W przypadku bloków bez bezpośredniego odpowiednika HTML użyj elementu <block>:

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

Bloki podstawowe

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>

Bloki niestandardowe

Ta sama składnia działa z każdym zarejestrowanym blokiem:

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>

Atrybuty

Atrybuty HTML elementów <block> są przekazywane jako atrybuty bloku. Obsługiwane są wartości 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" />

Wartości atrybutów są dekodowane jednokrotnie, tak jak odczytuje je przeglądarka, więc data-animate="[&amp;>span]:fade" i data-animate="[&>span]:fade" zapisują tę samą wartość.

W przypadku elementu mapowanego na blok Blockstudio każdy atrybut jest przechowywany wraz z blokiem. Zadeklarowane pola trafiają do szablonu; globalne atrybuty, których blok nie deklaruje (id, style, role, title, lang, dir, hidden, tabindex, aria-* i data-*), są dodawane do elementu głównego bloku podczas renderowania, tak samo jak w przypadku znaczników bloków bloków. W źródłach stron i wzorców prefiks html- oznacza wyłącznie jeden z tych globalnych atrybutów, dlatego html-role="note" jest przekazywany jako role, a procedury obsługi zdarzeń, takie jak html-onclick, nigdy nie są renderowane. Wszystko inne, w tym niezadeklarowany class, pozostaje w treści wpisu i nie trafia na stronę, a wp bs pages sync zgłasza taki przypadek dla każdej przetwarzanej strony.

Niestandardowe renderery bloków

Parser HTML korzysta z architektury opartej na rejestrze. Dodaj konstruktor niestandardowego bloku za pomocą 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 );

Następnie użyj go w dowolnym szablonie:

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

Możesz też zmienić sposób renderowania bloków podstawowych:

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

Funkcje zwrotne konstruktora otrzymują sparsowane atrybuty i surową treść wewnętrzną. Muszą zwracać tablicę bloków WordPress. Pełną kolejność filtrów i przykład kontenera znajdziesz w sekcji Niestandardowe renderery.

Sygnatura funkcji konstruktora

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 {}

Mapowanie elementów

Domyślnie standardowe elementy HTML, takie jak <h1>, <p> i <img>, są mapowane na podstawowe bloki WordPress. Możesz zmienić to mapowanie, aby wskazać dowolnemu elementowi HTML inny blok za pomocą filtra 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 );

Po włączeniu tego filtra każde <h1> w szablonach utworzy blok custom/heading zamiast core/heading. Atrybuty elementu są przekazywane do docelowego bloku. Jeśli zarejestrowano renderer dla nazwy docelowego bloku, zostanie on użyty. W przeciwnym razie powstanie ogólna struktura bloku.

To przydatne, gdy motyw lub wtyczka udostępnia niestandardowe typy bloków, które mają zastępować domyślne w szablonach wszystkich stron i wzorców.

W przypadku prostych mapowań <p> elementów Blockstudio może kierować wewnętrzną zawartość HTML bezpośrednio do atrybutu tekstu sformatowanego content zarejestrowanego bloku Blockstudio spoza podstawowego zestawu. Blok docelowy musi deklarować atrybut z id: "content" i type: "richtext". Formatowanie śródtekstowe (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) pozostaje w przekazywanej wartości, nawet jeśli ten sam znacznik jest mapowany jako element — domyślnie dotyczy to code i img. Akapit, którego jedynym elementem potomnym jest obraz, staje się blokiem, na który mapuje <img>, tak jak w przypadku samodzielnego obrazu generowanego przez Markdown. Zagnieżdżone znaczniki bloków i elementy HTML poziomu blokowego nadal są przetwarzane jako bloki wewnętrzne.

Wartości mapowania mogą być też funkcjami, gdy blok docelowy zależy od atrybutów elementu:

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

Niestandardowe bloki mapowane z elementów kontenerów, takich jak <section> i <div>, rekursywnie przetwarzają zagnieżdżone elementy potomne HTML, więc wewnętrzne nagłówki, obrazy, znaczniki bloków i akapity stają się natywnymi blokami potomnymi.

Pełny przykład

Kompletny szablon strony łączący różne typy bloków:

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>