Ugrás a tartalomhoz

Oldalak és minták

A Blockstudio lehetővé teszi, hogy témájában fájlokként definiáljon WordPress oldalakat, blokkmintákat és a Webhelyszerkesztő sablonjait. Írjon HTML-szerű sablonokat, amelyeket a Blockstudio feldolgozója natív WordPress blokkokká alakít.

  • Oldalak: WordPress bejegyzésekként szinkronizálódnak az adatbázissal, így a fájlsablonok és az oldalak tartalma szinkronban marad.
  • Minták: a rendszer a memóriában regisztrálja őket a register_block_pattern() segítségével, és elérhetők a blokkbeszúróban, hogy a felhasználók bárhol elhelyezhessék őket.
  • Webhelysablonok: fájlalapú wp_template és wp_template_part forrásokat biztosítanak a WordPress Webhelyszerkesztőhöz.

Mindhárom funkció ugyanazt a HTML feldolgozót és blokk-szintaxist használja.

Fájlalapú oldalak készítése

Gyakorlati útmutató a fájlalapú oldalsablonokhoz, a szinkronizáláshoz és a zároláshoz.

Mappastruktúra

Kód
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

Minden almappa tartalmaz egy JSON konfigurációs fájlt (page.json, pattern.json, template.json vagy part.json) és egy sablonfájlt.

Sablonmotorok

A sablonok írhatók egyszerű jelölésként index.php formátumban, illetve Twig vagy Blade használatával:

Fájl Motor Követelmény
index.php Nincs (változtatás nélkül olvassa be, a PHP kód nem fut le) Nincs
index.twig Twig Timber
index.blade.php Blade illuminate/view

Ha több sablonfájl is létezik, a prioritási sorrend: index.php > index.blade.php > index.twig.

Mivel a sablonok inicializáláskor, a kérések kontextusa előtt fordulnak le, a Twig és a Blade sablonok nem férnek hozzá dinamikus változókhoz. Beépített függvényekhez és szűrőkhöz viszont használhatók, például a {{ "text"|upper }} vagy a {{ strtoupper("text") }} esetén.

HTML blokkokra képezése

A szabványos HTML elemek automatikusan a megfelelő WordPress blokkokká alakulnak.

Szöveg

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

A listák megőrzik a szerkezetüket. A <ul> vagy <ol> elem az <li> elemen belül annak core/list-item elemébe ágyazott core/list blokkká válik, ahogyan azt a szerkesztő menti, így a listák tetszőleges mélységig beágyazhatók. A listán vagy egy elemen megadott class annak className értékévé válik; így állítható be például a is-style-checks blokkstílus egy oldalfájlból. A <block name="core/list" className="..."> ugyanezt teszi.

Média

HTML Blokk
<img> core/image
<figure> core/image (képaláírással)
<audio> core/audio
<video> core/video

Elrendezés

HTML Blokk
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, amely az elemet saját tagName-eként tartja meg
<hr> core/separator
<details> core/details
<table> core/table

Blokkszintaxis

Azoknál a blokkoknál, amelyeknek nincs közvetlen HTML megfelelőjük, használja a <block> elemet:

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

Alapblokkok

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>

Egyéni blokkok

Ugyanez a szintaxis bármely regisztrált blokknál használható:

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>

Attribútumok

A HTML attribútumai a <block> elemeknél blokkattribútumként kerülnek átadásra. A következő JSON értékek támogatottak:

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

Az attribútumértékeket a rendszer egyszer dekódolja, úgy, ahogy a böngésző olvassa be őket, ezért a data-animate="[&amp;>span]:fade" és a data-animate="[&>span]:fade" ugyanazt az értéket tárolja.

A Blockstudio blokkhoz rendelt elemen minden attribútumot a rendszer a blokkhoz tárol. A deklarált mezők eljutnak a sablonhoz; a blokk által nem deklarált globális attribútumok (id, style, role, title, lang, dir, hidden, tabindex, aria-* és data-*) megjelenítéskor a blokk gyökérelemére kerülnek, ugyanúgy, mint a blokktageknél. Az oldalak és minták forrásában az html- előtag csak ezen globális attribútumok egyikét jelöli, ezért a html-role="note" továbbításra kerül role formában, az eseménykezelők, például a html-onclick pedig soha nem jelennek meg. Minden más, például egy nem deklarált class, megmarad a bejegyzés tartalmában, de nem jut el az oldalra, és a wp bs pages sync minden általa feldolgozott oldalnál jelzi ezt.

Egyéni blokkmegjelenítők

A HTML feldolgozó nyilvántartás-alapú architektúrát használ. Egyéni blokkhoz a blockstudio/block_tags/builders segítségével adhat hozzá építőt:

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

Ezután bármely sablonban használhatja:

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

Az alapblokkok megjelenítését is felülírhatja:

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

Az építő visszahívásai megkapják a feldolgozott attribútumokat és a nyers belső tartalmat. Egy WordPress blokk tömbjét kell visszaadniuk. A teljes szűrősorrendért és a tároló példájáért lásd az Egyéni megjelenítők oldalt.

Az építőfüggvény aláírása

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

Elemtérképzés

Alapértelmezés szerint az olyan szabványos HTML elemek, mint a <h1>, a <p> és a <img>, alapvető WordPress blokkokhoz vannak rendelve. Ezt a leképezést felülírva bármely HTML elemet egy másik blokkhoz rendelhet a blockstudio/parser/element_mapping szűrő segítségével:

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

Ha ez a szűrő aktív, a sablonok minden <h1> eleme custom/heading blokkot hoz létre a core/heading helyett. Az elem attribútumai továbbkerülnek a célblokkhoz. Ha a célblokk nevéhez van regisztrálva megjelenítő, a rendszer azt használja. Ellenkező esetben általános blokkszerkezet jön létre.

Ez akkor hasznos, ha a témája vagy bővítménye olyan egyéni blokktípusokat biztosít, amelyeknek minden oldal- és mintasablonban le kell váltaniuk az alapértelmezett blokkokat.

Egyszerű <p> leképezéseknél a Blockstudio közvetlenül a regisztrált, nem alapszintű Blockstudio blokk content richtext attribútumába irányíthatja a belső HTML tartalmat. A célblokknak deklarálnia kell egy attribútumot a id: "content" és type: "richtext" értékekkel. A soron belüli formázás (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) a továbbított értékben marad akkor is, ha ugyanaz a tag elemtérképezést kap, ahogyan alapértelmezés szerint a code és a img esetén történik. Az olyan bekezdés, amelynek egyetlen gyermeke egy kép, azzá a blokkká válik, amelyhez a <img> rendeli, ezt hozza létre a Markdown önálló kép esetén. A beágyazott blokktagek és a blokkszintű HTML továbbra is belső blokkokként kerülnek feldolgozásra.

A leképezési értékek függvényhívhatók is lehetnek, ha a célblokk az elem attribútumaitól függ:

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

A tárolóelemekből, például <section> és <div> elemekből leképezett egyéni blokkok rekurzívan dolgozzák fel a beágyazott HTML gyermekelemeket, így a belső címsorok, képek, blokktagek és bekezdések natív gyermekblokkokká válnak.

Teljes példa

Teljes oldalsablon többféle blokktípussal:

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>