Přejít k obsahu

Stránky a vzory

Blockstudio vám umožňuje definovat stránky WordPress, vzory bloků a šablony Editoru webu jako soubory ve vašem motivu. Pište šablony ve stylu HTML a parser Blockstudio je převede na nativní bloky WordPress.

  • Stránky se synchronizují s databází jako příspěvky WordPress, takže šablony souborů a obsah stránek zůstávají synchronizované.
  • Vzory se registrují v paměti prostřednictvím register_block_pattern() a jsou dostupné ve vkladači bloků, kde je uživatelé mohou vložit kamkoli.
  • Šablony webu poskytují zdroje wp_template a wp_template_part založené na souborech pro Editor webu WordPress.

Všechny tři funkce používají stejný parser HTML a syntaxi bloků.

Tvorba stránek založených na souborech

Praktický průvodce šablonami stránek založenými na souborech, synchronizací a zamykáním.

Struktura složek

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á podsložka obsahuje konfigurační soubor JSON (page.json, pattern.json, template.json nebo part.json) a soubor šablony.

Šablonovací nástroje

Šablony lze psát jako prosté značky v index.php nebo v Twig či Blade:

Soubor Nástroj Požadavek
index.php Žádný (čte se beze změn, kód PHP se nespouští) Žádný
index.twig Twig Timber
index.blade.php Blade illuminate/view

Pokud existuje více souborů šablon, pořadí priorit je: index.php > index.blade.php > index.twig.

Protože se šablony kompilují při inicializaci (před vytvořením kontextu požadavku), šablony Twig a Blade nemají přístup k dynamickým proměnným. Hodí se pro vestavěné funkce a filtry, jako jsou {{ "text"|upper }} nebo {{ strtoupper("text") }}.

Mapování HTML na bloky

Standardní prvky HTML se automaticky převádějí na odpovídající 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

Seznamy si zachovávají svou strukturu. Prvek <ul> nebo <ol> uvnitř prvku <li> se stane vnitřním blokem core/list tohoto core/list-item, což odpovídá struktuře, kterou editor ukládá, takže seznamy lze libovolně zanořovat. Atribut class seznamu nebo položky se stane jeho className. Tak lze nastavit styl bloku, například is-style-checks, přímo v souboru stránky; totéž provede <block name="core/list" className="...">.

Média

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

Rozvržení

HTML Blok
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, který zachovává prvek jako své tagName
<hr> core/separator
<details> core/details
<table> core/table

Syntaxe bloků

U bloků, které nemají přímý ekvivalent v HTML, použijte prvek <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

Stejná syntaxe funguje pro libovolný registrovaný 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>

Atributy

Atributy HTML u prvků <block> se předávají jako atributy bloku. Podporovány jsou 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 atributů se dekódují jednou, stejně jako je čte prohlížeč, takže data-animate="[&amp;>span]:fade" a data-animate="[&>span]:fade" ukládají stejnou hodnotu.

U prvku namapovaného na blok Blockstudio se spolu s blokem ukládají všechny atributy. Deklarovaná pole se předávají šabloně; globální atributy, které blok nedeklaruje (id, style, role, title, lang, dir, hidden, tabindex, aria-* a data-*), se při vykreslení umístí na kořenový prvek bloku, stejně jako u značek bloků. Ve zdrojích stránek a vzorů předpona html- označuje pouze jeden z těchto globálních atributů, takže html-role="note" se předá jako role, zatímco obslužné rutiny událostí, jako je html-onclick, se nikdy nevykreslují. Všechno ostatní, včetně nedeklarovaného class, zůstává v obsahu příspěvku a na stránku se nepředává. wp bs pages sync na to upozorní u každé stránky, kterou parsuje.

Vykreslovače vlastních bloků

Parser HTML využívá architekturu založenou na registru. Přidejte tvůrce vlastního bloku 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 );

Pak jej použijte v libovolné šabloně:

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

Můžete také přepsat způsob vykreslování základních bloků:

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

Zpětná volání tvůrce dostávají naparsované atributy a surový vnitřní obsah. Musí vrátit pole bloků WordPress. Úplné pořadí filtrů a příklad kontejneru najdete v části Vlastní vykreslovače.

Signatura funkce tvůrce

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

Mapování prvků

Ve výchozím nastavení se standardní prvky HTML, jako jsou <h1>, <p> a <img>, mapují na základní bloky WordPress. Toto mapování můžete přepsat a pomocí filtru blockstudio/parser/element_mapping namapovat libovolný prvek HTML na jiný blok:

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

Při aktivním tomto filtru vytvoří každý prvek <h1> v šablonách blok custom/heading místo bloku core/heading. Atributy prvku se předají cílovému bloku. Pokud je pro název cílového bloku registrován vykreslovač, použije se. Jinak se vytvoří obecná struktura bloku.

To se hodí, pokud váš motiv nebo plugin poskytuje vlastní typy bloků, které mají ve všech šablonách stránek a vzorů nahradit výchozí bloky.

U jednoduchých mapování <p> může Blockstudio směrovat vnitřní HTML přímo do atributu richtext registrovaného bloku Blockstudio mimo jádro content. Cílový blok musí deklarovat atribut pomocí id: "content" a type: "richtext". Vložené formátování (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) zůstává ve směrované hodnotě, i když je stejná značka standardně mapována také na prvek, jako je tomu u code a img. Odstavec, jehož jediným potomkem je obrázek, se změní na blok, na který mapuje <img>; takový blok vytváří Markdown pro samostatný obrázek. Vnořené značky bloků a obsah na úrovni bloku HTML se nadále zpracovávají jako vnitřní bloky.

Hodnoty mapování mohou být také volatelné, pokud cílový blok závisí na atributech 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 kontejnerových prvků, jako jsou <section> a <div>, rekurzivně parsují vnořené potomky HTML. Vnitřní nadpisy, obrázky, značky bloků a odstavce se tak stanou nativními podřízenými bloky.

Úplný příklad

Kompletní šablona stránky kombinující několik typů bloků:

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>