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_templateawp_template_partzalož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
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>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Základní bloky
<!-- 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:
<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:
<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="[&>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:
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ě:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Můžete také přepsat způsob vykreslování základních bloků:
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
/**
* @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:
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:
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ů:
<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>