Preskočiť na obsah

Stránky a vzory

Blockstudio vám umožňuje definovať stránky WordPress, vzory blokov a šablóny Editora webu ako súbory vo vašej téme. Píšte šablóny podobné HTML a parser Blockstudio ich prevedie na natívne bloky WordPress.

  • Stránky sa synchronizujú s databázou ako príspevky WordPress, takže šablóny súborov a obsah stránok zostávajú zosynchronizované.
  • Vzory sa registrujú v pamäti prostredníctvom register_block_pattern() a používateľom sú dostupné vo vkladači blokov, aby ich mohli vložiť kamkoľvek.
  • Šablóny webu poskytujú zdroje wp_template a wp_template_part uložené v súboroch pre WordPress Editor webu.

Všetky tri funkcie používajú rovnaký parser HTML a syntax blokov.

Vytváranie stránok zo súborov

Praktický návod na šablóny stránok zo súborov, synchronizáciu a uzamknutie.

Štruktúra priečinkov

Kód
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ždý podpriečinok obsahuje konfiguračný súbor JSON (page.json, pattern.json, template.json alebo part.json) a súbor šablóny.

Šablónovacie nástroje

Šablóny možno písať ako obyčajné značky v index.php alebo v jazyku Twig či Blade:

Súbor Nástroj Požiadavka
index.php Žiadny (číta sa bez úprav, kód PHP sa nespúšťa) Žiadna
index.twig Twig Timber
index.blade.php Blade illuminate/view

Ak existuje viac súborov šablón, platí toto poradie priorít: index.php > index.blade.php > index.twig.

Keďže sa šablóny kompilujú pri inicializácii (pred vytvorením kontextu požiadavky), šablóny Twig a Blade nemajú prístup k dynamickým premenným. Sú užitočné pre vstavané funkcie a filtre, ako sú {{ "text"|upper }} alebo {{ strtoupper("text") }}.

Mapovanie HTML na bloky

Štandardné prvky HTML sa automaticky prevedú na príslušné bloky WordPress.

Text

HTML Blok
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (nečíslovaný)
<ol> core/list (číslovaný)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Zoznamy si zachovávajú svoju štruktúru. Prvok <ul> alebo <ol> vnútri prvku <li> sa zmení na vnorený blok core/list daného prvku core/list-item, čo je štruktúra, ktorú editor ukladá, takže zoznamy možno vnárať do ľubovoľnej hĺbky. Prvok class v zozname alebo jeho položke sa zmení na className, čím možno zo súboru stránky nastaviť štýl bloku, napríklad is-style-checks; rovnako funguje aj <block name="core/list" className="...">.

Médiá

HTML Blok
<img> core/image
<figure> core/image (s popisom)
<audio> core/audio
<video> core/video

Rozloženie

HTML Blok
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, ktorý zachová prvok ako svoj tagName
<hr> core/separator
<details> core/details
<table> core/table

Syntax blokov

Pre bloky, ktoré nemajú priamy ekvivalent HTML, použite prvok <block>:

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

Základné bloky

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>

Vlastné bloky

Rovnaká syntax funguje pre každý zaregistrovaný blok:

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>

Atribúty

Atribúty HTML prvkov <block> sa odovzdávajú ako atribúty bloku. Podporované sú hodnoty 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" />

Hodnoty atribútov sa dekódujú raz, tak ako ich číta prehliadač, takže data-animate="[&amp;>span]:fade" a data-animate="[&>span]:fade" ukladajú rovnakú hodnotu.

Pri prvku namapovanom na blok Blockstudio sa každý atribút uloží spolu s blokom. Deklarované polia sú dostupné šablóne; globálne atribúty, ktoré blok nedeklaruje (id, style, role, title, lang, dir, hidden, tabindex, aria-* a data-*), sa pri vykreslení vložia do koreňového prvku bloku, rovnako ako pri značkách blokov. V zdrojoch stránok a vzorov prefix html- označuje iba jeden z týchto globálnych atribútov, takže html-role="note" sa prenesie ako role, zatiaľ čo obslužné rutiny udalostí, ako napríklad html-onclick, sa nikdy nevykreslia. Všetko ostatné vrátane nedeklarovaného class zostáva v obsahu príspevku bez toho, aby sa dostalo na stránku, a wp bs pages sync to nahlási pri každej stránke, ktorú analyzuje.

Vykresľovače vlastných blokov

Parser HTML používa architektúru založenú na registri. Pridajte zostavovač vlastného bloku pomocou 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 );

Potom ho použite v ľubovoľnej šablóne:

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

Môžete tiež prepísať spôsob vykresľovania základných blokov:

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

Funkcie spätného volania zostavovača dostávajú zanalyzované atribúty a surový vnútorný obsah. Musia vrátiť pole blokov WordPress. Úplné poradie filtrov a príklad kontajnera nájdete v časti Vlastné vykresľovače.

Signatúra funkcie zostavovača

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

Mapovanie prvkov

Predvolene sa štandardné prvky HTML, ako sú <h1>, <p> a <img>, mapujú na základné bloky WordPress. Toto mapovanie môžete zmeniť tak, aby ľubovoľný prvok HTML smeroval na iný blok, pomocou 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 );

Keď je tento filter aktívny, každý prvok <h1> vo vašich šablónach vytvorí blok custom/heading namiesto bloku core/heading. Atribúty prvku sa odovzdajú cieľovému bloku. Ak je pre názov cieľového bloku zaregistrovaný vykresľovač, použije sa. V opačnom prípade sa vytvorí všeobecná štruktúra bloku.

Je to užitočné, ak vaša téma alebo doplnok poskytuje vlastné typy blokov, ktoré majú nahradiť predvolené bloky vo všetkých šablónach stránok a vzorov.

Pri jednoduchých mapovaniach <p> môže Blockstudio smerovať vnútorný obsah HTML priamo do atribútu richtext content registrovaného bloku Blockstudio od iného autora. Cieľový blok musí deklarovať atribút pomocou id: "content" a type: "richtext". Vložené formátovanie (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) zostáva v smerovanej hodnote, aj keď je rovnaká značka predvolene mapovaná ako prvok code a img. Odsek, ktorého jediným potomkom je obrázok, sa zmení na blok, na ktorý mapuje <img>; práve taký blok vytvorí Markdown pre samostatný obrázok. Vnorené značky blokov a blokový obsah HTML sa naďalej spracúvajú ako vnútorné bloky.

Mapovacie hodnoty môžu byť aj volateľné funkcie, ak cieľový blok závisí od atribútov prvku:

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

Vlastné bloky namapované z kontajnerových prvkov, ako sú <section> a <div>, rekurzívne analyzujú vnorené potomky HTML, takže vnútorné nadpisy, obrázky, značky blokov a odseky sa zmenia na natívne podriadené bloky.

Úplný príklad

Kompletná šablóna stránky, ktorá kombinuje viacero typov blokov:

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>