Ga naar de inhoud

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_template en wp_template_part voor 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

Code
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>:

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

Kernblokken

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>

Aangepaste blokken

Dezelfde syntaxis werkt voor elk geregistreerd 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>

Attributen

HTML-attributen op <block>-elementen worden als blokattributen doorgegeven. JSON-waarden worden ondersteund:

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" />

Attribuutwaarden worden één keer gedecodeerd, zoals een browser ze leest, zodat data-animate="[&amp;>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:

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

Gebruik het vervolgens in een sjabloon:

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

U kunt ook aanpassen hoe kernblokken worden gerenderd:

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

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 container­voorbeeld.

Functiesignatuur van de builder

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

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:

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

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:

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

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:

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>