Pāriet uz saturu

Programmatiska renderēšana

Tā kā Gutenberg kļūst par galveno rīku viegli rediģējamu vietņu izveidei klientiem, ir loģiski veidot visus nepieciešamos vietnes apgabalus kā blokus. Šī pieeja būs piemērota lielākajai daļai lietotāju, taču pieredzējušiem lietotājiem un konkrētiem lietojuma gadījumiem var būt nepieciešams izmantot esošos blokus ārpus redaktora.

Blockstudio nodrošina divus veidus, kā programmatiski renderēt blokus:

  • PHP funkcijas: bs_render_block un bs_block renderēšanai no PHP koda
  • HTML tagi: <bs:block-name> tagi, kas tiek aizstāti ar bloka izvadi jebkurā lapas vietā

Tiek atbalstītas visas Blockstudio specifiskās funkcijas, piemēram, iekļautie stili, skripti un tvērumā ierobežoti stili.

Salas darbojas arī šajos renderēšanas ceļos. Dinamiska sala, kas renderēta ar bs_render_block(), bs_block() vai bloka tagu, atgriež tādu pašu viettura marķieri kā no ieraksta satura renderēts bloks, un priekšgala izpildlaiks tiek ievietots, ja šis marķieris ir iekļauts atbildē.

Strukturētas kompozīcijas un pilni dokumenti

Ilgstoši izmantojamiem rīkiem, priekšskatījumiem, eksportiem un komponentu galerijām izmantojiet versijotu Blockstudio\Render API. Tas pieņem vienu deklarāciju vai sakārtotu sarakstu un renderē bez izvades izvadīšanas:

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

Standartizētajā normalizētajā deklarācijā ir četras atslēgas:

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

data, inner, innerBlocks, root, layers un example ir ērtākai ievadei paredzēti elementi, kas normalizēšanas laikā tiek noņemti. Ligzdotās deklarācijas tiek renderētas rekursīvi, izmantojot to pašu Blockstudio konveijeru.

Render::document() atgriež schemaVersion, html, body, blocks, assets, warnings un errors. Vērtība assets atdala head, footer, styles, scripts, modules, interactivity, ui un tailwind. Bloku sarakstā un resursos ietilpst atlasītajās veidnēs norādītās atkarības, bet nav iekļauti nesaistīti resursi un redaktoram paredzētie resursi.

Pilnos dokumentos var iestatīt bodyClasses/bodyAttributes un pēc izvēles ietvert renderēto pamatdaļu ar contentElement, contentClasses un contentAttributes. Ietvarā var izmantot tikai drošu elementa nosaukumu; atgrieztā body vērtība paliek neietverts renderētais saturs. Opcijas head un footer attiecīgajās vietās pievieno uzticamu dokumenta marķējumu un tiek iekļautas atgrieztajā resursu slēgumā.

Lai ap dokumentu, kas jau ir renderēts ar HTML, izveidotu ietvaru, norādiet zināmos saknes bloku nosaukumus:

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

Serializētam WordPress bloka saturam izmantojiet Render::content(). Patērētājiem, kas vienā pieprasījumā renderē vairākus neatkarīgus dokumentus, starp tiem jāizsauc Blockstudio\Batch_Render::reset(); Canvas::documents() to dara automātiski.

Renderēšana ārpus lapas

Blockstudio katra renderētā bloka priekšā ievieto <!--blockstudio/namespace/slug--> komentāru. Saskarnes lapā buferis nolasa šos komentārus, lai noteiktu, kuri bloki ir iekļauti, ielādētu to resursus un noņemtu komentārus pirms atbildes nosūtīšanas.

Izvadei, kas netiek apstrādāta šajā buferī, komentāri paliek. Tas attiecas uz REST atbildēm, plūsmām, AJAX apstrādātājiem un HTML, ko saglabājat vai nosūtāt citur pēc do_blocks(), Render::content() vai bs_render_block(). To noņemšanai izmantojiet bs_strip_render_markers():

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

Funkcija noņem reģistrēto Blockstudio bloku komentārus un atstāj visu pārējo neskartu, tostarp citus HTML komentārus. Tā meklē tos pašus marķierus, ko noņem lapas buferis. Izsauciet to pēc bloku reģistrēšanas (init vai vēlāk).

Neizņemiet marķējumu, kas joprojām tiek izvadīts buferētā saskarnes lapā. Lapai vajadzīgi komentāri, lai noteiktu, kurus bloku resursus ielādēt, un Blockstudio tos noņem pašās beigās.

Komentāru noņemšana nepievieno resursus. Bloku CSS un JavaScript faili tiek ievietoti tikai lapas buferī. Izmantojiet bs_block_assets() vai Render::document(), ja tie vajadzīgi arī patērētājam.

Bloku pārbaude

Pēc bloku reģistrēšanas (init vai vēlāk) izmantojiet bs_block_fields(), lai iegūtu atrisinātās lauku definīcijas, nelasot iekšējos reģistrus:

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

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

Atgrieztā vērtība ir reģistrēto lauku definīciju masīvs, kurā ietilpst atribūtu filtri, izvērstie pielāgotie lauki, aizstājumi un ligzdotas grupas, cilnes un atkārtotāji. Bloks Blockstudio bez laukiem atgriež []. Rezultāts ir kopija: tā izmaiņas nemaina reģistrēto bloku.

Tās ir definīcijas, nevis saglabātās vērtības. Lai validētu saglabāto marķējumu, izmantojiet bs_validate_block() definīcijas , nevis uzturiet atsevišķu lauku apstaigāšanas funkciju. Lai aprakstītu vērtības, ko bloks pieņem, izmantojiet bs_block_schema() definīcijas . WordPress piederošie atribūti paliek atsevišķi.

Lauki, ko pievieno paplašinājumi paplašinājumi, nav iekļauti bs_block_fields(). Lai tos iegūtu, izmantojiet bs_block_extension_fields(). Tā atrod paplašinājumus pēc bloka nosaukuma, tāpēc darbojas arī ar pamata un trešo pušu blokiem:

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

Atgrieztajā vērtībā uzskaitītas visu atbilstošo paplašinājumu lauku definīcijas tādā secībā, kādā paplašinājumi reģistrēti, un ar tādu pašu struktūru kā bs_block_fields(). Ja blokam nav atbilstoša paplašinājuma, tiek atgriezts []. Paplašinājumu vērtības tiek saglabātas tajā pašā objektā attrs.blockstudio.attributes, kurā ir paša bloka lauku vērtības, tāpēc visiem ID ir viena nosaukumtelpa. Ja divi paplašinājumi definē vienu un to pašu ID, tiek atgrieztas abas definīcijas un tās rediģē vienu un to pašu vērtību; renderēšanas laikā tiek izmantota vēlāk reģistrētā paplašinājuma definīcija.

Lai nolasītu saglabāta bloka vērtības tā, kā tās saņem veidne, izmantojiet bs_block_values().

Izmantojiet bs_block_assets(), lai pārbaudītu bloka atrastos CSS un JavaScript. Lai iegūtu pilnu priekšskatījuma dokumentu, tostarp ligzdotos blokus un koplietotās izpildlaika atkarības, izmantojiet Render::document(), kā aprakstīts iepriekš.

Saglabāto vērtību validēšana

Pēc bloku reģistrēšanas (init vai vēlāk) izmantojiet bs_validate_block(), lai pirms saglabāšanas pārbaudītu programmatiski ģenerētus vai importētus bloku atribūtus:

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

Padodiet visu attrs masīvu, ne tikai blockstudio.attributes. Blockstudio renderēšana pieņem deklarētos laukus arī augšējā līmenī, un, ja norādītas abas vērtības, priekšroka ir ligzdotajām. Pamata un trešo pušu bloku paplašinājumi nolasa tikai blockstudio.attributes. Tukšs Blockstudio bloks tiek pārvaldīts un atgriež [], nevis null.

Validācija ir skaidri izsaucama un nemaina datus. Tā nerenderē veidnes, nemaina vērtības, nesaglabā ziņas, neveic multivides vaicājumus un neizpilda aizpildīšanas atzvanus. Tā nenotiek automātiski saglabāšanas, lapu sinhronizēšanas vai renderēšanas laikā. Tā nav ne sanitizētājs, ne autorizācijas pārbaude, ne pielikuma esamības pārbaude.

Katrs atradums satur šādas nemainīgas atslēgas:

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

Rīkos izmantojiet code, nevis tulkoto message. source ir block vai extension. Ceļos izmanto glabāšanas atslēgas un atkārtotāja rindu vai atlases indeksus, sākot no nulles, bez slīpsvītras sākumā. Burtiski ~ un / atslēgā tiek kodēti kā ~0 un ~1. Augšējā līmeņa grupa pievieno prefiksu saviem bērnelementiem (cta_title); anonīmas grupas un cilnes nepievieno līmeni. Grupas ar ID citas grupas vai atkārtotāja iekšienē būvētājs neatbalsta, tāpēc to atslēgas netiek pieņemtas. Ziņojumu laukiem nav saglabātas vērtības. Failu lauks pieļauj saistīto <id>__size. Bloka Blockstudio saknē uzskaites atslēgas un globālie HTML atribūti, kas tiek nodoti attēlotajam elementam, nav nezināmi lauki. Tas neatļauj patvaļīgas atslēgas atkārtotāja rindās vai pamata bloku paplašinājumos.

Kods Nozīme expected
unknown_field Neviens saglabātais lauks nedeklarē šo glabāšanas atslēgu. Zināmās glabāšanas atslēgas.
unknown_option Atlase nav starp zināmajām opcijām. Atļautās opciju vērtības.
wrong_type Saglabātā struktūra nav atbalstīta šim laukam. Paredzētā glabāšanas saime vai tips.
too_few_rows, too_many_rows Esošs atkārtotājs neatbilst tā min vai max. Rindu ierobežojums.
definition_conflict Piemērojamās definīcijas vienai atslēgai pieprasa atšķirīgas glabāšanas struktūras. Katras definīcijas avots un lauka tips.
shadowed_value Ligzdota vērtība aizstāj citu augšējā līmeņa lauka vērtību. Uzvarējusī ligzdotā vērtība.
extension_top_level Veidne var nolasīt augšējā līmeņa vērtību, bet paplašinājumu piesaistes to nevar. Tās obligātais ceļš zem blockstudio/attributes.
unknown_attribute Augšējā līmeņa atslēga Blockstudio blokā netiek nolasīta renderēšanas ceļā un tiek atmesta. Reģistrētie atribūtu nosaukumi, paplašinājumu lauki un blockstudio.
missing_container attributes, disabled, name vai editor ir saglabāts augšējā līmenī, un trūkst blockstudio. Tā obligātais ceļš zem blockstudio.
invalid_container blockstudio vai blockstudio.attributes nav objekts. object.

unknown_field atradnes paziņojumā ir norādīta tuvākā tā paša līmeņa krātuves atslēga, ja atšķirība nepārsniedz trīs labojumus — tik daudz izmanto noteikums par nezināmiem iestatījumiem: This storage key is not declared by the block or its extensions. Did you mean "title"?. expected joprojām uzskaita visas zināmās atslēgas. Meklēšana ignorē reģistru un ņem vērā tikai šī konteinera krātuves atslēgas. Paziņojumi tiek tulkoti; integrācijām jāizmanto code, path un expected, nevis jāanalizē paziņojuma teksts.

Augšējā līmeņa atslēga Blockstudio blokā tiek atmesta pirms veidnes palaišanas, ja tā nav reģistrēts atribūts (tā lauki vai atribūti, ko WordPress pievieno laukiem supports, lock un metadata), atbilstoša paplašinājuma lauks, blockstudio, uzskaites atslēga vai nodots HTML atribūts. Šāda atslēga, piemēram, kļūdaini ievadīts lauka ID vai vērtību objekts, kas saglabāts bez tā ietverošā blockstudio, rada konstatējumu, jo bloks tiek attēlots bez šīs vērtības. Bloki, kuros ir tikai paplašinājumu lauki, netiek pārbaudīti attiecībā uz augšējā līmeņa atslēgām.

Pieņemtās struktūras atbilst renderēšanai: vairākas atlases un izvēles rūtiņas var saturēt sarakstu, vienu opcijas objektu vai importētu skalāru vērtību, tostarp skaitlisku nulli. Skaitļiem pieņem skaitliskas virknes. Failos var būt pielikumu ID, ID objekti, saraksti vai virkņu atsauces. Saites un ikonas vērtībām jābūt objektiem; pielāgotie lauku tipi izmanto reģistrēto atribūta tipu. Lauks attributes satur pāru sarakstu ar netukšu attribute nosaukumu un skalāru value; papildu metadati, piemēram, data.media, tiek saglabāti.

WordPress pirms renderēšanas validē reģistrētos augšējā līmeņa atribūtus, tāpēc var noraidīt tādu struktūru, kas ir pieņemta blockstudio.attributes. Piemēram, radio vērtība "a" ligzdotajā objektā darbojas, bet augšējā līmenī tiek atmesta, jo tās reģistrētais tips ir object. Šāda vērtība rada wrong_type. Izmantojiet ligzdoto objektu, lai saglabāšanas struktūra atbilstu tai, ko ieraksta redaktors.

Trūkstoši lauki nav obligāti. Tukšas ligzdotās vērtības (null, false, '', []) un atspējoti lauki nerada vērtību kļūdas. Skaidri norādīts tukšs atkārtotājs joprojām tiek pārbaudīts pret min; neesošs vai atspējots atkārtotājs netiek pārbaudīts. Par tukšu augšējā līmeņa vērtību tiek ziņots, ja WordPress to atmet un atjauno netukšu noklusējuma vērtību. Tāda pati vērtība ligzdotajā objektā var to notīrīt. Par definīciju konfliktiem tiek ziņots arī tad, ja atslēgai nav saglabātas vērtības.

Statiskās opcijas un reģistrācijas brīdī atrisinātās aizpildīšanas opcijas tiek pārbaudītas, vēlreiz neizsaucot aizpildīšanu. Attālās fetch opcijas un aizpildīšanas argumenti, kas satur {attributes.*}, tiek izlaisti. Krāsu un gradientu vērtības var būt pielāgotas, ja vien nav iestatīts disableCustomColors vai disableCustomGradients. Šī pārbaude attiecas uz saglabātajām vērtībām, nevis uz default, fallback vai redaktora validācijas noteikumiem.

Atbilstošie paplašinājumu lauki tiek iekļauti katram blokam, uz kuru tie attiecas. Vēlākas definīcijas uzvar blokā vai tā paplašinājumos saknes līmenī, tāpat kā renderēšanas laikā. Bloka lauks un paplašinājuma lauks paliek atsevišķas viena un tā paša atslēgas definīcijas, un abas tiek piemērotas. Atkārtotāja rindās renderētājs katrā avotā nolasa pirmo lauku ar atbilstošu ID, tāpēc tiek izmantotas tā opcijas un ierobežojumi. Dublikātu definīcijas tiek saglabātas konfliktu diagnostikai: neatbilstošas glabāšanas struktūras rada definition_conflict pat tad, ja vēlāks dublikāts renderēšanas laikā netiek nolasīts.

Funkcija pārbauda vienu bloku. Validējot dokumentu, apstaigājiet innerBlocks; sinhronizēti raksti un citas atsauces netiek automātiski izvērsti. Komanda wp bs blocks validate apstaigā viena vai vairāku ierakstu blokus un ziņo par to bloku ceļiem.

Vietnes ar pielāgotu renderēšanas laika atrisinātāju var pielāgot konstatējumus, nemainot saglabātos datus:

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

Vienmēr atgrieziet konstatējumu sarakstu; atgriežot [], bloks tiek pieņemts. Šis filtrs darbojas tikai pārvaldītiem blokiem, nekad null rezultātam.

Saglabāto vērtību aprakstīšana

Izmantojiet bs_block_schema() pēc bloka reģistrēšanas (init vai vēlāk), lai aprakstītu blokā saglabātās vērtības, piemēram, lai rīkā vai AI integrācijā ģenerētu bloka marķējumu vai pārbaudītu ievadi REST maršrutā:

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

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

Rezultāts ir saglabātā objekta JSON shēma attrs.blockstudio.attributes. Tā aptver bloka laukus un atbilstošo paplašinājumu laukus, kā arī validācijā izmantotās krātuves atslēgas: augstākā līmeņa grupa pievieno prefiksu saviem bērnelementiem, anonīmās grupas un cilnes nepievieno līmeni, bet failu lauks pievieno savu <id>__size pavadošo lauku. Atkārtotāji ir rindu objektu saraksti ar minItems un maxItems, kas ņemti no min un max. additionalProperties ir false lauku krātuves saknē un atkārtotāju rindās. Laukiem, kuru vērtība ir objekts, piemēram, saitēm un pielāgotiem objektiem, var būt savi metadati. Blokam bez laukiem nav properties, tāpēc atbilst tikai tukšs objekts.

Katrs lauks ir aprakstīts kanoniskā formā, ko pieņem bs_validate_block():

Lauks Shēma
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Virkne.
number, range Skaitlis ar minimum un maximum no min un max.
toggle Loģiskā vērtība.
select, radio, checkbox Opcijas vērtība vai opciju vērtību saraksts priekš checkbox un multiple ar enum.
color, gradient Virkne ar enum, ja ir iestatīts disableCustomColors vai disableCustomGradients.
token Virkņu saraksts.
files Nenegatīvs pielikuma ID skaitlis vai ID saraksts ar multiple.
link Objekts ar url, title un opensInNewTab; url ir obligāts.
icon Objekts ar set, subSet un icon; set un icon ir obligāti.
attributes Objektu saraksts ar netukšu attribute un skalāru value.
repeater Rindu objektu saraksts.
Pielāgoti lauku tipi To reģistrētais atribūta tips.

enum uzskaita validācijas pārbaudītās opcijas: statiskās opcijas un reģistrācijas brīdī jau atrisinātās aizpildīšanas opcijas. Attālinātajām fetch opcijām un aizpildīšanas argumentiem, kas satur {attributes.*}, nav enum. Atslēga, kurai definētas dažādas krātuves formas, tiek izlaista, jo validācija ziņo par visām zem tās saglabātajām vērtībām. Ja bloka laukam un paplašinājuma laukam ir kopīga atslēga, enum uzskaita vērtības, ko pieņem abi. Kopīgie atkārtotāji apvieno bērnelementu laukus un piemēro stingrākos rindu ierobežojumus no abām definīcijām. Atkārtotāju rindās izmanto pirmo lauku ar atbilstošu ID katrā avotā, tāpat kā renderēšanas laikā. Skaidri definētam laukam ar nosaukumu <id>__size ir priekšroka pār automātiski pievienoto faila lieluma pavadošo lauku.

Ja slēgtam laukam nav pieejamu izvēļu vai divām piemērojamām opciju kopām nav kopīgu izvēļu, tā kanoniskā vērtība ir null vienai izvēlei vai tukšs saraksts vairākām izvēlēm. Tukšs opciju saraksts nepadara lauku neierobežotu. Attālinātās un no atribūtiem atkarīgās izvēles paliek atvērtas.

Lauka label kļūst par title, tā help kļūst par description, bet default tiek saglabāta kā anotācija. Shēmas pašas title ir bloka nosaukums. Lauki nekad nav obligāti, un nosacījumu loģika nav shēmas daļa.

Ierobežojumos izmantoti tikai tādi atslēgvārdi, ko pārbauda rest_validate_value_from_schema(), tāpēc shēmu var izmantot tādu, kāda tā ir, kā ievades shēmu REST maršrutam vai iespējai:

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

Shēma apraksta vienu veidlapu katram laukam; validācija pieņem arī importētas struktūras, piemēram, opciju objektus, skaitliskas virknes un ID objektus. Tā neaizstāj bs_validate_block(): definīciju konflikti ir konfigurācijas problēmas, un tie joprojām var radīt konstatējumus arī tad, ja konfliktējošā atslēga ir izlaista. Validācijas filtri var arī ieviest vietnei specifiskus noteikumus. Izmantojiet bs_validate_block(), lai pārbaudītu saglabāto saturu. Vietnes ar pielāgotu renderēšanas laika risinātāju var pielāgot shēmu, izmantojot filtru blockstudio/blocks/attributes/schema.

PHP funkcijas

Bez datiem

Visvienkāršākajā formā funkcija pieņem vienu vērtību — renderējamā lapas bloka ID.

PHP
bs_render_block('blockstudio/cta');

Ar datiem

Lai renderētu bloku ar pielāgotiem datiem, pirmā parametra vienas vērtības vietā jāizmanto masīvs. Vērtība data atslēgā tiks nodota mainīgajam $attributes un $a jūsu bloka veidnē.

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

Ligzdošana

Blokus var ligzdot citu citā, izmantojot funkciju bs_block kopā ar jaudīgo mainīgo $content jūsu bloku veidnēs.

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

Pogas bloks tiks renderēts bloka veidnē mainīgā $content vietā.

Iegultie bloki, kas renderēti ar bs_render_block() vai bs_block(), vienmēr izvada priekšgalā atrisinātu HTML, pat tad, ja vecākbloks pašlaik tiek renderēts kā redaktora priekšskatījums. Veidnes pseidokomponenti, piemēram, <RichText /> un <InnerBlocks />, tiek atrisināti pirms iegultā bloka atgriešanas.

Vairākas vietturu zonas

Var izveidot arī vairākas satura vietturu zonas, vienkārši padarot mainīgo $content par asociatīvu masīvu un izsaucot atbilstošās tā atslēgas funkcijā bs_block.

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

Bloku tagi

Ieguliet jebkuru bloku, izmantojot HTML tagu sintaksi. Tiek atbalstīti divi formāti:

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

Abi renderē vienu un to pašu bloku. Sintaksē <bs:> defise kļūst par nosaukumvietas atdalītāju (acme-hero kļūst par acme/hero). Defises tiek pārbaudītas no kreisās uz labo pusi, un tiek izmantots pirmais reģistrētais kandidāts, tāpēc tiek atrisinātas arī nosaukumvietas, kurās ir defises: <bs:acme-ui-button> pārbauda acme/ui-button, pēc tam acme-ui/button. Sintaksē <block> pilnais bloka nosaukums tiek norādīts kā atribūts name.

Darbojas gan Blockstudio bloki, gan pamata WordPress bloki. Blockstudio bloki tiek renderēti, izmantojot visu apstrādes secību (veidnes, Tailwind, resursi). Pamata bloki tiek renderēti, izmantojot WordPress bloku renderēšanas sistēmu un iebūvētos bloku renderētājus.

Kā tas darbojas

Bloku tagi darbojas atšķirīgi atkarībā no to atrašanās vietas:

Bloku veidnēs un ierakstu saturā tagi izpildes laikā tiek aizstāti ar renderētiem HTML. Izvade ir atsauces bloka galīgais marķējums, kas iegults tieši lapā. Redaktorā šiem tagiem nav WordPress bloka. Tie kalpo tikai renderēšanai.

lapās, rakstos un vietņu veidnēs tagi tiek pārveidoti par vietējiem WordPress blokiem, pirms faila avots tiek sinhronizēts vai reģistrēts pakalpojumā WordPress. Tādējādi bloki parādās redaktorā, tos var rediģēt, ja mērķa vide to atbalsta, un tie iziet visu WordPress bloka dzīves ciklu. Taga sintakse ir saīsināts veids, kā veidņu failos definēt bloka saturu.

Šī atšķirība ir būtiska: bloku tagi veidnēs rada izvadi, bet bloku tagi lapās, rakstos un vietņu veidnēs rada vietējos blokus.

Bloku veidnēs

Bloku tagi tiek automātiski renderēti Twig un PHP veidnēs. Iestatījumi nav vajadzīgi. Tas attiecas arī uz sintaksēm <bs:> un <block>, kā arī jebkuriem reģistrētiem prefiksiem un aizstājvārdu tagiem, tāpēc veidne var tos izvadīt tieši, nevis izsaukt bs_render_block(). Izvade tiek renderēta HTML un iegulta tieši bloka veidnes izvadē:

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>

Ieraksta saturā

Lapu līmeņa renderēšana (ieraksta saturs, logrīku zonas) ir jāieslēdz atsevišķi:

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

Vai arī, izmantojot filtru:

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

Sintakse

Tagi bez noslēdzošā taga:

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

Pāra tagi ar iekšējo saturu:

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>

Brīvi kombinējiet abas formas. Abas sintakses var ligzdot citu citā:

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>

Prefiksu saīsinājumi

Bloku tagos var izmantot arī projektam specifiskus prefiksu saīsinājumus. Reģistrējiet prefiksu ar vienu vai vairākām nosaukumvietām, un Blockstudio atrisinās <prefix-slug> kā pirmo reģistrēto bloku attiecīgajā nosaukumvietu secībā:

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

Izmantojot iepriekš minēto piemēru, <theme-card> tiek atrisināts kā theme-components/card, <theme-button> tiek izmantots kā rezerves variants bsui/button, ja theme-components/button nav reģistrēts, un <theme-ui-feature-matrix> tiek atrisināts kā theme-components/ui-feature-matrix.

Prefiksus var arī kombinēt. Ja taga ar prefiksu nav tiešas atbilstības un atlikusī daļa pati ir reģistrēts prefiksa tags, atrisināšana turpinās rekursīvi, tāpēc zīmola prefikss var balstīties uz nosaukumvietas prefiksu:

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> nav bloka theme-components/ui-input, tāpēc tiek izmantots prefikss ui un atrisināts bsui/input. Tiešām atbilstībām vienmēr ir priekšroka pār ligzdotu atrisināšanu, un atļaušanas un liegšanas noteikumi tiek piemēroti galīgi atrisinātajam blokam.

Prefiksus var konfigurēt arī sadaļā blockstudio.json:

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

Prefiksiem jābūt veidotiem no mazajiem burtiem vai cipariem, jāsākas ar burtu, un tajos nedrīkst būt defises. Skaidri norādītiem aizstājvārdiem no blockstudio/block_tags/tag_aliases ir priekšroka pār prefiksu atrisināšanu. Nezināmi tagi ar prefiksu tiek atstāti nemainīti.

Prefiksu un aizstājvārdu tagi joprojām ir pieejami ērtākai satura veidošanai. Kanoniskais, pārnesamais pieraksts vienmēr ir <bs:namespace-slug>, jo tajā ir norādīts īstais bloka nosaukums un tas nav atkarīgs no projekta filtriem:

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

Blockstudio piemēros, ģenerētajā diagnostikā un programmatiskajā izvadē tiek izmantota šī kanoniskā rakstība. Projekti, kas vēlas noņemt vecāku saīsināto pierakstu, var izmantot patstāvīgo migrāciju ar vispirms veicamu izmēģinājumu uz kanoniskajiem tagiem, nepalaižot WordPress.

Pamata bloki

Var izmantot jebkuru bloku, kuram ir reģistrēts renderētājs:

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>

Vai arī, izmantojot sintaksi <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>

Atļaušanas un liegšanas saraksti

Kontrolējiet, kurus blokus var renderēt, izmantojot tagus:

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

allow ierobežo atbilstību tikai noteiktiem rakstiem. deny izslēdz atbilstošos rakstus, un tam ir priekšroka. Abi atbalsta * aizstājējzīmes, izmantojot fnmatch(). Tie attiecas uz abām sintaksēm un gan veidņu, gan lapu līmeņa renderēšanu.

Filtri: blockstudio/block_tags/allow un blockstudio/block_tags/deny.

HTML caurlaide

Atribūti, kuru nosaukums sākas ar data-, tiek nodoti renderētā bloka saknes elementam. Tādi paši ir arī atribūti ar prefiksu html-, tikai prefikss tiek noņemts. Darbojas ar abām sintaksēm. Caurlaides atribūts aizstāj saknes elementa esošo vērtību, nevis to papildina, tāpēc html-class aizstāj bloka klases.

Blockstudio bloks saknes elementā ievieto arī globālos atribūtus, kas nav deklarēti kā lauki: id, style, role, title, lang, dir, hidden, tabindex un katru atribūtu aria-*. Deklarētam laukam vienmēr ir priekšroka, tāpēc bloks ar lauku title tā vietā saņem vērtību no $a['title']. Nodotie stili tiek apstrādāti caur safecss_filter_attr(); filtrs WordPress tiek piemērots stila atribūtiem ieraksta saturā, un tie tiek pievienoti veidnē jau norādītajam stilam.

Atribūtu vērtības ir HTML, tāpēc entītijas tiek atkodētas vienreiz, parsējot tagu: veidne saņem title="Tom &amp; Jerry" kā Tom & Jerry, un izvades laikā tas tiek atkal ekranēts. Pēdiņās norādītās vērtībās var būt >, kā to izmanto Tailwind variantos un animācijas atlasītājos, gan tagos bez noslēdzošā taga, gan pāra tagos.

Jebkurš cits bloka nedeklarēts atribūts, tostarp class, nesasniedz HTML. Ja ir ieslēgts WP_DEBUG, Blockstudio par katru šādu atribūtu ziņo vienreiz katrā pieprasījumā, izmantojot _doing_it_wrong(). Deklarējiet šim atribūtam lauku vai norādiet to kā atribūtu data-, aria- vai html-.

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>

Pielāgoti renderētāji

Reģistrējiet pielāgotus bloku renderētājus papildu bloku tipiem. Renderētāji saņem atribūtu masīvu un iekšējā satura virkni un atgriež bloka masīvu WordPress:

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

Konteinerbloku gadījumā, kad iekšējais saturs jāsadala bērnblokos, pievienojiet otru ierakstu tajā pašā filtrā:

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 attiecas gan uz bloku tagiem, gan pielāgotiem blokiem, kas atlasīti, izmantojot blockstudio/parser/element_mapping. Šis ir piemērotais āķis, ja projektā izmantotam bloka elementa atveidojumam iekšējais teksts jāpārvieto uz lauku Blockstudio vai jāizveido pielāgots bloka masīvs.

blockstudio/block_tags/renderers un blockstudio/parser/renderers saņem to pašu reģistru un atzvanīšanas funkcijas formu. Tie joprojām ir pieejami saderībai un pēdējā līmeņa parsētāja pārrakstījumiem. Filtri tiek izpildīti šādā secībā:

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

Vēlāks filtrs var aizstāt ar agrāku filtru reģistrētu renderētāju.

Programmatiska lietošana

Piemērojiet tagu renderēšanu jebkurai virknei no PHP:

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

Komponenti

Bloku tagi labi sader ar komponentiem Komponenti. Komponenti ir bloki, kas tiek renderēti tikai programmatiski un nekad neparādās redaktorā.

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

Parsētājs

Bloku tagus apstrādā viegls virkņu skeneris, kas aizstāj DOMDocument. Parsētājs apstrādā gan sintaksi <bs:>, gan <block>, ligzdotus viena nosaukuma tagus, sekojot to dziļumam, atribūtu vērtības pēdiņās un rekursīvus konteinerblokus. Tas ir īpaši izstrādāts šim lietojumam, darbojas ātrāk gan par DOMDocument, gan par WordPress WP_HTML_Tag_Processor un novērš zināmās DOMDocument problēmas ar nosaukumvietu prefiksu noņemšanu un atribūtu nosaukumu pārveidošanu uz mazajiem burtiem.

lapām, rakstiem un vietņu veidnēm tas pats parsētājs apstrādā arī neapstrādātus HTML elementus (<p>, <div>, <h1> u.c.), piesaistot tos atbilstošajiem WordPress pamata blokiem.

Ja elementu atbilstība piesaista <p> reģistrētam blokam Blockstudio, kas nav pamata bloks un kurā deklarēts content richtext atribūts, iekšējais HTML saturs tiek automātiski novirzīts uz šo atribūtu content, tostarp iekļautajiem tagiem, piemēram, code un img, kas bloka līmenī ir piesaistīti elementiem. Rindkopa, kuras vienīgais bērnelements ir attēls, kļūst par bloku, kuram piesaistīts <img>. Ligzdoti bloku tagi vai bloka līmeņa HTML joprojām tiek apstrādāti, izmantojot parasto iekšējo bloku parsēšanu. <block name="core/shortcode"> saglabā īskoda tekstu kā bloka saturu.