Sidor & mönster
Blockstudio låter dig definiera WordPress-sidor, blockmönster och mallar för webbplatsredigeraren som filer i ditt tema. Skriv mallar som liknar HTML, så omvandlar Blockstudios parser dem till inbyggda WordPress-block.
- Sidor synkroniseras med databasen som WordPress-inlägg, så att filmallarna och sidinnehållet hålls synkroniserade.
- Mönster registreras i minnet via
register_block_pattern()och är tillgängliga i blockinfogaren så att användare kan placera dem var som helst. - Webbplatsmallar tillhandahåller filbaserade
wp_template– ochwp_template_part-källor för WordPresss webbplatsredigerare.
Alla tre funktionerna använder samma HTML-parser och blocksyntax.
En praktisk genomgång av filbaserade sidmallar, synkronisering och låsning.
Mappstruktur
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
Varje undermapp innehåller en JSON-konfigurationsfil (page.json, pattern.json, template.json eller part.json) och en mallfil.
Mallmotorer
Mallar kan skrivas som vanlig markup i index.php eller i Twig eller Blade:
| Fil | Motor | Krav |
|---|---|---|
index.php |
Ingen (läses som den är, PHP-kod körs inte) | Inga |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Om flera mallfiler finns är prioritetsordningen: index.php > index.blade.php > index.twig.
Eftersom mallar kompileras vid initiering (innan någon begärandekontext finns) har mallar i Twig och Blade inte tillgång till dynamiska variabler. De är användbara för inbyggda funktioner och filter som {{ "text"|upper }} eller {{ strtoupper("text") }}.
Mappning från HTML till block
Vanliga HTML-element konverteras automatiskt till motsvarande WordPress-block.
Text
| HTML | Block |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (oordnad) |
<ol> |
core/list (ordnad) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Listor behåller sin struktur. En <ul> eller <ol> inuti ett <li> blir ett inre core/list-block i det core/list-item, vilket är den struktur som redigeraren sparar, så listor kan nästlas på valfritt djup. Ett class på en lista eller ett objekt blir dess className, vilket gör att en blockstil som is-style-checks kan anges från en sidfil; <block name="core/list" className="..."> gör samma sak.
Media
| HTML | Block |
|---|---|
<img> |
core/image |
<figure> |
core/image (med bildtext) |
<audio> |
core/audio |
<video> |
core/video |
Layout
| HTML | Block |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group som behåller elementet som sitt tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Blocksyntax
För block som saknar en direkt motsvarighet i HTML använder du elementet <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Kärnblock
<!-- 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>
Anpassade block
Samma syntax fungerar för alla registrerade block:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Attribut
Attribut på elementen HTML <block> skickas vidare som blockattribut. Värden för JSON stöds:
<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ärden avkodas en gång, på samma sätt som när en webbläsare läser dem, så data-animate="[&>span]:fade" och data-animate="[&>span]:fade" lagrar samma värde.
På ett element som mappas till ett Blockstudio-block lagras varje attribut med blocket. Deklarerade fält når mallen; de globala attribut som blocket inte deklarerar (id, style, role, title, lang, dir, hidden, tabindex, aria-* och data-*) läggs på blockets rotelement när det renderas, precis som på blocktaggar. I sid- och mönsterkällor anger prefixet html- bara ett av dessa globala attribut, så html-role="note" skickas vidare som role, medan händelsehanterare som html-onclick aldrig renderas. Allt annat, inklusive ett odeklarerat class, finns kvar i inläggsinnehållet utan att visas på sidan, och wp bs pages sync rapporterar det för varje sida som den tolkar.
Renderare för anpassade block
Parsern HTML använder en registerbaserad arkitektur. Lägg till en byggare för ett anpassat block med 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 );
Använd den sedan i valfri mall:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Du kan också åsidosätta hur kärnblock renderas:
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 );
Återanrop för byggaren tar emot de tolkade attributen och det råa inre innehållet. De måste returnera en WordPress-blockarray. Se Renderare för anpassade block för hela filterordningen och ett exempel med en container.
Byggarfunktionens signatur
/**
* @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 {}
Elementmappning
Som standard mappas vanliga HTML-element som <h1>, <p> och <img> till kärnblock i WordPress. Du kan åsidosätta mappningen så att valfritt HTML-element pekar på ett annat block med filtret 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 );
När det här filtret är aktivt skapar varje <h1> i dina mallar ett custom/heading-block i stället för core/heading. Elementets attribut skickas vidare till målblocket. Om en renderare har registrerats för målblocket används den. Annars skapas en generisk blockstruktur.
Detta är användbart när ditt tema eller tillägg tillhandahåller anpassade blocktyper som ska ersätta standardblocken i alla sid- och mönstermallar.
För enkla <p>-mappningar kan Blockstudio dirigera inre HTML direkt till attributet content av typen richtext i ett registrerat block av typen Blockstudio. Målblocket måste deklarera ett attribut med id: "content" och type: "richtext". Formatering i löptext (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) finns kvar i det vidarebefordrade värdet även när samma tagg är elementmappad, som code och img är som standard. Ett stycke vars enda underordnade element är en bild blir det block som <img> mappas till, vilket är vad Markdown skapar för en fristående bild. Nästlade blocktaggar och blockelement på blocknivå i HTML fortsätter att tolkas som inre block.
Mappningsvärden kan också vara anropbara när målblocket beror på elementattribut:
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;
} );
Anpassade block som mappas från containerelement som <section> och <div> tolkar nästlade HTML-element rekursivt, så att inre rubriker, bilder, blocktaggar och stycken blir inbyggda underordnade block.
Komplett exempel
En fullständig sidmall som kombinerar flera blocktyper:
<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>