PHP-only blokkok WordPress-ben: egyszerű blokkok regisztrációja JavaScript nélkül

A WordPress blokkszerkesztő (Gutenberg) világában sokáig az volt az alapfelállás, hogy ha saját blokkot akarsz, akkor ahhoz JavaScript oldalon is hozzá kell nyúlnod: blokkregisztráció, editor UI, build folyamat, csomagkezelés, stb. Ez teljesen indokolt a kifejezetten interaktív, kliensoldali élményt igénylő blokkoknál, de rengeteg olyan valós igény van, ahol túl nagy ágyú verébre.

Most már lehetőség van egyszerű blokkok létrehozására kizárólag PHP-val, kifejezetten olyan esetekre, amikor a blokk szerveroldali renderelést (server-side rendering) használ, és nem cél a magas interaktivitás. Ez nem a klasszikus kliensoldali blokkparadigma leváltására készült, és nem is az a cél, hogy ugyanannyira „feature-rich” legyen, mint egy teljes értékű JS-es blokk. Viszont sok projektnél pont elég, és jelentősen csökkentheti a komplexitást – különösen klasszikus témák (classic themes) vagy erősen szervervezérelt munkafolyamatok mellett.

Mire jó a PHP-only blokkregisztráció (és mire nem)?

A PHP-only megközelítés lényege: a blokkot register_block_type() segítségével regisztrálod, megadod az attribútumokat és egy kötelező render_callback-et, a szerkesztő pedig – amennyire tud – automatikusan megjelenít szerkeszthető vezérlőket az Inspector Controls oldalsávban (a jobb oldali blokkbeállításoknál). A blokk megjelenítése a szerveren történik, tehát az editorban a módosítások kiszolgálása is szerveroldali renderhez kötődik.

• Olyan blokkokhoz ideális, amik főleg beállításokból és szerveroldali HTML kimenetből állnak (pl. „author box”, CTA, egyszerű listázók, témaspecifikus dobozok).
• Nem arra készült, hogy erősen interaktív, kliensoldali logikát igénylő blokkokat válts ki.
• Nem cél, hogy hosszú távon ugyanazt a funkcionalitást adja, mint a teljes értékű JS-es block API (tehát korlátokkal kell számolni).

Hogyan működik: autoRegister a register_block_type()-ban

A használat kulcsa, hogy a register_block_type() hívásban a supports tömbben bekapcsolod az autoRegister zászlót, és emellett kötelezően megadsz egy render_callback függvényt is. Ettől a blokk JavaScript-es regisztráció nélkül is meg fog jelenni a szerkesztőben.

<?php

function gutenberg_register_php_only_blocks() {
    register_block_type(
        'my-plugin/example',
        array(
            'title'           => 'My Example Block',
            'attributes'      => array(
                'title'   => array(
                    'type'    => 'string',
                    'default' => 'Hello World',
                ),
                'count'   => array(
                    'type'    => 'integer',
                    'default' => 5,
                ),
                'enabled' => array(
                    'type'    => 'boolean',
                    'default' => true,
                ),
                'size'    => array(
                    'type'    => 'string',
                    'enum'    => array( 'small', 'medium', 'large' ),
                    'default' => 'medium',
                ),
            ),
            'render_callback' => function ( $attributes ) {
                return sprintf(
                    '<div>%s: %d items (%s)</div>',
                    esc_html( $attributes['title'] ),
                    $attributes['count'],
                    $attributes['size']
                );
            },
            'supports'        => array(
                'autoRegister' => true,
            ),
        )
    );
}

add_action( 'init', 'gutenberg_register_php_only_blocks' );

<?php

function gutenberg_register_php_only_blocks() {
    register_block_type(
        'my-plugin/example',
        array(
            'title'           => 'My Example Block',
            'attributes'      => array(
                'title'   => array(
                    'type'    => 'string',
                    'default' => 'Hello World',
                ),
                'count'   => array(
                    'type'    => 'integer',
                    'default' => 5,
                ),
                'enabled' => array(
                    'type'    => 'boolean',
                    'default' => true,
                ),
                'size'    => array(
                    'type'    => 'string',
                    'enum'    => array( 'small', 'medium', 'large' ),
                    'default' => 'medium',
                ),
            ),
            'render_callback' => function ( $attributes ) {
                return sprintf(
                    '<div>%s: %d items (%s)</div>',
                    esc_html( $attributes['title'] ),
                    $attributes['count'],
                    $attributes['size']
                );
            },
            'supports'        => array(
                'autoRegister' => true,
            ),
        )
    );
}

add_action( 'init', 'gutenberg_register_php_only_blocks' );

A fenti minta jól mutatja a tipikus felállást: van néhány attribútum (string, integer, boolean, enum-os string), és ezekből a render_callback legyártja a HTML-t. A szerkesztő pedig a blokk jobb oldali beállításainál próbál automatikus mezőket generálni az attribútumok módosításához.

Automatikus Inspector mezők: mikor működik, és mikor nem?

Az egyik legkényelmesebb része ennek az egésznek, hogy a WordPress – ahol tudja – automatikusan legenerálja a megfelelő vezérlőket (például szövegmező, számmező, checkbox, legördülő) az Inspector Controls oldalsávban. Ettől lesz igazán „PHP-only” élmény: nincs külön JS UI-kód, mégis van szerkeszthető beállítási felület.

Fontos megkötések:

• Nem generálódik vezérlő azokra az attribútumokra, amelyek local szerepkörrel (role) rendelkeznek.
• Nem generálódik vezérlő olyan attribútumtípusokra, amelyeket ez a rendszer nem támogat.

Milyen attribútumtípusok támogatottak jelenleg?

Jelenleg a támogatás kifejezetten szűk. Az automatikusan generált mezők oldaláról nézve ezekre érdemes építeni:

• string
• number
• integer
• boolean

Van még egy nagyon lényeges feltétel: az attribútumok nem lehetnek „sourced” attribútumok. Magyarul: az értékeknek a blokkhatáron belüli JSON-ban kell tárolódniuk (ez az alapértelmezés), és nem lehet az, hogy az attribútum értéke a mentett HTML-ből van visszafejtve/serializálva. Ez a korlátozás több későbbi képesség (például „save jellegű” megoldások) előtt is falat húz.

Ha szeretnél belenézni, a kapcsolódó belső implementáció egyik kapaszkodója ez a függvényrészlet: wp_mark_auto_generate_control_attributes()#L41-L53.

Inner blocks (beágyazott blokkok) támogatása: jelenleg nincs

Gyakori kérdés, hogy lehet-e ezzel a módszerrel konténer blokkokat csinálni, amik más blokkokat fogadnak (InnerBlocks). A válasz jelenleg: nem, és nincs konkrét, egyértelmű iránykijelölés arra, hogy ez mikor vagy hogyan lenne megoldva.

A téma azért összetett, mert a blokkok egymásba ágyazása nem csak annyi, hogy „legyen egy konténer”. Például ilyen kérdések merülnek fel:

• Milyen konkrét beágyazási (nesting) forgatókönyveket várnának a fejlesztők a PHP-only regisztrációval?
• Milyen blokk-szintű és dokumentum-szintű szemantikát várunk el, és ez milyen adatbázis-struktúrát feltételez?
• Milyen kapcsolatokat képzelünk el blokk típusok között? Például egy konkrét parent P típus, ami csak egy konkrét child C példányokat tartalmaz, és mindkettő PHP-only regisztrációt használ? Vagy egy PHP-val generált konténer, ami bármilyen blokkot befogadhat?
• Milyen legyen a fejlesztői ergonomika a kódoldalon: mit jelent ez egy konténer render_callback-jében?
• Milyen legyen a kliensoldali ergonomika, ha azt is figyelembe vesszük, hogy a PHP-only blokkok szerkesztőbeli változásai szerver roundtripet igényelnek (SSR miatt), miközben a szerkesztő vászna alapvetően erősen reaktív blokkokra van kitalálva?
• És a legnehezebb kérdés: miért lenne a PHP-only regisztrációra épített megoldás meggyőzőbb, mint a meglévő – és jóval erősebb – kliensoldali módszertan?

Van-e „save” funkció, ami a post_content-be mentene render_callback helyett?

Ebben a felállásban nincs save funkció. A blokk outputja a render_callback-on keresztül készül, és nincs olyan mechanizmus, amivel ugyanezt a modellt „save a post_content-be” irányba át lehetne fordítani.

Ennek oka nem csak termékdöntés, hanem technikai nehézség is: egy ilyen lépés több problémát hozna magával, például azt, hogyan lehet teljesítményesen és megbízhatóan szerveroldalon „sourcingolni” attribútumokat HTML-ből. (A blokk attribútumok value source témájához: Block attributes – value source.)

Mit várhatsz a jövőtől?

Az autoRegister képesség jelenleg szándékosan egyszerű. Felmerült, hogy a Gutenberg-ben készülő Fields API és az úgynevezett block fields irányok idővel segíthetnek abban, hogy az autoRegister több mezőtípust is képes legyen automatikusan támogatni. Ettől függetlenül erre most korai bármit ígérni; egyelőre a fenti alaptípusokra és a JSON-ban tárolt attribútumokra érdemes tervezni.

Összefoglalás: mikor érdemes ezt választani?

Ha olyan blokkot szeretnél, ami alapvetően szerveroldali outputot ad (SSR), és a szerkesztőben elég néhány egyszerű beállítás (szöveg, szám, boolean, select), akkor a PHP-only blokkregisztrációval rengeteg járulékos terhet le tudsz venni a projektről. Klasszikus témákhoz, kisebb ügyféligények gyors kielégítéséhez, illetve „szűk célú” saját blokkokhoz ez kifejezetten jó eszköz – miközben a komoly, interaktív blokkokhoz továbbra is a hagyományos, JS-es megközelítés marad az igazán erős út.