Pagina’s en patronen
Met Blockstudio definieert u WordPress-pagina’s, blokpatronen en Site Editor-sjablonen als bestanden in uw thema. Schrijf sjablonen zoals HTML en de parser van Blockstudio zet ze om in native WordPress-blokken.
- Pagina’s worden als WordPress-berichten met de database gesynchroniseerd, zodat uw bestandssjablonen en pagina-inhoud synchroon blijven.
- Patronen worden via
register_block_pattern()in het geheugen geregistreerd en zijn beschikbaar in de blokinvoeger, zodat gebruikers ze overal kunnen plaatsen. - Sitesjablonen bieden bestandsgestuurde bronnen voor
wp_templateenwp_template_partvoor de WordPress Site Editor.
Alle drie functies gebruiken dezelfde HTML-parser en bloks syntaxis.
Pagina’s op basis van bestanden bouwen
Een praktische handleiding voor bestandssjablonen voor pagina’s, synchronisatie en vergrendeling.
Mapstructuur
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
Elke submap bevat een JSON-configuratiebestand (page.json, pattern.json, template.json of part.json) en een sjabloonbestand.
Sjabloonengines
Sjablonen kunnen worden geschreven als gewone opmaak in index.php, of in Twig of Blade:
| Bestand | Engine | Vereiste |
|---|---|---|
index.php |
Geen (wordt ongewijzigd gelezen, PHP-code wordt niet uitgevoerd) | Geen |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Als er meerdere sjabloonbestanden bestaan, geldt deze prioriteitsvolgorde: index.php > index.blade.php > index.twig.
Omdat sjablonen tijdens de initialisatie worden gecompileerd (voordat er een aanvraagcontext is), hebben Twig- en Blade-sjablonen geen toegang tot dynamische variabelen. Ze zijn nuttig voor ingebouwde functies en filters zoals {{ "text"|upper }} of {{ strtoupper("text") }}.
Mapping van HTML naar blokken
Standaard-HTML-elementen worden automatisch omgezet naar de bijbehorende WordPress-blokken.
Tekst
| HTML | Blok |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (ongeordend) |
<ol> |
core/list (geordend) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Lijsten behouden hun structuur. Een <ul> of <ol> binnen een <li> wordt een
core/list-binnenblok van die core/list-item, zoals de editor het opslaat,
zodat lijsten onbeperkt diep kunnen worden genest. Een class op een lijst of item wordt het
className ervan; zo stelt u een blokstijl zoals is-style-checks in vanuit een
paginabestand. <block name="core/list" className="..."> doet hetzelfde.
Media
| HTML | Blok |
|---|---|
<img> |
core/image |
<figure> |
core/image (met bijschrift) |
<audio> |
core/audio |
<video> |
core/video |
Indeling
| HTML | Blok |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group dat het element als zijn tagName behoudt |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Bloksyntaxis
Gebruik voor blokken zonder directe HTML-equivalent het element <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Kernblokken
<!-- 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>
Aangepaste blokken
Dezelfde syntaxis werkt voor elk geregistreerd 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>
Attributen
HTML-attributen op <block>-elementen worden als blokattributen doorgegeven. JSON-waarden worden ondersteund:
<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" />
Attribuutwaarden worden één keer gedecodeerd, zoals een browser ze leest, zodat
data-animate="[&>span]:fade" en data-animate="[&>span]:fade" dezelfde waarde opslaan.
Op een element dat aan een Blockstudio-blok is gekoppeld, wordt elk attribuut bij
het blok opgeslagen. Gedeclareerde velden zijn beschikbaar in het sjabloon; de globale attributen die het blok
niet declareert (id, style, role, title, lang, dir, hidden,
tabindex, aria-* en data-*) worden bij het renderen op het root-element van het
blok geplaatst, precies zoals bij bloktags. In
pagina- en patroonbronnen benoemt een html--prefix alleen een van die globale
attributen, dus html-role="note" wordt doorgegeven als role, terwijl eventhandlers zoals
html-onclick nooit worden gerenderd. Al het overige, inclusief een niet-gedeclareerde
class, blijft in de berichtinhoud zonder de pagina te bereiken, en
wp bs pages sync meldt dit voor elke pagina die de parser verwerkt.
Aangepaste blokrenderers
De HTML-parser gebruikt een op registers gebaseerde architectuur. Voeg met blockstudio/block_tags/builders een builder voor een aangepast
blok toe:
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 );
Gebruik het vervolgens in een sjabloon:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
U kunt ook aanpassen hoe kernblokken worden gerenderd:
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 );
Builder-callbacks ontvangen de geparste attributen en de ruwe binneninhoud. Ze moeten een WordPress-blokarray retourneren. Zie Aangepaste renderers voor de volledige filtervolgorde en het containervoorbeeld.
Functiesignatuur van de builder
/**
* @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 {}
Elementmapping
Standaard worden standaard-HTML-elementen zoals <h1>, <p> en <img> gekoppeld aan WordPress-kernblokken. U kunt deze koppeling aanpassen zodat elk HTML-element naar een ander blok verwijst met het filter blockstudio/parser/element_mapping:
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 );
Met dit actieve filter levert elke <h1> in uw sjablonen een custom/heading-blok op in plaats van core/heading. De attributen van het element worden doorgegeven aan het doelblok. Als er een renderer voor de naam van het doelblok is geregistreerd, wordt die gebruikt. Anders wordt er een generieke blokstructuur aangemaakt.
Dit is handig wanneer uw thema of plugin aangepaste bloktypen aanbiedt die in alle pagina- en patroonsjablonen de standaardtypen moeten vervangen.
Voor eenvoudige <p>-koppelingen kan Blockstudio de binnenste HTML rechtstreeks doorsturen naar het richtext-attribuut content van een geregistreerd niet-kern-Blockstudio-blok. Het doelblok moet een attribuut declareren met id: "content" en type: "richtext".
Inline-opmaak (a, b, br, code, del, em, i, img, ins,
mark, s, small, span, strong, sub, sup, u) blijft behouden in de doorgestuurde
waarde, ook als dezelfde tag standaard aan een element is gekoppeld, zoals code en img. Een alinea waarvan de enige inhoud een afbeelding is, wordt het blok waaraan <img> is gekoppeld, net zoals Markdown dat doet voor een losse afbeelding. Geneste bloktags en blokniveau-HTML blijven als binnenblokken worden geparseerd.
Koppelingswaarden kunnen ook aanroepbare functies zijn wanneer het doelblok afhankelijk is van de attributen van het element:
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;
} );
Aangepaste blokken die zijn gekoppeld aan containerelementen zoals <section> en <div> verwerken geneste HTML-elementen recursief, zodat binnenliggende koppen, afbeeldingen, bloktags en alinea’s native onderliggende blokken worden.
Compleet voorbeeld
Een volledig paginasjabloon waarin meerdere bloktypen worden gecombineerd:
<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>