Siirry sisältöön

Ohjelmallinen renderöinti

Koska Gutenberg on noussut keskeiseksi välineeksi helposti muokattavien asiakassivustojen luomisessa, kaikki tarvittavat verkkosivuston osat kannattaa rakentaa lohkoina. Tämä sopii useimpiin tarpeisiin, mutta edistyneet käyttäjät ja erityistapaukset saattavat vaatia lohkojen käyttöä editorin ulkopuolella.

Blockstudio tarjoaa kaksi tapaa renderöidä lohkoja ohjelmallisesti:

  • PHP-funktiot: bs_render_block ja bs_block renderöintiin koodista PHP
  • HTML-tagit: <bs:block-name>-tagit, jotka korvataan lohkon tulosteella missä tahansa sivulla

Kaikki ominaisuudelle Blockstudio tyypilliset ominaisuudet, kuten upotetut tyylit, skriptit ja rajatut tyylit, ovat tuettuja.

Saarekkeet toimivat myös näiden renderöintipolkujen kautta. Dynaaminen saareke, joka renderöidään toiminnolla bs_render_block(), ominaisuudella bs_block() tai lohkotagilla, palauttaa saman paikkamerkkimerkin kuin julkaisun sisällöstä renderöity lohko. Julkisen sivun suoritusympäristö lisätään, kun merkki esiintyy vastauksessa.

Rakenteiset koostumukset ja täydelliset dokumentit

Pitkäikäisissä työkaluissa, esikatseluissa, vienneissä ja komponenttigallerioissa kannattaa käyttää versioitua Blockstudio\Render API -toimintoa. Se hyväksyy yhden määrityksen tai järjestetyn luettelon ja renderöi tulostamatta sitä:

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'],
]);

Normitetussa vakiomäärityksessä on neljä avainta:

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

data, inner, innerBlocks, root, layers ja example ovat syötteen apukeinoja, jotka poistetaan normalisoinnissa. Sisäkkäiset määritykset renderöidään rekursiivisesti saman Blockstudio-prosessin kautta.

Render::document() palauttaa arvot schemaVersion, html, body, blocks, assets, warnings ja errors. Arvo assets erottaa toisistaan head, footer, styles, scripts, modules, interactivity, ui ja tailwind. Lohkoluettelo ja resurssit sisältävät valittujen mallien käyttämät riippuvuudet, mutta eivät niihin liittymättömiä tai vain editorissa käytettäviä resursseja.

Täydellisissä dokumenteissa voi asettaa arvot bodyClasses/bodyAttributes ja halutessaan kääriä renderöidyn rungon arvoilla contentElement, contentClasses ja contentAttributes. Kääreessä voi käyttää vain turvallista elementin nimeä; palautettu body sisältää edelleen käärimättömän renderöidyn sisällön. Valinnat head ja footer lisäävät luotettua dokumenttimerkintää omiin kohtiin, ja lisäykset sisältyvät palautettavaan resurssikokonaisuuteen.

Jos haluat koota jo renderöidyn dokumentin ympärille HTML, anna sen tunnetut juurilohkojen nimet:

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

Käytä Render::content() sarjallistettuun WordPress lohkosisältöön. Useita erillisiä dokumentteja yhdessä pyynnössä renderöivien kuluttajien tulee kutsua Blockstudio\Batch_Render::reset() niiden välissä; Canvas::documents() tekee tämän automaattisesti.

Sivun ulkopuolinen renderöinti

Blockstudio lisää <!--blockstudio/namespace/slug-->-kommentin jokaisen renderöimänsä lohkon eteen. Käyttöliittymän sivulla puskuri lukee nämä kommentit nähdäkseen, mitä lohkoja sivulla on, lataa niiden resurssit ja poistaa kommentit ennen vastauksen lähettämistä.

Tulosteessa, joka ei kulje kyseisen puskurin kautta, kommentit säilyvät. Tämä koskee REST-vastauksia, syötteitä, AJAX-käsittelijöitä sekä HTML, jotka tallennetaan tai lähetetään muualle do_blocks()-, Render::content()– tai bs_render_block()-käsittelyn jälkeen. Poista ne käyttämällä bs_strip_render_markers():

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

Funktio poistaa rekisteröityjen Blockstudio-lohkojen kommentit ja jättää kaiken muun ennalleen, mukaan lukien muut HTML-kommentit. Se tunnistaa samat merkit, jotka sivun puskuri poistaa. Kutsu sitä lohkojen rekisteröinnin jälkeen (init tai myöhemmin).

Älä poista merkintöjä, jotka tulostetaan edelleen puskuroidulle käyttöliittymän sivulle. Sivu tarvitsee kommentit tietääkseen, mitkä lohkojen resurssit ladataan, ja Blockstudio poistaa ne itse lopuksi.

Kommenttien poistaminen ei lisää resursseja. Lohkojen CSS- ja JavaScript-tiedostot lisätään vain sivupuskurissa. Käytä bs_block_assets()– tai Render::document()-tiedostoa, jos myös niiden kuluttaja tarvitsee kyseiset resurssit.

Lohkojen tarkastelu

Käytä bs_block_fields() lohkojen rekisteröinnin jälkeen (init tai myöhemmin), kun haluat saada ratkaistut kenttämääritykset lukematta sisäisiä rekistereitä:

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

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

Palautusarvo on rekisteröity kenttämääritysten taulukko, joka sisältää määritesuodattimet, laajennetut mukautetut kentät, ohitukset sekä sisäkkäiset ryhmät, välilehdet ja toistimet. Blockstudio-lohko, jolla ei ole kenttiä, palauttaa arvon []. Tulos on kopio: sen muuttaminen ei muuta rekisteröityä lohkoa.

Nämä ovat määritelmiä, eivät tallennettuja arvoja. Tallennetun merkkauskielen validointiin käytä bs_validate_block() sen sijaan, että ylläpitäisit erillistä kenttien läpikäyntiä. Kuvaa lohkon hyväksymät arvot käyttämällä bs_block_schema(). WordPress-omisteiset attribuutit pysyvät erillisinä.

laajennusten lisäämät kentät eivät kuulu kohteeseen bs_block_fields(). Hae ne komennolla bs_block_extension_fields(). Se etsii laajennukset lohkon nimen perusteella, joten se toimii myös ydinlohkojen ja kolmannen osapuolen lohkojen kanssa:

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

Palautusarvo luettelee kaikkien vastaavien laajennusten kenttämääritykset siinä järjestyksessä, jossa laajennukset rekisteröitiin, ja sen rakenne vastaa kohdetta bs_block_fields(). Jos mikään laajennus ei vastaa lohkoa, palautetaan []. Laajennusten arvot tallennetaan samaan attrs.blockstudio.attributes-objektiin kuin lohkon omat kenttäarvot, joten kaikilla tunnisteilla on sama nimiavaruus. Jos kaksi laajennusta määrittää saman tunnisteen, molemmat määritykset palautetaan ja ne muokkaavat samaa arvoa; renderöinnissä myöhemmin rekisteröidyn laajennuksen määritys tulee voimaan.

Voit lukea tallennetun lohkon arvot sellaisina kuin sen malli ne vastaanottaa komennolla bs_block_values().

Käytä komentoa bs_block_assets() lohkon löydettyjen CSS- ja JavaScript-tietojen tarkasteluun. Jos tarvitset täydellisen esikatseluasiakirjan, jossa ovat mukana myös sisäkkäiset lohkot ja jaetut ajonaikaiset riippuvuudet, käytä edellä kuvattua komentoa Render::document().

Tallennettujen arvojen tarkistaminen

Tarkista ohjelmallisesti luodut tai tuodut lohkomääritteet komennolla bs_validate_block() lohkojen rekisteröinnin jälkeen (init tai myöhemmin) ennen niiden tallentamista:

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

Anna koko attrs-taulukko, älä pelkästään blockstudio.attributes-arvoa. Blockstudio-renderöinti hyväksyy ilmoitetut kentät myös ylimmällä tasolla, ja sisäkkäiset arvot ovat etusijalla, jos molemmat annetaan. Ydinlohkojen ja kolmannen osapuolen lohkojen laajennukset lukevat vain arvon blockstudio.attributes. Tyhjä Blockstudio-lohko on hallittu lohko, ja se palauttaa arvon [], ei arvoa null.

Tarkistus on erikseen käynnistettävä ja vain lukeva. Se ei renderöi malleja, muuta arvoja, tallenna artikkeleita, hae mediaa eikä suorita täydennyskutsuja. Se ei käynnisty automaattisesti tallennuksen, sivun synkronoinnin tai renderöinnin yhteydessä. Se ei ole puhdistin, valtuutustarkistus eikä tarkistus siitä, onko liite olemassa.

Jokainen löydös sisältää seuraavat vakaat avaimet:

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

Käytä työkalussa code, älä käännettyä muotoa message. source on block tai extension. Poluissa käytetään tallennusavaimia ja toistinkentän rivien tai valintojen nollapohjaisia indeksejä ilman alussa olevaa vinoviivaa. Avaimen kirjaimelliset merkit ~ ja / merkitään muodossa ~0 ja ~1. Ylimmän tason ryhmä lisää etuliitteen lapsilleen (cta_title); anonyymit ryhmät ja välilehdet eivät lisää tasoa. Rakentaja ei tue ryhmiä, joilla on tunnus toisen ryhmän sisällä tai toistinkentässä, joten niiden avaimia ei hyväksytä. Viestikentillä ei ole tallennettua arvoa. Tiedostokentässä sallitaan sen kumppanikenttä <id>__size. Blockstudio-lohkon juuressa kirjanpitoavaimet ja globaalit HTML-määritteet, jotka välitetään renderöidylle elementille, eivät ole tuntemattomia kenttiä. Tämä ei salli mielivaltaisia avaimia toistinkentän riveillä tai ydinlohkojen laajennuksia.

Koodi Merkitys expected
unknown_field Mikään säilytetty kenttä ei määritä tätä tallennusavainta. Tunnetut tallennusavaimet.
unknown_option Valinta ei kuulu tunnettuihin vaihtoehtoihin. Sallitut vaihtoehtoarvot.
wrong_type Tallennettu muoto ei ole kentän tukema. Odotettu tallennusperhe tai tyyppi.
too_few_rows, too_many_rows Toistinkentän arvo ylittää min– tai max-rajan. Riviraja.
definition_conflict Samaan avaimeen sovellettavat määritykset edellyttävät eri tallennusmuotoja. Kunkin määrityksen lähde ja kenttätyyppi.
shadowed_value Sisäkkäinen arvo korvaa ylimmän tason kentän eri arvolla. Voittava sisäkkäinen arvo.
extension_top_level Malli voi lukea ylimmän tason arvon, mutta laajennussidonnat eivät. Sen vaadittu polku kohdassa blockstudio/attributes.
unknown_attribute Blockstudio-lohkon ylimmän tason avainta ei lueta renderöintipolussa, ja se hylätään. Rekisteröidyt määritteen nimet, laajennuskentät ja blockstudio.
missing_container attributes, disabled, name tai editor on tallennettu ylimmälle tasolle, ja blockstudio puuttuu. Sen vaadittu polku kohdassa blockstudio.
invalid_container blockstudio tai blockstudio.attributes ei ole objekti. object.

unknown_field-löydöksen viesti nimeää lähimmän tallennusavaimen samalla tasolla, jos se on enintään kolmen muokkauksen päässä. Tätä etäisyyttä tuntemattomien asetusten sääntö käyttää: This storage key is not declared by the block or its extensions. Did you mean "title"? expected luettelee silti kaikki tunnetut avaimet. Vastaavuuden tarkistus ei huomioi kirjainkokoa ja ottaa huomioon vain kyseisen säilön tallennusavaimet. Viestit on käännetty; integraatioiden tulee viestitekstin jäsentämisen sijaan käyttää arvoja code, path ja expected.

Blockstudio-lohkon ylimmän tason avain, joka ei ole rekisteröity määrite (sen kentät tai määritteet, jotka WordPress lisää kohteille supports, lock ja metadata), vastaavan laajennuksen kenttä, blockstudio, kirjanpitoavain tai välitetty HTML-määrite, hylätään ennen mallin suoritusta. Tällainen avain, kuten esimerkiksi kirjoitusvirheellinen kenttätunnus tai ilman blockstudio-käärettään tallennettu arvo-objekti, tuottaa havainnon, koska lohko renderöityy ilman kyseistä arvoa. Lohkoja, joissa on vain laajennuskenttiä, ei validoida ylimmän tason avainten osalta.

Hyväksytyt muodot vastaavat renderöintiä: usean valinnan kentät ja valintaruudut voivat sisältää luettelon, yhden vaihtoehto-objektin tai tuodun skalaariarvon, myös numeerisen nollan. Numeeriset merkkijonot hyväksytään numeroille. Tiedostot voivat sisältää liitetunnuksia, tunnusobjekteja, luetteloita tai merkkijonoviittauksia. Linkki- ja kuvakearvojen on oltava objekteja; mukautetuissa kenttätyypeissä käytetään niiden rekisteröityä määritetyyppiä. attributes-kenttä sisältää luettelon pareja, joista kunkin attribute-nimen on oltava epätyhjä ja value-arvon skalaari; valinnaiset metatiedot, kuten data.media, säilytetään.

WordPress validoi rekisteröidyt ylimmän tason määritteet ennen renderöintiä, joten se voi hylätä muodon, joka hyväksytään kohteen blockstudio.attributes sisällä. Esimerkiksi radiopainikkeen arvo "a" toimii sisäkkäisessä objektissa, mutta se hylätään ylimmällä tasolla, jossa sen rekisteröity tyyppi on object. Tällainen arvo tuottaa havainnon wrong_type. Käytä sisäkkäistä objektia saman tallennusmuodon välittämiseen, jonka editori kirjoittaa.

Puuttuvat kentät eivät ole pakollisia. Tyhjät sisäkkäiset arvot (null, false, '', []) ja käytöstä poistetut kentät eivät tuota arvoihin liittyviä virheitä. Nimenomainen tyhjä toistinkenttä tarkistetaan silti suhteessa rajaan min; puuttuvaa tai käytöstä poistettua toistinkenttää ei. Tyhjä ylimmän tason arvo ilmoitetaan, jos WordPress hylkää sen ja palauttaa sen sijaan epätyhjän oletusarvon. Sama arvo sisäkkäisessä objektissa voi tyhjentää arvon. Määritysten ristiriidat ilmoitetaan, vaikka avaimella ei olisi tallennettua arvoa.

Staattiset vaihtoehdot ja rekisteröinnin yhteydessä jo ratkaistut täydennettävät vaihtoehdot tarkistetaan kutsumatta täydennystä uudelleen. Etäpalvelusta haettavat fetch-vaihtoehdot ja {attributes.*}-arvoja sisältävät täydennysargumentit ohitetaan. Väri- ja liukuväriarvot voivat olla mukautettuja, ellei disableCustomColors tai disableCustomGradients ole asetettu. Tässä tarkistetaan tallennetut arvot, ei arvoja default, fallback eikä editorin validointisääntöjä.

Vastaavat laajennuskentät sisällytetään jokaiseen lohkoon, jota ne koskevat. Lohkon tai sen juuressa olevien laajennusten sisällä myöhemmät määritykset voittavat, kuten renderöinnissäkin. Lohkon oma kenttä ja laajennuskenttä ovat saman avaimen erillisiä määrityksiä, ja molempia sovelletaan. Toistinkentän riveillä renderöijä lukee kussakin lähteessä ensimmäisen kentän, jolla on vastaava tunnus, joten sen vaihtoehtoja ja rajoja sovelletaan. Kaksoismääritykset säilytetään ristiriitojen diagnosointia varten: yhteensopimattomat tallennusmuodot tuottavat havainnon definition_conflict, vaikka myöhempää kaksoismääritystä ei luettaisi renderöinnissä.

Funktio tarkistaa yhden lohkon. Käsittele innerBlocks käydessäsi asiakirjan läpi; synkronoituja kuvioita ja muita viittauksia ei laajenneta automaattisesti. Komento wp bs blocks validate käy yhden tai useamman artikkelin lohkot läpi ja ilmoittaa niiden lohkopolut.

Sivustot, joilla on mukautettu renderöintiaikainen ratkaisija, voivat muokata havaintoja muuttamatta tallennettuja tietoja:

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

Palauta aina havaintojen luettelo; arvon [] palauttaminen hyväksyy lohkon. Tämä suodatin toimii vain hallituissa lohkoissa, ei tuloksessa null.

Tallennettujen arvojen kuvaaminen

Kuvaa bs_block_schema()-toiminnolla lohkon tallentamat arvot rekisteröinnin jälkeen (init tai myöhemmin). Näin voit esimerkiksi luoda lohkomerkkauskieltä työkalussa tai tekoälyintegraatiossa tai tarkistaa syötteen REST-reitillä:

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

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

Tulos on objektin attrs.blockstudio.attributes-tallennuskohteeseen tallennetun sisällön JSON-skeema. Se kattaa lohkon kentät ja vastaavien laajennusten kentät sekä validoinnin käyttämät tallennusavaimet: ylimmän tason ryhmän etuliite lisätään sen lapsiin, nimettömät ryhmät ja välilehdet eivät lisää tasoa, ja tiedostokenttään lisätään sen <id>__size-liitännäinen. Toistimet ovat rivikohteiden luetteloita, joissa on minItems ja maxItems lähteistä min ja max. additionalProperties on false kenttätallennuksen juuressa ja toistinriveillä. Objektimuotoiset kentät, kuten linkit ja mukautetut objektit, voivat sisältää omat metatietonsa. Kentättömällä lohkolla ei ole properties-määritystä, joten vain tyhjä objekti vastaa sitä.

Kukin kenttä kuvataan kanonisessa muodossa, jonka bs_validate_block() hyväksyy:

Kenttä Skeema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Merkkijono.
number, range Numero, jossa ovat minimum ja maximum lähteistä min ja max.
toggle Totuusarvo.
select, radio, checkbox Vaihtoehdon arvo tai vaihtoehtoarvojen luettelo kohteille checkbox ja multiple, jossa on enum.
color, gradient Merkkijono, jossa on enum, kun disableCustomColors tai disableCustomGradients on asetettu.
token Merkkijonojen luettelo.
files Liitteen tunnus ei-negatiivisena kokonaislukuna tai tunnusten luettelo, jossa on multiple.
link Objekti, jossa ovat url, title ja opensInNewTab; url on pakollinen.
icon Objekti, jossa ovat set, subSet ja icon; set ja icon ovat pakollisia.
attributes Objektien luettelo, jossa on ei-tyhjä attribute ja skalaarinen value.
repeater Rivikohteiden luettelo.
Mukautetut kenttätyypit Niiden rekisteröity attribuuttityyppi.

enum luettelee validoinnissa tarkistettavat vaihtoehdot: staattiset vaihtoehdot ja rekisteröinnissä jo ratkaistut täyttöarvot. Etäpalvelun fetch-vaihtoehdoilla ja täyttöargumenteilla, jotka sisältävät {attributes.*}, ei ole arvoa enum. Avain, jolle on määritelty eri tallennusmuotoja, jätetään pois, koska validointi raportoi kaikki sen alle tallennetut arvot. Kun lohkon kentällä ja laajennuksen kentällä on sama avain, enum luettelee molempien hyväksymät arvot. Jaetut toistimet yhdistävät lapsikenttänsä ja soveltavat määritelmien tiukempia rivirajoja. Toistinriveillä käytetään kunkin lähteen ensimmäistä kenttää, jolla on vastaava tunnus, kuten renderöinnissäkin. Erityisesti nimetty kenttä <id>__size ohittaa automaattisesti lisättävän tiedostokokoisen liitännäiskentän.

Jos suljetulla kentällä ei ole saatavilla olevia vaihtoehtoja tai kahdella sovellettavalla vaihtoehtojoukolla ei ole yhteisiä arvoja, sen kanoninen arvo on null yksittäiselle valinnalle tai tyhjä luettelo monivalinnalle. Tyhjä vaihtoehtoluettelo ei tee kentästä rajoittamatonta. Etäpalvelun ja attribuuteista riippuvat vaihtoehdot pysyvät avoimina.

Kentän label muuttuu arvoksi title, sen help arvoksi description, ja sen default säilytetään annotaationa. Skeeman oma title on lohkon otsikko. Kentät eivät ole koskaan pakollisia, eikä skeema sisällä ehdollista logiikkaa.

Rajoitteissa käytetään vain avainsanoja, jotka rest_validate_value_from_schema() tarkistaa, joten skeema toimii sellaisenaan reitin tai kyvykkyyden syöteskeemana kohteessa REST:

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

Skeema kuvaa yhden kentän lomaketta kohden; validointi hyväksyy myös tuotuja muotoja, kuten asetusobjekteja, numeromerkkijonoja ja ID-objekteja. Se ei korvaa tunnistetta bs_validate_block(): määrittelyristiriidat ovat määritysongelmia ja voivat edelleen tuottaa havaintoja, vaikka ristiriitainen avain jätettäisiin pois. Validointisuodattimet voivat myös asettaa sivustokohtaisia sääntöjä. Tarkista tallennettu sisältö tunnisteella bs_validate_block(). Sivustot, joissa on mukautettu renderöintiaikainen ratkaisija, voivat mukauttaa skeemaa suodattimella blockstudio/blocks/attributes/schema.

PHP-funktiot

Ilman dataa

Yksinkertaisimmillaan funktio ottaa yhden arvon: sivulla renderöitävän lohkon tunnisteen.

PHP
bs_render_block('blockstudio/cta');

Datan kanssa

Jos lohko halutaan renderöidä mukautetulla datalla, ensimmäisen parametrin yksittäisen arvon tilalla on käytettävä taulukkoa. Data-avaimen arvo välitetään $attributes-muuttujalle lohkomallissa sekä $a-muuttujalle.

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

Sisäkkäiset lohkot

Lohkoja voi sisäkkäistää käyttämällä bs_block-funktiota yhdessä lohkomallien tehokkaan $content-muuttujan kanssa.

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',
    ]
  ])
]);

Painikelohko renderöidään lohkomallissa muuttujan $content tilalle.

bs_render_block()– tai bs_block()-merkinnällä renderöidyt upotetut lohkot tulostavat aina käyttöliittymään ratkaistun HTML-sisällön, myös silloin kun ylätason lohkosta renderöidään parhaillaan editorin esikatselua. Mallien valekomponentit, kuten <RichText /> ja <InnerBlocks />, ratkaistaan ennen upotetun lohkon palauttamista.

Useita sisältöpaikkoja

Voit luoda useita sisältöpaikkoja muuttamalla $content-muuttujan assosiatiiviseksi taulukoksi ja kutsumalla sen asianmukaisia avaimia bs_block-funktiossa.

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

Lohkotunnisteet

Upota mikä tahansa lohko käyttämällä HTML-tägisyntaksia. Tuetut muodot ovat:

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

Molemmat renderöivät saman lohkon. <bs:>-syntaksi muuttaa yhdysmerkin nimiavaruuden erottimeksi (acme-hero muuttuu muotoon acme/hero). Yhdysmerkkejä kokeillaan vasemmalta oikealle, ja ensimmäinen rekisteröity ehdokas valitaan, joten myös yhdysmerkkejä sisältävät nimiavaruudet ratkeavat: <bs:acme-ui-button> kokeilee ensin acme/ui-button-muotoa ja sitten acme-ui/button-muotoa. <block>-syntaksissa koko lohkon nimi annetaan name-määritteenä.

Sekä Blockstudio-lohkot että coren WordPress-lohkot toimivat. Blockstudio-lohkot renderöidään koko putken kautta (mallipohjat, Tailwind, resurssit). Core-lohkot renderöidään WordPressn lohkojen renderöintijärjestelmällä käyttäen sisäänrakennettuja lohkojen renderöijiä.

Näin se toimii

Lohkotägien toiminta riippuu siitä, missä ne esiintyvät:

Lohkomalleissa ja artikkelien sisällössä tägät korvataan renderöidyillä HTML-lohkoilla ajon aikana. Tuloste on viitatun lohkon lopullinen merkintäkieli, joka upotetaan suoraan sivulle. Näitä varten editoriin ei lisätä WordPress-lohkoa. Ne ovat pelkkä renderöintimekanismi.

Sivuissa, kuvioissa ja sivustomalleissa tägät muunnetaan natiiveiksi WordPress-lohkoiksi ennen kuin tiedoston lähde synkronoidaan tai rekisteröidään WordPressiin. Lohkot näkyvät editorissa, niitä voi muokata, jos kohde tukee muokkausta, ja ne käyvät läpi WordPressn koko lohkon elinkaaren. Tägisyntaksi on lyhennelmä lohkosisällön määrittämiseen mallitiedostoissa.

Tämä ero on tärkeä: malleissa lohkotägät tuottavat tulostetta, kun taas sivuissa, kuvioissa ja sivustomalleissa ne tuottavat natiiveja lohkoja.

Lohkomalleissa

Lohkotägät renderöidään automaattisesti Twig- ja PHP-malleissa. Asetuksia ei tarvita. Tämä koskee myös syntakseja <bs:> ja <block> sekä kaikkia rekisteröityjä etuliite– ja aliastägejä, joten malli voi tuottaa ne suoraan bs_render_block()-kutsun sijaan. Tuloste renderöidään HTML ja upotetaan suoraan lohkomallin tulosteeseen:

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>

Artikkelien sisällössä

Sivutason renderöinti (artikkelien sisältö ja vimpainten alueet) on otettava käyttöön erikseen:

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

Tai suodattimen kautta:

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

Syntaksi

Itsestään sulkeutuvat tägät:

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

Parilliset tägät, joiden sisällä on sisältöä:

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>

Yhdistele vapaasti. Kumpaakin syntaksia voi käyttää toistensa sisällä:

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>

Etuliitteiden lyhenteet

Lohkotägeissä voi käyttää myös projektille määritettyjä etuliitteitä. Rekisteröi etuliite yhdelle tai useammalle nimiavaruudelle, niin Blockstudio ratkaisee <prefix-slug>-tunnisteen ensimmäiseksi lohkoksi kyseisessä nimiavaruusjärjestyksessä:

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

Yllä olevassa esimerkissä <theme-card> ratkeaa muotoon theme-components/card, <theme-button> käyttää varalla bsui/button-muotoa, jos theme-components/button ei ole rekisteröity, ja <theme-ui-feature-matrix> ratkeaa muotoon theme-components/ui-feature-matrix.

Etuliitteitä voi myös yhdistellä. Jos etuliitteellinen tägä ei ratkea suoraan ja jäljelle jäävä tunniste on itse rekisteröity etuliitetägä, ratkaisua jatketaan rekursiivisesti, jolloin brändietuliitteen voi asettaa nimiavaruusetuliitteen päälle:

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

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

<theme-ui-input>-lohkolla ei ole theme-components/ui-input-lohkoa, joten sen ratkaisu jatkuu etuliitteeseen ui ja ratkeaa muotoon bsui/input. Suorat osumat ovat aina etusijalla sisäkkäiseen ratkaisuun nähden, ja salli- ja estosäännöt koskevat lopullista ratkaistua lohkoa.

Voit määrittää etuliitteitä myös kohdassa blockstudio.json:

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

Etuliitteissä saa olla vain pieniä kirjaimia tai numeroita. Niiden on alettava kirjaimella, eivätkä ne saa sisältää yhdysmerkkejä. Kohteen blockstudio/block_tags/tag_aliases eksplisiittiset aliakset ovat etusijalla etuliitteiden ratkaisuun nähden. Tuntemattomat etuliitteelliset tägät jätetään ennalleen.

Etuliite- ja aliastägät ovat edelleen käteviä kirjoittamisen apuvälineitä. Kanoninen ja siirrettävä kirjoitusasu on aina <bs:namespace-slug>, sillä se ilmaisee varsinaisen lohkon nimen ilman projektisuodattimista riippumista:

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

Blockstudio-esimerkeissä, luoduissa diagnostiikkatiedoissa ja ohjelmallisessa tulosteessa käytetään tätä kanonista kirjoitusasua. Projektit, jotka haluavat poistaa vanhemman lyhennemuodon, voivat käyttää itsenäistä, ensin koeajon suorittavaa kanonisten tägien siirtymää käynnistämättä WordPressa.

Ydinlohkot

Mitä tahansa lohkoa, jolla on rekisteröity renderöijä, voi käyttää:

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>

Tai syntaksilla <block>:

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>

Salli- ja estolistat

Määritä, mitkä lohkot voivat renderöityä tägien kautta:

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

allow rajoittaa renderöinnin vain täsmääviin malleihin. deny sulkee pois täsmäävät mallit ja on etusijalla. Molemmat tukevat fnmatch()n kautta käytettäviä *-jokerimerkkejä. Näitä sovelletaan molempiin syntakseihin sekä malli- että sivutason renderöintiin.

Suodattimet: blockstudio/block_tags/allow ja blockstudio/block_tags/deny.

HTML-määritteiden välitys

Etuliitteellä data- alkavat määritteet välitetään renderöidyn lohkon juurielementille. Myös etuliitteellä html- alkavat määritteet välitetään, ja etuliite poistetaan. Toimii molemmilla syntakseilla. Välitetty määrite korvaa juurielementin aiemman arvon yhdistämisen sijaan, joten html-class korvaa lohkon omat luokat.

Blockstudio-lohko lisää myös juurielementtiinsä ne yleiset määritteet, joita se ei määritä kentiksi: id, style, role, title, lang, dir, hidden, tabindex ja kaikki aria-*-määritteet. Määritetty kenttä on aina etusijalla, joten jos lohkolla on title-kenttä, se saa arvon sen sijaan kohteesta $a['title']. Välitetyt tyylit käsitellään suodattimen safecss_filter_attr() kautta, WordPress-suodatin koskee artikkelien sisällön tyylimääritteitä, ja tyylit lisätään mallin jo määrittämän tyylin perään.

Määritteiden arvot ovat HTML, joten entiteetit dekoodataan kerran tägää jäsennettäessä: title="Tom &amp; Jerry" välittyy malliin muodossa Tom & Jerry ja escapetaan uudelleen tulosteessa. Lainausmerkkien sisällä olevissa arvoissa voi olla >, kuten Tailwind-muunnelmissa ja animaation valitsimissa, sekä itsestään sulkeutuvissa että parillisissa tägeissä.

Lohkon muut määrittelemättömät määritteet, kuten class, eivät koskaan päädy HTML-muuttujaan. Kun WP_DEBUG on käytössä, Blockstudio ilmoittaa kustakin tällaisesta määritteestä kerran pyyntöä kohti kohteen _doing_it_wrong() kautta. Määritä sille kenttä tai kirjoita se data--, aria-– tai html--määritteenä.

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>

Mukautetut renderöijät

Rekisteröi mukautettuja lohkorenderöijiä muille lohkotyypeille. Renderöijät ottavat vastaan määritetaulukon ja sisällön merkkijonon ja palauttavat WordPress-lohkojen taulukon:

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

Jos säilölohkon sisällön sisäosat on jäsennettävä alatason lohkoiksi, lisää samaan suodattimeen toinen alkio:

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,
    ];
};

blockstudio/block_tags/builders koskee sekä lohkotägejä että kohteen blockstudio/parser/element_mapping kautta valittuja mukautettuja lohkoja. Tämä on sopiva koukku, kun elementtiin yhdistetyn projektin lohkon sisäinen teksti pitää siirtää Blockstudio-kenttään tai muodostaa mukautettu lohkotaulukko.

blockstudio/block_tags/renderers ja blockstudio/parser/renderers saavat saman rekisterin ja takaisinkutsun muodon. Ne ovat käytettävissä yhteensopivuuden vuoksi sekä jäsentimen viimeisiin tason ohituksiin. Suodattimet suoritetaan tässä järjestyksessä:

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

Myöhempi suodatin voi korvata aiemmin rekisteröidyn renderöijän.

Ohjelmallinen käyttö

Käsittele tägien renderöintiä mihin tahansa merkkijonoon kohteesta PHP:

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

Komponentit

Lohkotägät sopivat hyvin yhteen komponenttien kanssa. Komponentit ovat lohkoja, jotka renderöidään vain ohjelmallisesti eivätkä koskaan näy editorissa.

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

Jäsennin

Lohkotägät käsitellään kevyellä merkkijonon skannerilla, joka korvaa DOMDocumentin. Jäsennin tukee sekä syntakseja <bs:> ja <block>, saman nimisten sisäkkäisten tägien syvyysseurantaa, lainausmerkeissä olevia määritearvoja sekä rekursiivisia säilölohkoja. Se on suunniteltu juuri tähän käyttötapaukseen, toimii suorituskykytesteissä sekä DOMDocumentia että WordPressn WP_HTML_Tag_Processora nopeammin ja välttää DOMDocumentin tunnetut ongelmat nimiavaruusetuliitteiden poistossa ja määritteiden muuttamisessa pienaakkosiksi.

Sivujen, kuvioiden ja sivustomallien yhteydessä sama jäsennin käsittelee myös raakoja HTML-elementtejä (<p>, <div>, <h1> jne.) ja yhdistää ne niitä vastaaviin ytimen WordPress-lohkoihin.

Kun elementtikartoitus yhdistää <p>n rekisteröityyn ei-ytimen Blockstudio-lohkoon, jossa on content richtext-määrite, sisäinen HTML ohjataan automaattisesti kyseiseen content-määritteeseen. Tämä koskee myös sisäisiä tägejä, kuten code ja img, jotka on yhdistetty lohkotasolla elementteihin. Kappale, jonka ainoa alielementti on kuva, muuttuu lohkoksi, johon <img> yhdistää. Sisäkkäiset lohkotägät tai lohkotason HTML käsitellään edelleen normaalisti sisälohkojen jäsennyksen kautta. <block name="core/shortcode"> säilyttää lyhytkooditekstinsä lohkon sisältönä.