Gå til indhold

Programmatisk gengivelse

Da Gutenberg er blevet det foretrukne værktøj til at skabe hjemmesider, som kunder nemt kan redigere, giver det mening at opbygge alle nødvendige dele af hjemmesiden som blokke. Denne tilgang dækker de fleste behov, men avancerede brugere og særlige anvendelser kan kræve, at de eksisterende blokke bruges uden for editoren.

Blockstudio tilbyder to metoder til programmatisk gengivelse af blokke:

  • Funktioner PHP: bs_render_block og bs_block til gengivelse fra kode PHP
  • Taggene HTML: Taggene <bs:block-name>, som erstattes af blokoutput overalt på siden

Alle funktioner, der er specifikke for Blockstudio, understøttes, såsom inline-typografier, scripts og afgrænsede typografier.

Islands fungerer også med disse gengivelsesmetoder. En dynamisk ø, der gengives med bs_render_block(), bs_block() eller et bloktag, returnerer den samme pladsholdermarkør som en blok gengivet fra indholdet i et indlæg. Frontendens runtime indsættes, når denne markør findes i svaret.

Strukturerede kompositioner og komplette dokumenter

Til værktøjer, forhåndsvisninger, eksporter og komponentgallerier, der skal bruges længe, skal du bruge den versionsstyrede Blockstudio\Render API. Den accepterer én deklaration eller en ordnet liste og gengiver uden at udskrive:

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

Den kanoniske normaliserede deklaration har fire nøgler:

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

data, inner, innerBlocks, root, layers og example er forenklinger ved indtastning og normaliseres væk. Indlejrede deklarationer gengives rekursivt gennem den samme pipeline Blockstudio.

Render::document() returnerer schemaVersion, html, body, blocks, assets, warnings og errors. Værdien assets adskiller head, footer, styles, scripts, modules, interactivity, ui og tailwind. Bloklisten og aktiverne omfatter afhængigheder, der refereres til af de valgte skabeloner, men udelader irrelevante aktiver og aktiver, der kun bruges i editoren.

Komplette dokumenter kan angive bodyClasses/bodyAttributes og eventuelt omslutte det gengivne indhold med contentElement, contentClasses og contentAttributes. Wrapperen er begrænset til et sikkert elementnavn; det returnerede body er fortsat det gengivne indhold uden wrapper. Indstillingerne head og footer tilføjer betroet dokumentmarkup på deres respektive positioner og indgår i den returnerede aktivafhængighedsstruktur.

Hvis du vil samle et dokument omkring HTML, der allerede er renderet, skal du angive de kendte rodbloknavne:

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

Brug Render::content() til serialiseret WordPress blokindhold. Forbrugere, der renderer flere uafhængige dokumenter i én anmodning, bør kalde Blockstudio\Batch_Render::reset() mellem dem; Canvas::documents() gør det automatisk.

Gengivelse uden for siden

Blockstudio indsætter en <!--blockstudio/namespace/slug-->-kommentar foran hver blok, den gengiver. På en frontendside læser bufferen disse kommentarer for at se, hvilke blokke der er til stede, indlæser deres aktiver og fjerner kommentarerne, inden svaret sendes.

Output, der ikke passerer gennem bufferen, beholder kommentarerne. Det gælder REST-svar, feeds, AJAX-håndteringer og HTML, du gemmer eller sender et andet sted hen efter do_blocks(), Render::content() eller bs_render_block(). Brug bs_strip_render_markers() til at fjerne dem:

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

Funktionen fjerner kommentarerne for registrerede Blockstudio-blokke og lader alt andet være urørt, herunder andre HTML-kommentarer. Den matcher de samme markører, som sidebufferen fjerner. Kald den efter blokregistrering (init eller senere).

Fjern ikke markup, der stadig udskrives på en bufferlagret frontendside. Siden skal bruge kommentarerne for at vide, hvilke blokaktiver der skal indlæses, og Blockstudio fjerner dem selv til sidst.

Fjernelse af kommentarerne tilføjer ikke aktiver. Blokkenes CSS- og JavaScript-filer indsættes kun af sidebufferen. Brug bs_block_assets() eller Render::document(), når forbrugeren også har brug for dem.

Inspicering af blokke

Brug bs_block_fields() efter blokregistrering (på init eller senere) for at hente de opløste feltdefinitioner uden at læse interne registre:

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

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

Returværdien er det registrerede array med feltdefinitioner, inklusive attributfiltre, udvidede brugerdefinerede felter, tilsidesættelser og indlejrede grupper, faner og repeatere. En Blockstudio-blok uden felter returnerer []. Resultatet er en kopi: Ændringer i den påvirker ikke den registrerede blok.

Dette er definitioner, ikke gemte værdier. Brug bs_validate_block() til at validere gemt markup i stedet for at vedligeholde en separat feltgennemløber. Brug bs_block_schema() til at beskrive de værdier, en blok accepterer. Attributter, der ejes af WordPress, forbliver separate.

Felter, der tilføjes af udvidelser, er ikke en del af bs_block_fields(). Brug bs_block_extension_fields() til at hente dem. Funktionen matcher udvidelser efter bloknavn, så den fungerer også for kerneblokke og tredjepartsblokke:

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

Returværdien viser feltdefinitionerne for hver matchende udvidelse i den rækkefølge, udvidelserne blev registreret, med samme struktur som bs_block_fields(). En blok, der ikke matches af nogen udvidelse, returnerer []. Udvidelsernes værdier gemmes i samme attrs.blockstudio.attributes-objekt som blokkens egne feltværdier, så alle id’er deler ét navnerum. Hvis to udvidelser definerer samme id, returneres begge definitioner, og de redigerer samme værdi; under gengivelse anvendes definitionen fra den udvidelse, der blev registreret sidst.

Brug bs_block_values() til at læse værdierne fra en gemt blok, sådan som skabelonen modtager dem.

Brug bs_block_assets() til at inspicere blokkens fundne CSS og JavaScript. Brug Render::document() som beskrevet ovenfor for at få et komplet forhåndsvisningsdokument, inklusive indlejrede blokke og delte runtime-afhængigheder.

Validering af gemte værdier

Brug bs_validate_block() efter blokregistrering (init eller senere) til programmatisk at kontrollere automatisk genererede eller importerede blokattributter, før du gemmer dem:

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

Angiv hele attrs-arrayet, ikke kun blockstudio.attributes. En Blockstudio-gengivelse accepterer også deklarerede felter på øverste niveau, og indlejrede værdier har forrang, når begge er angivet. Udvidelser af kerneblokke og tredjepartsblokke læser kun blockstudio.attributes. En tom Blockstudio-blok er administreret og returnerer [], ikke null.

Validering er eksplicit og skrivebeskyttet. Den gengiver ikke skabeloner, ændrer ikke værdier, gemmer ikke indlæg, forespørger ikke efter medier og kører ikke udfyldningscallbacks. Den kører ikke automatisk under lagring, sidesynkronisering eller gengivelse. Den er ikke en sanitizer, et autorisationstjek eller en kontrol af, om en vedhæftning findes.

Hvert fund indeholder disse stabile nøgler:

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

Brug code, ikke den oversatte message, i værktøjer. source er block eller extension. Stier bruger lagernøgler og nulbaserede repeater-række- eller valgindekser uden en indledende skråstreg. Bogstavelige ~ og / i en nøgle escapes som ~0 og ~1. En gruppe på øverste niveau tilføjer sine børn som præfiks (cta_title); anonyme grupper og faner tilføjer intet niveau. Grupper med et ID inde i en anden gruppe eller en repeater understøttes ikke af builderen, så deres nøgler accepteres ikke. Meddelelsesfelter har ingen gemt værdi. Et filer-felt tillader dets ledsagende <id>__size. I roden af en Blockstudio-blok er bogføringsnøgler og globale HTML-attributter, der videresendes til det renderede element, ikke ukendte felter. Dette tillader ikke vilkårlige nøgler i repeater-rækker eller udvidelser af kerneblokke.

Kode Betydning expected
unknown_field Ingen bevaret feltdefinition erklærer denne lagernøgle. Kendte lagernøgler.
unknown_option Et valg findes ikke blandt de kendte muligheder. Tilladte valgværdier.
wrong_type Den gemte struktur understøttes ikke af feltet. Forventet lagerfamilie eller type.
too_few_rows, too_many_rows En tilstedeværende repeater ligger uden for dens min eller max. Rækkegrænsen.
definition_conflict Gældende definitioner for én nøgle kræver forskellige lagerstrukturer. Kilde og felttype for hver definition.
shadowed_value En indlejret værdi tilsidesætter en anden feltværdi på øverste niveau. Den vindende indlejrede værdi.
extension_top_level Skabelonen kan læse en værdi på øverste niveau, men bindings til udvidelser kan ikke. Den påkrævede sti under blockstudio/attributes.
unknown_attribute En nøgle på øverste niveau i en Blockstudio-blok læses ikke af renderingsstien og fjernes. Registrerede attributnavne, udvidelsesfelter og blockstudio.
missing_container attributes, disabled, name eller editor er gemt på øverste niveau, og blockstudio mangler. Den påkrævede sti under blockstudio.
invalid_container blockstudio eller blockstudio.attributes er ikke et objekt. object.

Meddelelsen for et fund af typen unknown_field angiver den nærmeste lagernøgle på samme niveau, når den ligger inden for tre redigeringer; det er den regel, der bruges for ukendte indstillinger: This storage key is not declared by the block or its extensions. Did you mean "title"? expected viser stadig alle kendte nøgler. Matchningen ignorerer forskel på store og små bogstaver og omfatter kun lagernøgler fra den pågældende beholder. Meddelelserne er oversat; integrationer bør bruge code, path og expected i stedet for at analysere meddelelsesteksten.

En nøgle på øverste niveau i en Blockstudio-blok, som hverken er en registreret attribut (dens felter, attributterne, som WordPress tilføjer for supports, lock og metadata), et felt fra en matchende udvidelse, blockstudio, en bogføringsnøgle eller en videresendt HTML-attribut, fjernes, før skabelonen køres. En sådan nøgle, for eksempel et forkert indtastet felt-ID eller et værdiobjekt gemt uden sin blockstudio-indpakning, giver et fund, fordi blokken renderes uden værdien. Blokke, der kun indeholder udvidelsesfelter, kontrolleres ikke for nøgler på øverste niveau.

De accepterede strukturer følger renderingen: Flere valg og afkrydsningsfelter kan indeholde en liste, ét valgobjekt eller en importeret skalar, herunder numerisk nul. Numeriske strenge accepteres for tal. Filer kan indeholde vedhæftnings-ID’er, ID-objekter, lister eller strengreferencer. Link- og ikonværdier skal være objekter; brugerdefinerede felttyper bruger deres registrerede attributtype. Et attributes-felt indeholder en liste af par med et ikke-tomt attribute-navn og en skalar value; valgfrie metadata såsom data.media bevares.

WordPress validerer registrerede attributter på øverste niveau før rendering, hvilket kan afvise en struktur, der accepteres inde i blockstudio.attributes. For eksempel fungerer en radioværdi på "a" i det indlejrede objekt, men fjernes på øverste niveau, hvor dens registrerede type er object. En sådan værdi giver wrong_type. Brug det indlejrede objekt til den samme lagerstruktur, som editoren skriver.

Manglende felter er ikke påkrævede. Tomme indlejrede værdier (null, false, '', []) og deaktiverede felter giver ikke værdifejl. En udtrykkeligt tom repeater kontrolleres stadig mod min; en fraværende eller deaktiveret repeater gør ikke. En tom værdi på øverste niveau rapporteres, hvis WordPress fjerner den og gendanner en ikke-tom standardværdi i stedet. Den samme værdi i det indlejrede objekt kan rydde den. Definitionskonflikter rapporteres, selv når nøglen ikke har nogen gemt værdi.

Statiske valgmuligheder og valgmuligheder fra populate, der allerede er løst ved registrering, kontrolleres uden at kalde populate igen. Eksterne fetch-valgmuligheder og populate-argumenter, der indeholder {attributes.*}, springes over. Farve- og gradientværdier kan være brugerdefinerede, medmindre disableCustomColors eller disableCustomGradients er angivet. Dette kontrollerer gemte værdier, ikke default, fallback eller editorens valideringsregler.

Matchende udvidelsesfelter medtages for hver blok, de er målrettet mod. Senere definitioner vinder i blokken eller dens udvidelser på roden, som ved rendering. Blokkens eget felt og et udvidelsesfelt forbliver separate definitioner af samme nøgle, og begge gælder. I repeater-rækker læser rendereren det første felt med et matchende ID i hver kilde, så dets valgmuligheder og grænser gælder. Dublerede definitioner bevares til konfliktdiagnostik: inkompatible lagerstrukturer giver definition_conflict, selv når en senere dubleret definition ikke læses ved rendering.

Funktionen kontrollerer én blok. Gennemgå innerBlocks, når du validerer et dokument; synkroniserede mønstre og andre referencer udvides ikke automatisk. Kommandoen wp bs blocks validate gennemgår blokkene i ét eller flere indlæg og rapporterer deres blokstier.

Websteder med en brugerdefineret resolver ved rendering kan tilpasse fundene uden at ændre gemte data:

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

Returnér altid en liste over fund; hvis du returnerer [], accepteres blokken. Dette filter køres kun for administrerede blokke, aldrig for resultatet fra null.

Beskrivelse af gemte værdier

Brug bs_block_schema() efter blokregistrering (init eller nyere) til at beskrive de værdier, en blok gemmer, for eksempel for at generere blokmarkup i et værktøj eller en AI-integration eller for at kontrollere input i en REST-rute:

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

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

Resultatet er et JSON-skema for det objekt, der er gemt i attrs.blockstudio.attributes. Det omfatter blokkens felter og felterne fra matchende udvidelser med de lagernøgler, som valideringen bruger: En gruppe på øverste niveau sætter et præfiks foran sine underordnede felter, anonyme grupper og faner tilføjer intet niveau, og et filfelt tilføjer sin <id>__size-ledsager. Gentagelsesfelter er lister med rækkeobjekter, der har minItems og maxItems fra min og max. additionalProperties er false ved feltlagerets rod og i gentagelsesrækker. Felter med objektværdier, såsom links og tilpassede objekter, kan have deres egne metadata. En blok uden felter har ingen properties, så kun et tomt objekt matcher.

Hvert felt beskrives i en kanonisk form, der accepteres af bs_validate_block():

Felt Skema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block En streng.
number, range Et tal med minimum og maximum fra min og max.
toggle En boolesk værdi.
select, radio, checkbox En valgmulighed eller en liste over valgmuligheder for checkbox og multiple med enum.
color, gradient En streng med enum, når disableCustomColors eller disableCustomGradients er angivet.
token En liste over strenge.
files Et ikke-negativt vedhæftnings-ID som heltal eller en liste over ID’er med multiple.
link Et objekt med url, title og opensInNewTab; url er påkrævet.
icon Et objekt med set, subSet og icon; set og icon er påkrævet.
attributes En liste over objekter med en ikke-tom attribute og en skalær value.
repeater En liste over rækkeobjekter.
Tilpassede felttyper Deres registrerede attributtype.

enum viser de valgmuligheder, som valideringen kontrollerer: statiske valgmuligheder og valgmuligheder fra populate, der allerede er opløst ved registrering. Fjernbaserede fetch-valgmuligheder og populate-argumenter, der indeholder {attributes.*}, har ingen enum. En nøgle med definitioner, der har forskellige lagerformer, udelades, fordi valideringen rapporterer alle værdier, der er gemt under den. Når et blokfelt og et udvidelsesfelt deler en nøgle, viser enum de værdier, som begge accepterer. Delte gentagelsesfelter kombinerer deres underordnede felter og anvender de strengeste rækkebegrænsninger fra begge definitioner. I gentagelsesrækker gælder det første felt med et matchende ID i hver kilde, som ved rendering. Et eksplicit felt med navnet <id>__size har forrang frem for en automatisk tilføjet ledsager for filstørrelse.

Når et lukket felt ikke har tilgængelige valgmuligheder, eller to relevante sæt valgmuligheder ikke har noget overlap, er dets kanoniske værdi null ved et enkelt valg eller en tom liste ved flere valg. En tom liste over valgmuligheder gør ikke feltet ubegrænset. Fjernbaserede valg og attributafhængige valg forbliver åbne.

Et felts label bliver til title, dets help bliver til description, og dets default bevares som en annotation. Skemaets eget title er bloktitlen. Felter er aldrig påkrævede, og betinget logik indgår ikke i skemaet.

Begrænsningerne bruger kun nøgleord, som rest_validate_value_from_schema() kontrollerer, så skemaet kan bruges direkte som inputskema for en REST-rute eller en ability:

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

Skemaet beskriver én formular pr. felt; valideringen accepterer også importerede strukturer som optionsobjekter, numeriske strenge og ID-objekter. Det erstatter ikke bs_validate_block(): konflikter i definitioner er konfigurationsproblemer og kan stadig give fund, selv når den konfliktende nøgle udelades. Valideringsfiltre kan også håndhæve webstedsspecifikke regler. Brug bs_validate_block() til at kontrollere gemt indhold. Websteder med en tilpasset resolver ved rendering kan tilpasse skemaet med filteret blockstudio/blocks/attributes/schema.

PHP funktioner

Uden data

I den enkleste form modtager funktionen en enkelt værdi, som er ID’et på den blok, der skal renderes på siden.

PHP
bs_render_block('blockstudio/cta');

Med data

Hvis blokken skal renderes med tilpassede data, skal du bruge et array i stedet for en enkelt værdi som første parameter. Værdien i data-nøglen sendes til variablen $attributes og $a i din blokskabelon.

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

Indlejring

Blokke kan indlejres i hinanden ved hjælp af funktionen bs_block sammen med den nyttige variabel $content i dine blokskabeloner.

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

Knappen renderes i stedet for variablen $content i blokskabelonen.

Indlejrede blokke, der renderes med bs_render_block() eller bs_block(), udsender altid frontend-afklaret HTML, også når den overordnede blok aktuelt renderer en editorforhåndsvisning. Skabelonens pseudokomponenter som <RichText /> og <InnerBlocks /> afklares, før den indlejrede blok returneres.

Flere pladser

Du kan også oprette flere indholdspladser ved at gøre variablen $content til et associativt array og kalde de relevante nøgler i funktionen 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']
    ])
  ]
]);

Bloktags

Indlejr enhver blok med syntaksen for tagget HTML. To formater understøttes:

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

Begge gengiver den samme blok. Syntaksen <bs:> gør en bindestreg til namespaceskilletegn (acme-hero bliver til acme/hero). Bindestreger afprøves fra venstre mod højre, og den første registrerede kandidat bruges, så namespaces med bindestreger også finder den rette blok: <bs:acme-ui-button> afprøver acme/ui-button og derefter acme-ui/button. Syntaksen <block> angiver hele bloknavnet som en attribut af typen name.

Både Blockstudio-blokke og kerneblokkene WordPress fungerer. Blockstudio-blokke renderes gennem hele pipelinen (skabeloner, Tailwind, aktiver). Kerneblokke renderes gennem WordPresss blokrenderingssystem med de indbyggede blokrenderere.

Sådan fungerer det

Bloktags opfører sig forskelligt alt efter, hvor de forekommer:

I blokskabeloner og indhold, erstattes tags under kørsel med renderet HTML. Outputtet er den endelige markup for den refererede blok, indlejret direkte på siden. Der findes ingen WordPress-blok i editoren for disse. De bruges udelukkende til rendering.

I Pages, Patterns, and Site Templates, konverteres tags til native WordPress-blokke, før filkilden synkroniseres eller registreres med WordPress. Det betyder, at blokkene vises i editoren, kan redigeres, hvor målet understøtter redigering, og gennemgår hele WordPresss bloklivscyklus. Tagsyntaksen er en kortform til at definere blokindhold i skabelonfiler.

Denne forskel er vigtig: bloktags i skabeloner producerer output, mens bloktags på sider, i mønstre og i Site Templates producerer native blokke.

I blokskabeloner

Bloktags renderes automatisk i skabeloner af typen Twig og PHP. Ingen indstilling er nødvendig. Det omfatter også syntakserne <bs:> og <block> samt alle registrerede præfiks– og aliastags, så en skabelon kan udsende dem direkte i stedet for at kalde bs_render_block(). Outputtet renderes HTML og indlejres direkte i blokkens skabelonoutput:

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>

I indhold

Rendering på sideniveau (indhold og widgetområder) er valgfri:

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

Eller via et filter:

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

Syntaks

Tags uden afslutning:

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

Parrede tags med indhold imellem:

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>

Du kan frit blande syntakserne. Begge kan indlejres i hinanden:

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>

Præfiksforkortelser

Bloktags kan også bruge projektspecifikke præfiksforkortelser. Registrer et præfiks med ét eller flere namespaces, så løser Blockstudio <prefix-slug> til den første registrerede blok i den rækkefølge, namespaces er angivet:

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

Med eksemplet ovenfor løses <theme-card> til theme-components/card, <theme-button> falder tilbage på bsui/button, hvis theme-components/button ikke er registreret, og <theme-ui-feature-matrix> løses til theme-components/ui-feature-matrix.

Præfikser kan også kombineres. Hvis et tag med præfiks ikke løses direkte, og resten af sluggen selv er et registreret tag med præfiks, gentages løsningen rekursivt, så et brandpræfiks kan ligge oven på et namespacepræfiks:

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> har ingen theme-components/ui-input-blok, så løsningen fortsætter med præfikset ui og finder bsui/input. Direkte match har altid forrang for indlejret løsning, og tilladelses- og afvisningsregler gælder for den endeligt fundne blok.

Du kan også konfigurere præfikser i blockstudio.json:

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

Præfikser skal bestå af små bogstaver eller tal, begynde med et bogstav og må ikke indeholde bindestreger. Eksplicitte aliasser fra blockstudio/block_tags/tag_aliases har forrang for præfiksløsning. Ukendte tags med præfiks efterlades uændrede.

Præfiks- og aliastags understøttes fortsat som praktiske hjælpemidler til redigering. Den kanoniske, portable stavemåde er altid <bs:namespace-slug>, fordi den angiver det faktiske bloknavn uden at afhænge af projektfiltre:

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

Blockstudio-eksempler, genererede diagnosticeringer og programmatisk output bruger denne kanoniske stavemåde. Projekter, der vil fjerne en ældre forkortelse, kan bruge den selvstændige migration til kanoniske tags, som først foretager en prøvekørsel, uden at starte WordPress.

Kerneblokke

Enhver blok med en registreret renderer kan bruges:

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>

Eller med syntaksen <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>

Tilladelses- og afvisningslister

Styr, hvilke blokke der kan renderes via tags:

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

allow begrænser til matchende mønstre. deny udelukker matchende mønstre og har forrang. Begge understøtter *-jokertegn via fnmatch(). De gælder for begge syntakser og både rendering på skabelon- og sideniveau.

Filtre: blockstudio/block_tags/allow og blockstudio/block_tags/deny.

Videregivelse af HTML

Attributter med præfikset data- videregives til det renderede elements rodelement. Attributter med præfikset html- videregives også, men præfikset fjernes. Fungerer med begge syntakser. En videregivet attribut erstatter rodelementets eksisterende værdi i stedet for at blive flettet sammen med den, så html-class erstatter blokkens egne klasser.

En Blockstudio-blok placerer også de globale attributter, den ikke har erklæret som felter, på sit rodelement: id, style, role, title, lang, dir, hidden, tabindex og alle attributter af typen aria-*. Et erklæret felt har altid forrang, så en blok med et felt af typen title modtager i stedet værdien i $a['title']. Videregivne typografier behandles gennem safecss_filter_attr(); filteret WordPress gælder for style-attributter i indhold og føjes til en style, som skabelonen allerede angiver.

Attributværdier er HTML, så entiteter afkodes én gang, når et tag fortolkes: title="Tom &amp; Jerry" når frem til skabelonen som Tom & Jerry og escapes igen i outputtet. Værdier i anførselstegn kan indeholde >, som i varianter af typen Tailwind og animationsvælgere, både i tags uden afslutning og i parrede tags.

Enhver anden attribut, som en blok ikke erklærer, herunder class, når aldrig frem til HTML. Når WP_DEBUG er slået til, rapporterer Blockstudio hver sådan attribut én gang pr. anmodning via _doing_it_wrong(). Erklær et felt for attributten, eller skriv den som en attribut af typen data-, aria- eller 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>

Brugerdefinerede renderere

Registrer brugerdefinerede blokrenderere for flere bloktyper. Renderere modtager et attributarray og en streng med det indre indhold og returnerer et WordPress-blokarray:

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

For containerblokke, der skal fortolke det indre indhold som underblokke, skal du tilføje et andet element i det samme filter:

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 gælder både for bloktags og brugerdefinerede blokke, der vælges via blockstudio/parser/element_mapping. Dette er det rette hook, når en projektblok med elementmapping skal flytte indre tekst til et felt af typen Blockstudio eller opbygge et brugerdefineret blokarray.

blockstudio/block_tags/renderers og blockstudio/parser/renderers modtager samme register og callbackstruktur. De er fortsat tilgængelige af hensyn til kompatibilitet og tilsidesættelser på det sidste parserniveau. Filtrene køres i denne rækkefølge:

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

Et senere filter kan erstatte en renderer, der er registreret af et tidligere filter.

Programmatisk brug

Anvend tagrendering på enhver streng fra PHP:

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

Komponenter

Bloktags fungerer godt sammen med Components. Komponenter er blokke, der kun renderes programmatisk og aldrig vises i editoren.

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

Parser

Bloktags behandles af en letvægtsstrengscanner, der erstatter DOMDocument. Parseren håndterer både syntaksen <bs:> og <block>, indlejrede tags med samme navn ved at holde styr på dybden, attributværdier i anførselstegn og rekursive containerblokke. Den er specialbygget til netop dette brugstilfælde, klarer sig bedre i benchmarks end både DOMDocument og WordPresss WP_HTML_Tag_Processor og undgår DOMDocuments kendte problemer med fjernelse af namespacepræfikser og konvertering af attributnavne til små bogstaver.

For Pages, Patterns, and Site Templates håndterer den samme parser også rå elementer af typen HTML (<p>, <div>, <h1> osv.) og mapper dem til de tilsvarende kerneblokke af typen WordPress.

Når en elementmapping knytter <p> til en registreret blok af typen Blockstudio, der ikke er en kerneblok, og som erklærer en richtext-attribut af typen content, sendes det indre HTML automatisk til attributten content, også for inline-tags som code og img, der er mappet på blokniveau. Et afsnit, hvor eneste underordnede element er et billede, bliver til den blok, som <img> mapper til. Indlejrede bloktags eller blokniveau-HTML behandles stadig med normal fortolkning af indre blokke. <block name="core/shortcode"> beholder sin shortcode-tekst som blokkens indhold.