Gå til indhold

Sider og mønstre

Blockstudio lader dig definere WordPress-sider, blokmønstre og skabeloner til Site Editor som filer i dit tema. Skriv skabeloner i stil med HTML, så konverterer Blockstudios parser dem til native WordPress-blokke.

  • Sider synkroniseres med databasen som WordPress-indlæg, så dine filskabeloner og sideindhold holdes synkroniseret.
  • Mønstre registreres i hukommelsen via register_block_pattern() og er tilgængelige i blokindsætteren, så brugerne kan placere dem hvor som helst.
  • Site-skabeloner leverer filbaserede wp_template– og wp_template_part-kilder til WordPress Site Editor.

Alle tre funktioner bruger den samme HTML-parser og bloksyn­taks.

Sådan bygger du filbaserede sider

En praktisk gennemgang af filbaserede sideskabeloner, synkronisering og låsning.

Mappestruktur

Kode
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

Hver undermappe indeholder en JSON-konfigurationsfil (page.json, pattern.json, template.json eller part.json) og en skabelonfil.

Skabelonmotorer

Skabeloner kan skrives som almindelig markup i index.php eller i Twig eller Blade:

Fil Motor Krav
index.php Ingen (læses som den er, PHP-kode udføres ikke) Ingen
index.twig Twig Timber
index.blade.php Blade illuminate/view

Hvis der findes flere skabelonfiler, er prioritetsrækkefølgen: index.php > index.blade.php > index.twig.

Da skabeloner kompileres ved initialisering (før der findes en request-kontekst), har Twig- og Blade-skabeloner ikke adgang til dynamiske variabler. De er nyttige til indbyggede funktioner og filtre som {{ "text"|upper }} eller {{ strtoupper("text") }}.

Tilknytning af HTML til blokke

Standard-HTML-elementer konverteres automatisk til de tilsvarende WordPress-blokke.

Tekst

HTML Blok
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (uordnet)
<ol> core/list (ordnet)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Lister bevarer deres struktur. Et <ul> eller <ol> inde i et <li> bliver en core/list indre blok i det core/list-item, sådan som editoren gemmer strukturen, så lister kan indlejres på alle niveauer. Et class på en liste eller et punkt bliver dets className, hvilket gør det muligt at angive en bloktypografi som is-style-checks fra en sidefil; <block name="core/list" className="..."> gør det samme.

Medier

HTML Blok
<img> core/image
<figure> core/image (med billedtekst)
<audio> core/audio
<video> core/video

Layout

HTML Blok
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, der bevarer elementet som sin tagName
<hr> core/separator
<details> core/details
<table> core/table

Bloksyntaks

Brug elementet <block> til blokke, der ikke har en direkte HTML-ækvivalent:

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

Kerneblokke

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>

Brugerdefinerede blokke

Den samme syntaks fungerer for alle registrerede blokke:

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>

Attributter

HTML-attributter på <block>-elementer overføres som blokattributter. JSON-værdier understøttes:

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

Attributværdier afkodes én gang, som en browser læser dem, så data-animate="[&amp;>span]:fade" og data-animate="[&>span]:fade" gemmer den samme værdi.

På et element, der er knyttet til en Blockstudio-blok, gemmes alle attributter sammen med blokken. Deklarerede felter overføres til skabelonen; de globale attributter, som blokken ikke deklarerer (id, style, role, title, lang, dir, hidden, tabindex, aria-* og data-*), føjes til blokkens rodelement, når den renderes, præcis som ved bloktags. I side- og mønsterkilder angiver et html--præfiks kun et af disse globale attributter, så html-role="note" videresendes som role, mens event handlers som html-onclick aldrig renderes. Alt andet, herunder et ikke-deklareret class, bliver i indlægsindholdet uden at nå siden, og wp bs pages sync rapporterer det for hver side, den fortolker.

Brugerdefinerede blokrenderere

Parseren HTML bruger en registerbaseret arkitektur. Tilføj en builder til en brugerdefineret blok med 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 );

Brug den derefter i en vilkårlig skabelon:

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

Du kan også tilsidesætte, hvordan kerneblokke renderes:

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 modtager de fortolkede attributter og det rå indre indhold. De skal returnere et blokarray i WordPress-format. Se Brugerdefinerede renderere for hele filterrækkefølgen og et containereksempel.

Builder-funktionens signatur

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

Elementtilknytning

Som standard knyttes standardelementer i HTML, som <h1>, <p> og <img>, til kerneblokke i WordPress. Du kan tilsidesætte denne tilknytning, så et vilkårligt HTML-element knyttes til en anden blok ved hjælp af filteret 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 );

Når dette filter er aktivt, opretter hvert <h1> i dine skabeloner en custom/heading-blok i stedet for core/heading. Elementets attributter overføres til målblokken. Hvis der er registreret en renderer til målblokkens navn, bruges den. Ellers oprettes en generisk blokstruktur.

Dette er nyttigt, når dit tema eller plugin leverer brugerdefinerede bloktyper, der skal erstatte standarderne i alle side- og mønsterskabeloner.

Ved enkle <p>-tilknytninger kan Blockstudio sende indre HTML direkte til en registreret ikke-kerneblok i Blockstudios attribut content af typen richtext. Målblokken skal deklarere en attribut med id: "content" og type: "richtext". Inlineformatering (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) bevares i den videresendte værdi, selv når det samme tag er tilknyttet et element, som code og img er som standard. Et afsnit, hvis eneste barn er et billede, bliver den blok, som <img> knytter til, svarende til det, Markdown opretter for et selvstændigt billede. Indlejrede bloktags og blokniveau-HTML fortolkes fortsat som indre blokke.

Tilknytningsværdier kan også være kaldbare, når målblokken afhænger af elementets attributter:

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

Brugerdefinerede blokke, der er knyttet til containerelementer som <section> og <div>, fortolker indlejrede HTML-børn rekursivt, så indre overskrifter, billeder, bloktags og afsnit bliver til native underblokke.

Komplet eksempel

En komplet sideskabelon, der kombinerer flere bloktyper:

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>