Ugrás a tartalomhoz

Programozott megjelenítés

Mivel a Gutenberg egyre fontosabb eszköz az ügyfelek számára könnyen szerkeszthető webhelyek létrehozásában, érdemes a webhely minden szükséges részét blokkokként megalkotni. Ez a megközelítés a legtöbb igényt kielégíti, de a haladó felhasználóknak és bizonyos esetekben szükségük lehet arra, hogy a meglévő blokkokat a szerkesztőn kívül használják.

A Blockstudio kétféle megoldást kínál a blokkok programozott megjelenítésére:

  • PHP függvények: bs_render_block és bs_block blokkok megjelenítése PHP kódból
  • HTML címkék: <bs:block-name> címkék, amelyek az oldal bármely részén blokk kimenetére cserélhetők

Minden Blockstudio-specifikus funkció, például a sorközi stílusok, szkriptek és a hatókörre korlátozott stílusok is támogatottak.

Az Islands ezen megjelenítési útvonalakon is működik. A bs_render_block(), bs_block() vagy blokkcímkével megjelenített dinamikus sziget ugyanazt a helyőrzőjelölőt adja vissza, mint a bejegyzés tartalmából megjelenített blokk, és a válaszban szereplő jelölő hatására az előtér futtatókörnyezete is bekerül.

Strukturált összeállítások és teljes dokumentumok

Hosszú élettartamú eszközökhöz, előnézetekhez, exportokhoz és komponensgalériákhoz használd a verziózott Blockstudio\Render API megoldást. Egyetlen deklarációt vagy rendezett listát fogad el, és echo nélkül jelenít meg:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

A kanonikus, normalizált deklaráció négy kulcsból áll:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

A data, inner, innerBlocks, root, layers és example bemeneti kényelmi lehetőségek, amelyeket a rendszer normalizáláskor eltávolít. A beágyazott deklarációk rekurzívan, ugyanazon a Blockstudio folyamaton keresztül jelennek meg.

A Render::document() a következőket adja vissza: schemaVersion, html, body, blocks, assets, warnings és errors. A assets érték különíti el ezeket: head, footer, styles, scripts, modules, interactivity, ui és tailwind. A blokkok listája és az eszközök tartalmazzák a kiválasztott sablonok hivatkozott függőségeit, de a nem kapcsolódó és csak szerkesztőben használatos eszközöket kizárják.

A teljes dokumentumok megadhatják a bodyClasses/bodyAttributes értéket, és opcionálisan a megjelenített törzset a következőkkel foglalhatják burkolóelembe: contentElement, contentClasses és contentAttributes. A burkolóelem csak biztonságos elemmel használható; a visszaadott body továbbra is a burkolatlan, megjelenített tartalom marad. A head és footer beállítás a megfelelő helyre fűzi be a megbízható dokumentumjelölést, és bekerül a visszaadott eszközfüggőségek közé.

Egy már renderelt dokumentum összeállításához adja meg a HTML ismert gyökérblokkjainak nevét:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Sorozatosított WordPress blokk-tartalomhoz használja a Render::content() elemet. Azoknak a fogyasztóknak, amelyek egy kérésben több független dokumentumot renderelnek, hívják meg közöttük a Blockstudio\Batch_Render::reset() elemet; ezt a Canvas::documents() automatikusan elvégzi.

Megjelenítés az oldalon kívül

A Blockstudio minden általa megjelenített blokk elé <!--blockstudio/namespace/slug--> megjegyzést helyez. A webhely látogatói számára megjelenített oldal esetén a kimeneti puffer beolvassa ezeket a megjegyzéseket, megállapítja, mely blokkok vannak jelen, betölti az eszközeiket, majd eltávolítja a megjegyzéseket, mielőtt elküldi a választ.

Az a kimenet, amely nem halad át ezen a pufferen, megőrzi a megjegyzéseket. Ez vonatkozik a REST válaszokra, a hírcsatornákra, az AJAX-kezelőkre, valamint azokra a HTML adatokra, amelyeket a do_blocks(), a Render::content() vagy a bs_render_block() után máshol tárol vagy elküld. A megjegyzések eltávolításához használja a bs_strip_render_markers() függvényt:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

A függvény eltávolítja a regisztrált Blockstudio blokkok megjegyzéseit, és minden mást érintetlenül hagy, az egyéb HTML megjegyzéseket is beleértve. Ugyanazokat a jelölőket ismeri fel, amelyeket az oldalpuffer eltávolít. A blokk regisztrálása után hívja meg (init vagy újabb verzióban).

Ne távolítsa el az oldaljelölést, ha a tartalom még bekerül egy pufferelt, webhelylátogatóknak szánt oldalba. Az oldalnak szüksége van a megjegyzésekre annak megállapításához, mely blokk-eszközöket kell betölteni, a Blockstudio pedig a végén maga távolítja el őket.

A megjegyzések eltávolítása nem ad hozzá eszközöket. A blokk CSS és JavaScript fájljait csak az oldalpuffer illeszti be. Használja a bs_block_assets() elemet vagy a Render::document() függvényt, ha a felhasználónak ezekre is szüksége van.

Blokkok vizsgálata

A regisztrált meződefiníciók feloldott alakjának lekéréséhez használja a bs_block_fields() függvényt a blokk regisztrálása után (init vagy újabb verzióban), anélkül, hogy belső regisztereket kellene beolvasnia:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

A visszatérési érték a regisztrált meződefiníciók tömbje, amely tartalmazza az attribútumszűrőket, a kibontott egyéni mezőket, a felülírásokat, valamint a beágyazott csoportokat, lapfüleket és ismétlőket. Egy mező nélküli Blockstudio blokk esetén az eredmény []. Az eredmény másolat: a módosítása nem változtatja meg a regisztrált blokkot.

Ezek definíciók, nem mentett értékek. A mentett jelölés ellenőrzéséhez használja a bs_validate_block() elemet külön mezőbejáró fenntartása helyett. A blokk által elfogadott értékek leírásához használja a bs_block_schema() elemet. A WordPress által kezelt attribútumok külön maradnak.

A bővítményekkel hozzáadott mezők nem részei a bs_block_fields() elemnek. A lekérésükhöz használja a bs_block_extension_fields() függvényt. A bővítményeket blokknév alapján keresi meg, így az alapértelmezett és a külső felek által készített blokkokkal is működik:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

A visszatérési érték minden egyező bővítmény meződefinícióit felsorolja a bővítmények regisztrálásának sorrendjében, a bs_block_fields() elemével megegyező szerkezetben. Ha egy blokkhoz egyetlen bővítmény sem illeszkedik, az eredmény []. A bővítmények értékei ugyanabban a attrs.blockstudio.attributes objektumban tárolódnak, mint a blokk saját mezőértékei, ezért minden azonosító ugyanazt a névteret használja. Ha két bővítmény ugyanazt az azonosítót definiálja, mindkét definíció visszatér, és ugyanazt az értéket szerkeszti; megjelenítéskor a később regisztrált bővítmény definíciója érvényesül.

Ha egy mentett blokk értékeit úgy szeretné beolvasni, ahogyan azokat a sablon megkapja, használja a bs_block_values() függvényt.

A blokk felismert CSS értékeinek és a JavaScript adatainak vizsgálatához használja a bs_block_assets() függvényt. Az összes blokkot és megosztott futásidejű függőséget tartalmazó teljes előnézeti dokumentumhoz használja a fent leírt Render::document() elemet.

Tárolt értékek ellenőrzése

A programozottan létrehozott vagy importált blokkattribútumok mentés előtti ellenőrzéséhez használja a bs_validate_block() függvényt a blokk regisztrálása után (init vagy újabb verzióban):

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Adja át a teljes attrs tömböt, ne csak a blockstudio.attributes elemet. A Blockstudio megjelenítése a deklarált mezőket a legfelső szinten is elfogadja, és ha mindkettőt megadja, a beágyazott értékek élveznek elsőbbséget. Az alapértelmezett és külső blokkok bővítményei csak a blockstudio.attributes elemet olvassák. Egy üres Blockstudio blokk kezelése is megtörténik, és az eredmény [], nem pedig null.

Az ellenőrzés kifejezetten meghívandó, és csak olvasásra szolgál. Nem jelenít meg sablonokat, nem módosít értékeket, nem ment bejegyzéseket, nem kérdez le médiatartalmakat, és nem futtat feltöltési visszahívásokat. Nem fut le automatikusan mentés, oldalszinkronizálás vagy megjelenítés közben. Nem tisztítófüggvény, nem jogosultság-ellenőrzés, és nem ellenőrzi, hogy létezik-e a csatolmány.

Minden megállapítás a következő stabil kulcsokat tartalmazza:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

Az eszközökben a code értéket használja, ne a lefordított message értéket. A source a block vagy a extension. Az útvonalak tárolási kulcsokat és nullától kezdődő ismétlőmező-sor- vagy kiválasztási indexeket használnak, kezdő perjel nélkül. A kulcsban szereplő szó szerinti ~ és / jelek escape-elt formája ~0 és ~1. A legfelső szintű csoport előtagot ad a gyermekeihez (cta_title); a névtelen csoportok és fülek nem adnak hozzá szintet. Az azonosítóval rendelkező, másik csoporton vagy ismétlőmezőn belüli csoportokat az építő nem támogatja, ezért a kulcsaikat nem fogadja el. Az üzenetmezőknek nincs tárolt értékük. A fájlmezőhöz tartozhat a <id>__size kiegészítő mező. Egy Blockstudio blokk gyökerénél a nyilvántartási kulcsok és a megjelenített elemnek továbbított globális HTML attribútumok nem számítanak ismeretlen mezőnek. Ez nem teszi lehetővé tetszőleges kulcsok használatát az ismétlőmező soraiban vagy az alapblokkok bővítését.

Kód Jelentés expected
unknown_field Egyetlen megtartott mező sem deklarálja ezt a tárolási kulcsot. Ismert tárolási kulcsok.
unknown_option A kiválasztás nem szerepel az ismert lehetőségek között. Engedélyezett értékek.
wrong_type A tárolt alak nem támogatott ennél a mezőnél. Elvárt tárolási család vagy típus.
too_few_rows, too_many_rows Egy meglévő ismétlőmező kívül esik a min vagy max értékein. A sorra vonatkozó korlát.
definition_conflict Egy kulcs alkalmazható definíciói eltérő tárolási alakokat követelnek meg. Az egyes definíciók forrása és mezőtípusa.
shadowed_value Egy beágyazott érték felülír egy eltérő legfelső szintű mezőértéket. A győztes beágyazott érték.
extension_top_level A sablon be tud olvasni egy legfelső szintű értéket, de a bővítménykötések nem. A szükséges útvonal itt: blockstudio/attributes.
unknown_attribute Egy Blockstudio blokk legfelső szintű kulcsát a megjelenítési útvonal nem olvassa be, ezért eldobja. Regisztrált attribútumnevek, bővítménymezők és blockstudio.
missing_container A attributes, disabled, name vagy editor legfelső szinten van tárolva, és hiányzik a blockstudio. A szükséges útvonal itt: blockstudio.
invalid_container A blockstudio vagy a blockstudio.attributes nem objektum. object.

Egy unknown_field találat üzenete a legközelebbi, azonos szintű tárolási kulcsot nevezi meg, ha legfeljebb három szerkesztési műveletre van tőle; ezt a szabályt használja az ismeretlen beállításokhoz: This storage key is not declared by the block or its extensions. Did you mean "title"? A expected továbbra is az összes ismert kulcsot felsorolja. Az egyezés nem veszi figyelembe a kis- és nagybetűket, és csak az adott tároló tárolási kulcsait vizsgálja. Az üzenetek le vannak fordítva; az integrációk az üzenet szövegének elemzése helyett a code, path és expected elemeket használják.

Egy Blockstudio blokk legfelső szintű kulcsa, amely nem regisztrált attribútum (saját mezői, valamint a WordPress által a supports, lock és metadata számára hozzáadott attribútumok), nem egy illeszkedő bővítmény mezője, nem blockstudio, és nem nyilvántartási kulcs vagy továbbított HTML attribútum, a sablon futása előtt eldobásra kerül. Egy ilyen kulcs — például egy elgépelt mezőazonosító vagy egy értékek objektum, amelyet a blockstudio burkoló nélkül tároltak — jelzést eredményez, mert a blokk az adott érték nélkül jelenik meg. Az olyan blokkok legfelső szintű kulcsait nem ellenőrzi, amelyek csak bővítménymezőket tartalmaznak.

Az elfogadott alakok a megjelenítést követik: a többszörös választók és jelölőnégyzetek listát, egyetlen opciós objektumot vagy importált skalárértéket is tartalmazhatnak, beleértve a numerikus nullát. Számok esetén a numerikus karakterláncok is elfogadottak. A fájlok mellékletazonosítókat, azonosítókat tartalmazó objektumokat, listákat vagy karakterlánc-hivatkozásokat tartalmazhatnak. A hivatkozás- és ikonértékeknek objektumoknak kell lenniük; az egyéni mezőtípusok a regisztrált attribútumtípusukat használják. Egy attributes mező párok listáját tartalmazza, amelyben a attribute neve nem üres, a value pedig skalár; a választható metaadatok, például a data.media megmaradnak.

A WordPress megjelenítés előtt érvényesíti a regisztrált legfelső szintű attribútumokat, ezért elutasíthat egy olyan alakot, amelyet a blockstudio.attributes beágyazott formában elfogad. Például egy "a" rádiógomb értéke működik a beágyazott objektumban, de a legfelső szinten eldobásra kerül, ahol a regisztrált típusa object. Az ilyen érték wrong_type eredményez. Használja a beágyazott objektumot azzal a tárolási alakkal, amelyet a szerkesztő ír.

A hiányzó mezők nem kötelezőek. Az üres beágyazott értékek (null, false, '', []) és a letiltott mezők nem okoznak értékhibát. A kifejezetten üres ismétlőmezőt továbbra is ellenőrzi a min alapján; a hiányzó vagy letiltott ismétlőmezőt nem. A legfelső szintű üres értéket jelenti, ha a WordPress eldobja, és egy nem üres alapértelmezett értéket állít vissza. Ugyanez az érték a beágyazott objektumban törölheti azt. A definíciók közötti ütközéseket akkor is jelzi, ha a kulcshoz nincs mentett érték.

A statikus beállításokat és a regisztráláskor már feloldott feltöltési beállításokat anélkül ellenőrzi, hogy újra meghívná a feltöltést. A távoli fetch beállításokat és a {attributes.*} értéket tartalmazó feltöltési argumentumokat kihagyja. A szín- és színátmenet-értékek egyediek lehetnek, kivéve, ha be van állítva a disableCustomColors vagy a disableCustomGradients. Ez a tárolt értékeket ellenőrzi, nem a default, a fallback vagy a szerkesztő érvényesítési szabályait.

Az illeszkedő bővítménymezők minden általuk célzott blokkban szerepelnek. A blokkon vagy annak gyökérszintű bővítményein belül a későbbi definíciók érvényesülnek, a megjelenítéshez hasonlóan. Egy blokk saját mezője és egy bővítménymező ugyanazon kulcs külön definíciói maradnak, és mindkettő érvényesül. Az ismétlőmező soraiban a megjelenítő minden forrásban az első, egyező azonosítójú mezőt olvassa be, így annak beállításai és korlátai érvényesek. Az ütközések diagnosztizálásához az ismétlődő definíciók is megmaradnak: az inkompatibilis tárolási alakok definition_conflict eredményeznek, még akkor is, ha a megjelenítéskor egy későbbi ismétlődő definíció nem kerül beolvasásra.

A függvény egyetlen blokkot ellenőriz. Dokumentum ellenőrzésekor járja be a innerBlocks tartalmát; a szinkronizált minták és más hivatkozások nem kerülnek automatikusan kibontásra. A wp bs blocks validate parancs egy vagy több bejegyzés blokkjait járja be, és jelenti a blokkjaik útvonalát.

Az egyedi megjelenítéskori feloldóval rendelkező webhelyek a tárolt adatok módosítása nélkül alakíthatják át a jelzéseket:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Mindig a jelzések listáját adja vissza; a [] visszaadása elfogadja a blokkot. Ez a szűrő csak a kezelt blokkokra fut le, a null eredményére soha.

A tárolt értékek leírása

A blokk regisztrálása után (init vagy újabb verziótól) a bs_block_schema() segítségével írja le a blokk által tárolt értékeket, például blokkjelölés generálásához egy eszközben vagy egy MI-integrációban, illetve a bemenet ellenőrzéséhez egy REST útvonalon:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

Az eredmény egy JSON séma a attrs.blockstudio.attributes helyen mentett objektumról. A blokk mezőit és az illeszkedő bővítmények mezőit fedi le, az ellenőrzés által használt tárolási kulcsokkal: egy legfelső szintű csoport előtagot ad a gyermekeinek, a névtelen csoportok és lapok nem adnak hozzá szintet, a fájlmező pedig hozzáadja a hozzá tartozó <id>__size mezőt. Az ismétlők sorobjektumok listái, amelyek a min és max alapján tartalmazzák a minItems és maxItems értékeket. A additionalProperties a mezőtárolás gyökerében és az ismétlősorokban is false. Az olyan objektumértékű mezők, mint a hivatkozások és az egyéni objektumok, saját metaadatokat tartalmazhatnak. A mezők nélküli blokknak nincs properties értéke, ezért csak az üres objektum illeszkedik.

Minden mező kanonikus formában van leírva, amelyet a bs_validate_block() elfogad:

Mező Séma
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Karakterlánc.
number, range Szám, a min és max szerinti minimum és maximum értékekkel.
toggle Logikai érték.
select, radio, checkbox Opcióérték, illetve az checkbox és multiple esetén opcióértékek listája, enum értékkel.
color, gradient Karakterlánc, disableCustomColors vagy disableCustomGradients beállításakor enum értékkel.
token Karakterláncok listája.
files Nem negatív egész számú mellékletazonosító, vagy azonosítók listája multiple értékkel.
link Objektum url, title és opensInNewTab értékkel; a url kötelező.
icon Objektum set, subSet és icon értékkel; a set és icon kötelező.
attributes Objektumok listája, nem üres attribute értékkel és skalár value értékkel.
repeater Sorobjektumok listája.
Egyéni mezőtípusok A regisztrált attribútumtípusuk.

A enum felsorolja az ellenőrzés által vizsgált opciókat: a statikus opciókat és a regisztrációkor már feloldott feltöltési opciókat. A távoli fetch opcióknak és a {attributes.*} értéket tartalmazó feltöltési argumentumoknak nincs enum értékük. A különböző tárolási alakú definíciókkal rendelkező kulcsok kimaradnak, mert az ellenőrzés az alatta tárolt összes értékről jelentést készít. Ha egy blokkmező és egy bővítménymező ugyanazt a kulcsot használja, a enum felsorolja a mindkettő által elfogadott értékeket. A közös ismétlők egyesítik a gyermekmezőiket, és mindkét definíció szigorúbb sorhatárait alkalmazzák. Az ismétlősorokon belül minden forrásban az első, egyező azonosítójú mező érvényesül, ahogy rendereléskor is. A kifejezetten <id>__size névre keresztelt mező elsőbbséget élvez az automatikusan hozzáadott fájlméret-kiegészítővel szemben.

Ha egy zárt mezőhöz nem áll rendelkezésre választható érték, vagy két alkalmazandó opciókészletnek nincs közös eleme, az egyetlen választás kanonikus értéke null, több választás esetén pedig egy üres lista. Az üres opciólista nem teszi korlátlanná a mezőt. A távoli és attribútumfüggő választási lehetőségek továbbra is nyitottak.

Egy mező label értéke title lesz, a help értéke description lesz, a default pedig annotációként megmarad. A séma saját title értéke a blokk címe. A mezők soha nem kötelezők, és a feltételes logika nem része a sémának.

A korlátozások csak olyan kulcsszavakat használnak, amelyeket a rest_validate_value_from_schema() ellenőriz, így a séma változtatás nélkül használható egy REST útvonal vagy képesség bemeneti sémájaként:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

A séma mezőnként egy űrlapot ír le; az érvényesítés importált alakzatokat, például opcióobjektumokat, numerikus karakterláncokat és ID-objektumokat is elfogad. Nem helyettesíti a bs_validate_block()-t: a definíciók ütközései konfigurációs problémák, és akkor is eredményezhetnek megállapításokat, ha az ütköző kulcs kimarad. Az érvényesítési szűrők webhelyspecifikus szabályokat is előírhatnak. A tárolt tartalom ellenőrzéséhez használja a bs_validate_block()-t. Az egyéni rendereléskori feloldót használó webhelyek a sémát a blockstudio/blocks/attributes/schema szűrővel módosíthatják.

PHP függvények

Adatok nélkül

A legegyszerűbb formájában a függvény egyetlen értéket fogad el: a lapon renderelendő blokk azonosítóját.

PHP
bs_render_block('blockstudio/cta');

Adatokkal

Ha egy blokkot egyéni adatokkal szeretne renderelni, az első paraméter egyetlen értéke helyett tömböt kell megadni. Az adatkulcs értéke a blokk sablonjában a $attributes és a $a változóba kerül.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

Beágyazás

A blokkok egymásba ágyazhatók a bs_block függvény és a blokksablonokban használt hatékony $content változó együttes használatával.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

A gombblokk a blokksablonban a $content változó helyére renderelődik.

A bs_render_block() vagy bs_block() segítségével renderelt beágyazott blokkok mindig az előtérben feloldott HTML elemet adják vissza, akkor is, ha a szülőblokk éppen szerkesztői előnézetet renderel. A sablonok olyan álkomponensei, mint a <RichText /> és a <InnerBlocks />, a beágyazott blokk visszaadása előtt feloldódnak.

Több tartalomhely

Több tartalomhely is létrehozható: a $content változót asszociatív tömbbé kell alakítani, majd a bs_block függvényben a megfelelő kulcsokat kell meghívni.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Blokktagek

Bármely blokk beágyazható a HTML tagek szintaxisával. Két formátum támogatott:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

Mindkettő ugyanazt a blokkot rendereli. A <bs:> szintaxis a kötőjelet névtér-elválasztóvá alakítja (a acme-hero ebből acme/hero lesz). A kötőjeleket balról jobbra próbálja, és az első regisztrált jelölt nyer, így a kötőjelet tartalmazó névterek is feloldódnak: a <bs:acme-ui-button> először a acme/ui-button elemet, majd a acme-ui/button elemet próbálja. A <block> szintaxis a teljes blokknevet name attribútumként veszi át.

A Blockstudio blokkok és a WordPress alapvető WordPress blokkjai is használhatók. A Blockstudio blokkok a teljes feldolgozási folyamaton keresztül renderelődnek (sablonok, Tailwind, eszközök). Az alapblokkok a WordPress blokkrenderelő rendszerén keresztül renderelődnek, a beépített blokk-renderelőkkel.

Működés

A blokkcímkék attól függően működnek másképp, hogy hol jelennek meg:

Blokksablonokban és bejegyzéstartalomban a címkék futásidőben renderelt HTML elemekké alakulnak. A kimenet a hivatkozott blokk végleges jelölése, közvetlenül a lapba ágyazva. Ezekhez nem tartozik WordPress blokk a szerkesztőben. Pusztán renderelési mechanizmusként szolgálnak.

Oldalakban, mintákban és webhely-sablonokban a címkék natív WordPress blokkokká alakulnak, mielőtt a fájlforrás szinkronizálódik vagy regisztrálódik a WordPress rendszerben. Így a blokkok megjelennek a szerkesztőben, szerkeszthetők, ha a cél támogatja a szerkesztést, és végigmennek a WordPress teljes blokk-életciklusán. A címkeszintaxis rövidített módja a blokktartalom sablonfájlokban való megadásának.

Ez a különbség fontos: a sablonokban lévő blokkcímkék kimenetet hoznak létre, az oldalakon, mintákban és webhely-sablonokban lévők pedig natív blokkokat.

Blokksablonokban

A blokkcímkék automatikusan renderelődnek a Twig és PHP sablonokon belül. Nincs szükség beállításra. Ez a <bs:> és <block> szintaxisra, valamint minden regisztrált előtag és álnévcímkére is érvényes, így a sablon közvetlenül kiadhatja ezeket a bs_render_block() meghívása helyett. A kimenet renderelt HTML, közvetlenül a blokk sablonjának kimenetébe ágyazva:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

Bejegyzéstartalomban

Az oldalszintű renderelés (bejegyzéstartalom, widgetterületek) külön bekapcsolandó:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Vagy szűrőn keresztül:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Szintaxis

Önlezáró címkék:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Páros címkék belső tartalommal:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

Szabadon kombinálhatja a formákat. Mindkét szintaxis egymásba ágyazható:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Előtag-rövidítések

A blokkcímkék projektspecifikus előtag-rövidítésekkel is használhatók. Regisztráljon egy előtagot egy vagy több névtérrel, és a Blockstudio az előtagot <prefix-slug> sorrendben az első regisztrált blokkra oldja fel:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

A fenti példában a <theme-card> a theme-components/card elemre oldódik fel, a <theme-button> pedig a bsui/button elemre vált vissza, ha a theme-components/button nincs regisztrálva, a <theme-ui-feature-matrix> pedig a theme-components/ui-feature-matrix elemre oldódik fel.

Az előtagok egymásba is fűzhetők. Ha egy előtagos címke nem oldható fel közvetlenül, és a hátralévő slug maga is regisztrált előtagcímke, a feloldás rekurzívan folytatódik, így egy márkaelőtag egy névtérelőtagra épülhet:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

A <theme-ui-input> nem rendelkezik theme-components/ui-input blokkal, ezért továbblép a ui előtagra, és feloldja a bsui/input elemet. A közvetlen találatok mindig elsőbbséget élveznek a beágyazott feloldással szemben, az engedélyezési és tiltási szabályok pedig a végső feloldott blokkra vonatkoznak.

Az előtagokat a blockstudio.json fájlban is beállíthatja:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Az előtagok csak kisbetűket és számokat tartalmazhatnak, betűvel kell kezdődniük, és nem tartalmazhatnak kötőjelet. A blockstudio/block_tags/tag_aliases explicit álnevei elsőbbséget élveznek az előtagok feloldásával szemben. Az ismeretlen előtagos címkék változatlanul maradnak.

Az előtag- és álnévcímkék továbbra is kényelmes szerkesztési megoldásként használhatók. A kanonikus, hordozható írásmód mindig a <bs:namespace-slug>, mert a tényleges blokknevet rögzíti a projekt szűrőitől függetlenül:

HTML
<bs:theme-components-card />
<bs:bsui-input />

A Blockstudio példák, a generált diagnosztikai üzenetek és a programozott kimenet ezt a kanonikus írásmódot használják. A régebbi rövidítést elhagyni kívánó projektek az önálló, először próbaüzemmódban futtatható kanonikus címkemigrációt használhatják a WordPress elindítása nélkül.

Alapblokkok

Bármely regisztrált renderelővel rendelkező blokk használható:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Vagy a <block> szintaxisával:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

Engedélyezési és tiltólisták

Szabályozza, mely blokkok renderelhetők címkékkel:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

A allow csak a mintának megfelelő elemeket engedélyezi. A deny kizárja az egyező mintákat, és elsőbbséget élvez. Mindkettő támogatja a * helyettesítő karaktereket a fnmatch() használatával. Ezek mindkét szintaxisra, valamint a sablon- és oldalszintű renderelésre is érvényesek.

Szűrők: blockstudio/block_tags/allow és blockstudio/block_tags/deny.

HTML továbbadás

A data- előtagú attribútumok továbbkerülnek a renderelt blokk gyökérelemére. A html- előtagú attribútumok szintén továbbkerülnek, az előtag eltávolításával. Mindkét szintaxissal működik. A továbbadott attribútum felülírja a gyökérelem meglévő értékét, nem pedig összeolvad vele, így a html-class lecseréli a blokk saját osztályait.

Egy Blockstudio blokk a gyökérelemére teszi azokat a globális attribútumokat is, amelyeket nem deklarál mezőként: id, style, role, title, lang, dir, hidden, tabindex és minden aria-* attribútum. A deklarált mező mindig elsőbbséget élvez, így a title mezővel rendelkező blokk ehelyett a $a['title'] értékét kapja. A továbbadott stílusok a safecss_filter_attr() feldolgozáson mennek át, a WordPress szűrő a bejegyzéstartalom stílusattribútumaira érvényes, és a sablonban már beállított stílushoz fűződnek.

Az attribútumértékek HTML értékek, ezért a tagek feldolgozásakor az entitások egyszer dekódolódnak: a title="Tom &amp; Jerry" a sablonba Tom & Jerry formában kerül, majd a kimenetben újra escape-elődik. Az idézőjelek közé tett értékek tartalmazhatnak > elemet, ahogy a Tailwind változatok és animációs szelektorok esetén is; ez önlezáró és páros címkéknél egyaránt működik.

Minden más, a blokk által nem deklarált attribútum, beleértve a class elemet is, nem jut el a HTML elemhez. Ha a WP_DEBUG be van kapcsolva, a Blockstudio kérésenként egyszer jelenti az ilyen attribútumokat a _doing_it_wrong() segítségével. Deklaráljon hozzá mezőt, vagy adja meg data-, aria- vagy html- attribútumként.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Egyéni renderelők

Regisztráljon egyéni blokk-renderelőket további blokktípusokhoz. A renderelők attribútumtömböt és belsőtartalom-karakterláncot fogadnak, és WordPress blokk-tömböt adnak vissza:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

Az olyan tárolóblokkoknál, amelyeknek a belső tartalmát gyermekblokkokra kell bontaniuk, adjon hozzá egy második bejegyzést ugyanahhoz a szűrőhöz:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

A blockstudio/block_tags/builders a blokkcímkékre és a blockstudio/parser/element_mapping segítségével kiválasztott egyéni blokkokra is érvényes. Ez a megfelelő hook, ha egy elemhez rendelt projektblokknak a belső szövegét Blockstudio mezőbe kell helyeznie, vagy egyéni blokk-tömböt kell létrehoznia.

A blockstudio/block_tags/renderers és a blockstudio/parser/renderers ugyanazt a regisztert és visszahívási formát kapja. Kompatibilitási okokból és végső, parser szintű felülbíráláshoz továbbra is rendelkezésre állnak. A szűrők ebben a sorrendben futnak:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

Egy későbbi szűrő lecserélheti egy korábbi szűrő által regisztrált renderelőt.

Programozott használat

Alkalmazza a címkerenderelést bármely, PHP által kapott karakterláncra:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

Komponensek

A blokkcímkék jól használhatók a Komponensekkel. A komponensek olyan blokkok, amelyek csak programozottan renderelődnek, és soha nem jelennek meg a szerkesztőben.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Parser

A blokkcímkéket egy könnyű karakterlánc-elemző dolgozza fel a DOMDocument helyett. A parser kezeli a <bs:> és <block> szintaxist, a mélység követésével kezeli az azonos nevű, egymásba ágyazott címkéket, az idézőjelezett attribútumértékeket és a rekurzív tárolóblokkokat. Kifejezetten erre az esetre készült, a DOMDocumentnél és a WordPress WP_HTML_Tag_Processor eleménél is gyorsabb a teljesítménytesztek szerint, továbbá elkerüli a DOMDocument ismert problémáit a névtérelőtagok eltávolításával és az attribútumok kisbetűssé alakításával.

Az Oldalak, minták és webhely-sablonok esetében ugyanez a parser a nyers HTML elemeket is kezeli (<p>, <div>, <h1> stb.), és a megfelelő alapvető WordPress blokkokhoz rendeli őket.

Ha egy elemtérkép a <p> elemet egy regisztrált, nem alapvető Blockstudio blokkhoz rendeli, amely content richtext attribútumot deklarál, a belső HTML automatikusan ebbe a content attribútumba kerül, beleértve az olyan beágyazott címkéket is, mint a code és a img, ha ezek blokk szinten elemtérképpel vannak megadva. Az a bekezdés, amelynek egyetlen gyermeke egy kép, azzá a blokkká válik, amelyhez a <img> van rendelve. A beágyazott blokkcímkék vagy blokk szintű HTML elemek továbbra is a szokásos belsőblokk-elemzésre esnek vissza. A <block name="core/shortcode"> rövidkód-szövegét a blokk tartalmaként őrzi meg.