Programmatisch renderen
Nu Gutenberg steeds belangrijker wordt voor het maken van eenvoudig bewerkbare websites voor klanten, is het logisch om alle benodigde onderdelen van een website als blokken te maken. Deze aanpak is geschikt voor de meeste gebruikers, maar gevorderde gebruikers en specifieke toepassingen kunnen bestaande blokken ook buiten de editor nodig hebben.
Blockstudio biedt twee manieren om blokken programmatisch te renderen:
- PHP-functies:
bs_render_blockenbs_blockom te renderen vanuit PHP-code - HTML-tags:
<bs:block-name>-tags die overal op de pagina worden vervangen door blokuitvoer
Alle functies die specifiek zijn voor Blockstudio, zoals inline stijlen, scripts en begrensde stijlen, worden ondersteund.
Islands werken ook via deze renderpaden. Een dynamisch eiland dat wordt gerenderd met bs_render_block(), bs_block() of een bloktag geeft dezelfde tijdelijke aanduiding terug als een blok dat vanuit berichtinhoud wordt gerenderd. De frontend-runtime wordt geïnjecteerd wanneer die aanduiding aanwezig is in de respons.
Gestructureerde composities en volledige documenten
Gebruik voor langlopende tools, previews, exports en componentgalerijen het geversioneerde Blockstudio\Render API. Het accepteert één declaratie of een geordende
lijst en rendert zonder uitvoer af te drukken:
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'],
]);
De canonieke genormaliseerde declaratie heeft vier sleutels:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers en example zijn handige invoeropties en worden tijdens de normalisatie verwijderd. Geneste declaraties worden recursief verwerkt via dezelfde Blockstudio-pipeline.
Render::document() retourneert schemaVersion, html, body, blocks,
assets, warnings en errors. De waarde assets scheidt head,
footer, styles, scripts, modules, interactivity, ui en tailwind.
De bloklijst en assets bevatten afhankelijkheden waarnaar de geselecteerde templates verwijzen,
maar sluiten niet-gerelateerde assets en assets die alleen voor de editor zijn bedoeld uit.
Volledige documenten kunnen bodyClasses/bodyAttributes instellen en desgewenst de gerenderde body omwikkelen met contentElement, contentClasses en
contentAttributes. De wrapper is beperkt tot een veilige elementnaam; de geretourneerde body blijft de inhoud zonder wrapper.
De opties head en footer voegen vertrouwde documentmarkup toe op hun respectievelijke posities en worden opgenomen in de geretourneerde assetverzameling.
Om een document op te bouwen rond HTML dat al is gerenderd, geef je de bekende namen van de hoofdblokken op:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Gebruik Render::content() voor geserialiseerde WordPress-blokinhoud. Consumers die meerdere onafhankelijke documenten in één verzoek renderen, moeten tussen elk document Blockstudio\Batch_Render::reset() aanroepen; Canvas::documents() doet dit automatisch.
Weergeven buiten de pagina
Blockstudio plaatst een <!--blockstudio/namespace/slug-->-commentaar vóór elk blok dat het weergeeft. Op een frontendpagina leest de buffer deze commentaren om te zien welke blokken aanwezig zijn, laadt hij de bijbehorende assets en verwijdert hij de commentaren voordat het antwoord wordt verzonden.
Uitvoer die niet door die buffer gaat, behoudt de commentaren. Dit geldt voor REST-antwoorden, feeds, AJAX-handlers en HTML die u ergens anders opslaat of na do_blocks(), Render::content() of bs_render_block() ergens anders naartoe stuurt. Gebruik bs_strip_render_markers() om ze te verwijderen:
$html = bs_strip_render_markers(do_blocks($post->post_content));
De functie verwijdert de commentaren van geregistreerde Blockstudio-blokken en laat al het overige ongemoeid, waaronder andere HTML-commentaren. De functie komt overeen met dezelfde markeringen die de paginabuffer verwijdert. Roep de functie aan nadat de blokken zijn geregistreerd (init of later).
Verwijder geen markup die nog op een gebufferde frontendpagina wordt afgedrukt. De pagina heeft de commentaren nodig om te bepalen welke blokassets moeten worden geladen, en Blockstudio verwijdert ze zelf aan het einde.
Het verwijderen van de opmerkingen voegt geen assets toe. Blok-CSS- en JavaScript-bestanden worden
alleen door de paginabuffer geïnjecteerd. Gebruik
bs_block_assets() of
Render::document() wanneer de consumer ze ook nodig heeft.
Blokken inspecteren
Gebruik bs_block_fields() nadat blokken zijn geregistreerd (op init of later) om de opgeloste velddefinities op te halen zonder interne registers te lezen:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
De geretourneerde waarde is de array met geregistreerde velddefinities, inclusief attribuutfilters, uitgebreide aangepaste velden, overschrijvingen en geneste groepen, tabbladen en repeaters. Een Blockstudio-blok zonder velden retourneert []. Het resultaat is een kopie: wijzigingen eraan veranderen het geregistreerde blok niet.
Dit zijn definities, geen opgeslagen waarden. Gebruik bs_validate_block() om opgeslagen markup te valideren, in plaats van een aparte veldwalker bij te houden. Gebruik bs_block_schema() om te beschrijven welke waarden een blok accepteert. Attributen die eigendom zijn van WordPress blijven apart.
Velden die door uitbreidingen zijn toegevoegd, maken geen deel uit van bs_block_fields(). Gebruik bs_block_extension_fields() om ze op te halen. De functie koppelt uitbreidingen aan de hand van de bloknaam en werkt daarom ook voor coreblokken en blokken van derden:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
De geretourneerde waarde bevat de velddefinities van elke overeenkomende uitbreiding, in de volgorde waarin de uitbreidingen zijn geregistreerd, met dezelfde structuur als bs_block_fields(). Voor een blok waarvoor geen uitbreiding geldt, wordt [] geretourneerd. Uitbreidingswaarden worden opgeslagen in hetzelfde attrs.blockstudio.attributes-object als de eigen veldwaarden van het blok, zodat alle ID’s dezelfde naamruimte delen. Als twee uitbreidingen dezelfde ID definiëren, worden beide definities geretourneerd en bewerken ze dezelfde waarde; bij het weergeven geldt de definitie van de uitbreiding die later is geregistreerd.
Gebruik bs_block_values() om de waarden van een opgeslagen blok te lezen zoals de template ze ontvangt.
Gebruik bs_block_assets() om de ontdekte CSS en JavaScript van het blok te inspecteren. Gebruik voor een compleet voorbeelddocument,
inclusief geneste blokken en gedeelde runtime-afhankelijkheden,
Render::document() zoals hierboven beschreven.
Opgeslagen waarden valideren
Gebruik bs_validate_block() nadat blokken zijn geregistreerd (init of later) om programmatisch gegenereerde of geïmporteerde blokattributen te controleren voordat u ze opslaat:
$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.
}
Geef de volledige array attrs door, niet alleen blockstudio.attributes. Een Blockstudio-weergave accepteert ook gedeclareerde velden op het hoogste niveau, en geneste waarden hebben voorrang wanneer beide zijn opgegeven. Uitbreidingen van coreblokken en blokken van derden lezen alleen blockstudio.attributes. Een leeg Blockstudio-blok wordt beheerd en retourneert [], niet null.
Validatie is expliciet en alleen-lezen. Er worden geen templates weergegeven, waarden gewijzigd, berichten opgeslagen, media opgevraagd of invulcallbacks uitgevoerd. Validatie wordt niet automatisch uitgevoerd bij het opslaan, synchroniseren van pagina’s of weergeven. Het is geen sanitizer, autorisatiecontrole of controle of een bijlage bestaat.
Elke bevinding bevat de volgende stabiele sleutels:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Gebruik code, niet het vertaalde message, in tooling. source is block of
extension. Paden gebruiken opslagsleutels en nulgebaseerde indices van repeater-rijen of selecties,
zonder voorafgaande slash. Letterlijke ~ en / in een sleutel worden ge-escapet als ~0 en
~1. Een groep op het hoogste niveau voegt een prefix toe aan de onderliggende velden (cta_title); anonieme groepen
en tabbladen voegen geen niveau toe. Groepen met een ID binnen een andere groep of een repeater
worden niet ondersteund door de builder, dus hun sleutels worden niet geaccepteerd. Berichtvelden
hebben geen opgeslagen waarde. Een bestandsveld staat het bijbehorende veld <id>__size toe.
Aan de root van een Blockstudio-blok zijn boekhoudsleutels en globale HTML-
kenmerken die worden doorgegeven aan het gerenderde element geen onbekende velden. Dit
staat geen willekeurige sleutels in repeater-rijen of uitbreidingen van core-blokken toe.
| Code | Betekenis | expected |
|---|---|---|
unknown_field |
Geen behouden veld declareert deze opslagsleutel. | Bekende opslagsleutels. |
unknown_option |
Een selectie staat niet tussen de bekende opties. | Toegestane optiewaarden. |
wrong_type |
De opgeslagen vorm wordt niet ondersteund door het veld. | Verwachte opslagfamilie of type. |
too_few_rows, too_many_rows |
Een aanwezige repeater valt buiten zijn min of max. |
De rijgrens. |
definition_conflict |
Toepasselijke definities voor één sleutel vereisen verschillende opslagvormen. | Bron en veldtype van elke definitie. |
shadowed_value |
Een geneste waarde overschrijft een andere veldwaarde op het hoogste niveau. | De winnende geneste waarde. |
extension_top_level |
De template kan een waarde op het hoogste niveau lezen, maar bindings van uitbreidingen niet. | Het vereiste pad onder blockstudio/attributes. |
unknown_attribute |
Een sleutel op het hoogste niveau van een Blockstudio-blok wordt niet gelezen door het renderpad en gaat verloren. | Geregistreerde attribuutnamen, uitbreidingsvelden en blockstudio. |
missing_container |
attributes, disabled, name of editor is opgeslagen op het hoogste niveau en blockstudio ontbreekt. |
Het vereiste pad onder blockstudio. |
invalid_container |
blockstudio of blockstudio.attributes is geen object. |
object. |
De melding bij een bevinding van unknown_field noemt de dichtstbijzijnde opslagcode op hetzelfde niveau als die binnen drie bewerkingen valt; de regel voor onbekende instellingen gebruikt: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected vermeldt nog steeds elke bekende code.
Bij het vergelijken wordt geen onderscheid gemaakt tussen hoofdletters en kleine letters, en er wordt alleen gekeken naar opslagcodes uit die container. Meldingen zijn vertaald; integraties moeten code, path en expected gebruiken in plaats van de meldingstekst te ontleden.
Een sleutel op het hoogste niveau van een Blockstudio-blok die geen geregistreerd attribuut is
(de velden ervan, de attributen die WordPress toevoegt voor supports, lock en
metadata), geen veld van een overeenkomende uitbreiding, noch blockstudio, noch een
boekhoudsleutel of doorgegeven HTML-attribuut, wordt verwijderd voordat de template
wordt uitgevoerd. Zo’n sleutel, bijvoorbeeld een verkeerd getypte veld-ID of een waardenobject dat
zonder de wrapper blockstudio is opgeslagen, leidt tot een melding omdat het blok
zonder die waarde wordt gerenderd. Blokken die alleen uitbreidingsvelden bevatten, worden niet
gecontroleerd op sleutels op het hoogste niveau.
De geaccepteerde vormen volgen de rendering: meerdere selecties en selectievakjes kunnen
een lijst, één optieobject of een geïmporteerde scalaire waarde bevatten, waaronder numerieke nul.
Numerieke strings worden geaccepteerd voor getallen. Bestanden kunnen bijlage-ID’s, ID-objecten,
lijsten of stringverwijzingen bevatten. Link- en pictogramwaarden moeten objecten zijn; aangepaste
veldtypen gebruiken het geregistreerde attribuuttype.
Een veld attributes bevat een lijst met paren met een niet-lege naam attribute
en een scalaire waarde value; optionele metadata zoals data.media blijft behouden.
WordPress valideert geregistreerde attributen op het hoogste niveau vóór de rendering, waardoor
een vorm kan worden afgewezen die binnen blockstudio.attributes wordt geaccepteerd. Een
radiowaarde "a" werkt bijvoorbeeld in het geneste object, maar wordt op het hoogste niveau verwijderd,
waar het geregistreerde type object is. Zo’n waarde leidt tot wrong_type.
Gebruik het geneste object voor dezelfde opslagvorm die de editor schrijft.
Ontbrekende velden zijn niet verplicht. Lege geneste waarden (null, false, '',
[]) en uitgeschakelde velden leiden niet tot waardefouten. Een expliciet lege
repeater wordt nog steeds gecontroleerd op min; een ontbrekende of uitgeschakelde repeater niet.
Een lege waarde op het hoogste niveau wordt gemeld als WordPress deze verwijdert en een
niet-standaardwaarde herstelt. Dezelfde waarde in het geneste object kan die wissen.
Conflicten tussen definities worden gemeld, zelfs als de sleutel geen opgeslagen waarde heeft.
Statische opties en opties die bij registratie al zijn opgelost, worden gecontroleerd zonder populate opnieuw aan te roepen. Opties voor externe fetch en populate-argumenten met {attributes.*} worden overgeslagen. Kleur- en verloopwaarden
mogen aangepast zijn, tenzij disableCustomColors of disableCustomGradients is ingesteld.
Dit controleert opgeslagen waarden, niet default, fallback of validatieregels van de editor.
Overeenkomende uitbreidingsvelden worden opgenomen voor elk blok waarop ze van toepassing zijn. Latere
definities winnen binnen het blok of de uitbreidingen ervan op het hoogste niveau, net als bij rendering.
Een eigen veld van een blok en een uitbreidingsveld blijven aparte definities van
dezelfde sleutel en zijn beide van toepassing. Binnen repeater-rijen leest de renderer het
eerste veld met een overeenkomende ID in elke bron; de opties en grenzen daarvan
gelden. Dubbele definities blijven behouden voor conflictdiagnostiek:
onverenigbare opslagvormen leiden tot definition_conflict, zelfs als een
latere dubbele definitie niet wordt gelezen tijdens de rendering.
De functie controleert één blok. Doorloop innerBlocks bij het valideren van een document;
gesynchroniseerde patronen en andere verwijzingen worden niet automatisch uitgebreid. De opdracht
wp bs blocks validate doorloopt de blokken van een of meer berichten en rapporteert hun blokpaden.
Sites met een aangepaste resolver tijdens de rendering kunnen de bevindingen aanpassen zonder de opgeslagen gegevens te wijzigen:
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);
Geef altijd een lijst met bevindingen terug; [] teruggeven accepteert het blok. Dit
filter wordt alleen uitgevoerd voor beheerde blokken, nooit voor het resultaat null.
Opgeslagen waarden beschrijven
Gebruik bs_block_schema() na de blokregistratie (init of later) om de waarden te beschrijven die een blok opslaat, bijvoorbeeld om blockmarkup te genereren in een tool of AI-integratie, of om invoer te controleren in een REST-route:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Het resultaat is een JSON-schema van het object dat is opgeslagen in attrs.blockstudio.attributes. Het omvat de velden van het blok en van overeenkomende extensies, met de opslagcodes die voor validatie worden gebruikt: een groep op het hoogste niveau krijgt een prefix voor de onderliggende velden, anonieme groepen en tabbladen voegen geen niveau toe, en een bestandsveld voegt de bijbehorende <id>__size toe. Repeaters zijn lijsten met rijobjecten met minItems en maxItems uit min en max. additionalProperties is false op het niveau van de veldopslag en in repeaterrijen. Velden met objectwaarden, zoals links en aangepaste objecten, kunnen hun eigen metadata bevatten. Een blok zonder velden heeft geen properties, dus alleen een leeg object komt overeen.
Elk veld wordt beschreven in een canonieke vorm die wordt geaccepteerd door bs_validate_block():
| Veld | Schema |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Een tekenreeks. |
number, range |
Een getal, met minimum en maximum uit min en max. |
toggle |
Een boolean. |
select, radio, checkbox |
Een optiewaarde, of een lijst met optiewaarden voor checkbox en multiple, met enum. |
color, gradient |
Een tekenreeks, met enum wanneer disableCustomColors of disableCustomGradients is ingesteld. |
token |
Een lijst met tekenreeksen. |
files |
Een niet-negatieve bijlage-ID als geheel getal, of een lijst met ID’s met multiple. |
link |
Een object met url, title en opensInNewTab; url is vereist. |
icon |
Een object met set, subSet en icon; set en icon zijn vereist. |
attributes |
Een lijst met objecten met een niet-lege attribute en een scalaire value. |
repeater |
Een lijst met rijobjecten. |
| Aangepaste veldtypen | Hun geregistreerde attribuuttype. |
enum vermeldt de opties die bij validatie worden gecontroleerd: statische opties en opties die bij registratie al zijn opgelost. Externe opties van fetch en invulargumenten met {attributes.*} hebben geen enum. Een code met definities voor verschillende opslagvormen wordt weggelaten, omdat validatie elke waarde rapporteert die eronder is opgeslagen. Wanneer een blokveld en een extensieveld dezelfde code delen, vermeldt enum welke waarden beide accepteren. Gedeelde repeaters combineren hun onderliggende velden en passen de strengste rijgrenzen van beide definities toe. Binnen repeaterrijen geldt, net als bij renderen, het eerste veld met een overeenkomende ID in elke bron. Een expliciet veld met de naam <id>__size heeft voorrang op een automatisch toegevoegd bestandsgrootteveld.
Wanneer een gesloten veld geen beschikbare keuzes heeft, of twee toepasselijke optieverzamelingen geen overlap hebben, is de canonieke waarde null voor een enkele selectie, of een lege lijst voor meerdere selecties. Een lege optielijst maakt een veld niet onbeperkt. Externe en attribuutafhankelijke keuzes blijven open.
De label van een veld wordt title, de help wordt description en de default blijft behouden als annotatie. De eigen title van het schema is de bloktitel. Velden zijn nooit verplicht en voorwaardelijke logica maakt geen deel uit van het schema.
Beperkingen gebruiken alleen trefwoorden die rest_validate_value_from_schema() controleert, zodat het schema direct kan dienen als invoerschema voor een REST-route of een ability:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Het schema beschrijft één formulier per veld; validatie accepteert ook geïmporteerde vormen, zoals optieobjecten, numerieke tekenreeksen en ID-objecten. Het vervangt bs_validate_block() niet: conflicten in definities zijn configuratieproblemen en kunnen nog steeds bevindingen opleveren, zelfs wanneer de conflicterende sleutel is weggelaten. Validatiefilters kunnen ook sitespecifieke regels opleggen. Gebruik bs_validate_block() om opgeslagen inhoud te controleren. Sites met een aangepaste resolver tijdens het renderen kunnen het schema aanpassen met het filter blockstudio/blocks/attributes/schema.
Functies van PHP
Zonder gegevens
In de eenvoudigste vorm accepteert de functie één waarde: de ID van het blok dat op de pagina moet worden gerenderd.
bs_render_block('blockstudio/cta');
Met gegevens
Om het blok met aangepaste gegevens te renderen, moet voor de eerste parameter een array worden gebruikt in plaats van één waarde. De waarde in de data-sleutel wordt doorgegeven aan de variabele $attributes en $a in je bloktemplate.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Nesting
Blokken kunnen in elkaar worden genest met de functie bs_block in combinatie met de krachtige variabele $content in je bloktemplates.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
Het knopblok wordt gerenderd op de plek van de variabele $content in de bloktemplate.
Ingesloten blokken die met bs_render_block() of bs_block() worden gerenderd, geven altijd frontend-geresolveerde HTML terug, zelfs wanneer het bovenliggende blok op dat moment een editorvoorbeeld rendert. Pseudo-componenten in templates, zoals <RichText /> en <InnerBlocks />, worden geresolveerd voordat het ingesloten blok wordt teruggegeven.
Meerdere slots
Je kunt ook meerdere contentslots maken door de variabele $content om te zetten in een associatieve array en de bijbehorende sleutels aan te roepen in de functie bs_block.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
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
Sluit elk blok in met de tagnotatie HTML. Er worden twee indelingen ondersteund:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Beide renderen hetzelfde blok. De <bs:>-syntaxis zet een koppelteken om in het scheidingsteken voor namespaces (acme-hero wordt acme/hero). Koppeltekens worden van links naar rechts geprobeerd en de eerste geregistreerde kandidaat wordt gebruikt. Zo worden ook namespaces met koppeltekens herkend: <bs:acme-ui-button> probeert acme/ui-button en daarna acme-ui/button. De syntaxis <block> gebruikt de volledige bloknaam als een name-attribuut.
Zowel Blockstudio-blokken als coreblokken van WordPress werken. Blockstudio-blokken doorlopen de volledige pipeline (templates, Tailwind, assets). Coreblokken worden gerenderd via het blokrendersysteem van WordPress, met de ingebouwde blokrenderers.
Werking
Bloktags gedragen zich verschillend, afhankelijk van waar ze staan:
In bloktemplates en berichtinhoud worden tags tijdens runtime vervangen door gerenderde HTML. De uitvoer is de uiteindelijke markup van het blok waarnaar wordt verwezen, rechtstreeks ingesloten in de pagina. Hiervoor is geen WordPress-blok in de editor. Het is puur een rendermechanisme.
In Pagina’s, patronen en sitetemplates worden tags omgezet in native WordPress-blokken voordat de bestandsbron wordt gesynchroniseerd of bij WordPress geregistreerd. Dit betekent dat de blokken in de editor verschijnen, bewerkt kunnen worden als het doelsysteem dat ondersteunt en de volledige levenscyclus van blokken in WordPress doorlopen. De tagnotatie is een verkorte manier om blokinhoud in templatebestanden te definiëren.
Dit onderscheid is belangrijk: bloktags in templates produceren uitvoer; bloktags in pagina’s, patronen en sitetemplates produceren native blokken.
In bloktemplates
Bloktags worden automatisch gerenderd in Twig- en PHP-templates. Er is geen instelling nodig. Dit geldt ook voor de syntaxis <bs:> en <block>, evenals voor alle geregistreerde prefix– en aliastags. Een template kan ze dus rechtstreeks uitvoeren in plaats van bs_render_block() aan te roepen. De uitvoer wordt gerenderd HTML en rechtstreeks ingesloten in de uitvoer van de bloktemplate:
<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>
In berichtinhoud
Renderen op paginaniveau (berichtinhoud, widgetgebieden) is optioneel:
{
"blockTags": {
"enabled": true
}
}
Of via een filter:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Syntaxis
Tags die zichzelf sluiten:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Gekoppelde tags met binneninhoud:
<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>
Combineer ze naar wens. Beide syntaxisvormen kunnen in elkaar worden genest:
<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>
Prefixafkortingen
Bloktags kunnen ook projectspecifieke prefixafkortingen gebruiken. Registreer een prefix met een of meer namespaces; Blockstudio koppelt <prefix-slug> vervolgens aan het eerste geregistreerde blok in die namespacevolgorde:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
Met het bovenstaande voorbeeld wordt <theme-card> gekoppeld aan theme-components/card, valt <theme-button> terug op bsui/button wanneer theme-components/button niet is geregistreerd en wordt <theme-ui-feature-matrix> gekoppeld aan theme-components/ui-feature-matrix.
Prefixes kunnen ook worden gecombineerd. Als een tag met prefix niet rechtstreeks wordt gevonden en de resterende slug zelf een geregistreerde tag met prefix is, wordt de zoekopdracht recursief herhaald. Zo kan een merkprefix boven op een namespaceprefix staan:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> heeft geen theme-components/ui-input-blok en valt daarom terug op de prefix ui, die bsui/input oplevert. Rechtstreekse overeenkomsten krijgen altijd voorrang op geneste zoekopdrachten. De regels voor toestaan en weigeren gelden voor het uiteindelijk gevonden blok.
Je kunt prefixes ook configureren in blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Prefixes moeten uit kleine letters of cijfers bestaan, met een letter beginnen en mogen geen koppeltekens bevatten. Expliciete aliassen uit blockstudio/block_tags/tag_aliases hebben voorrang op het zoeken naar prefixes. Onbekende tags met een prefix blijven ongewijzigd.
Prefix- en aliastags blijven handige opties voor auteurs. De canonieke, draagbare schrijfwijze is altijd <bs:namespace-slug>, omdat daarin de echte bloknaam staat en die niet afhankelijk is van projectfilters:
<bs:theme-components-card />
<bs:bsui-input />
Voorbeelden van Blockstudio, gegenereerde diagnostische meldingen en programmatische uitvoer gebruiken deze canonieke schrijfwijze. Projecten die een oudere verkorte schrijfwijze willen verwijderen, kunnen daarvoor de zelfstandige migratie van canonieke tags gebruiken, die eerst een proefuitvoering doet en geen WordPress hoeft te starten.
Coreblokken
Elk blok met een geregistreerde renderer kan worden gebruikt:
<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>
Of met de syntaxis <block>:
<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>
Lijsten met toegestane en geweigerde blokken
Bepaal welke blokken via tags kunnen worden gerenderd:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow beperkt de selectie tot overeenkomende patronen. deny sluit overeenkomende patronen uit en heeft voorrang. Beide ondersteunen *-jokertekens via fnmatch(). Dit geldt voor beide syntaxisvormen en voor renderen op zowel template- als paginaniveau.
Filters: blockstudio/block_tags/allow en blockstudio/block_tags/deny.
Doorgifte van HTML
Attributen met het voorvoegsel data- worden doorgegeven aan het rootelement van het gerenderde blok. Attributen met het voorvoegsel html- worden ook doorgegeven, maar zonder het voorvoegsel. Dit werkt met beide syntaxisvormen. Een doorgegeven attribuut vervangt de bestaande waarde van het rootelement in plaats van deze samen te voegen. html-class vervangt dus de eigen klassen van het blok.
Een Blockstudio-blok plaatst ook de globale attributen die het niet als velden declareert op het rootelement: id, style, role, title, lang, dir, hidden, tabindex en elk attribuut aria-*. Een gedeclareerd veld heeft altijd voorrang. Een blok met een veld title ontvangt dus de waarde in $a['title']. Doorgegeven stijlen worden verwerkt via safecss_filter_attr(). Het filter WordPress geldt voor style-attributen in berichtinhoud. De stijlen worden toegevoegd aan een style die de template al instelt.
Attribuutwaarden zijn HTML. Entiteiten worden dus eenmaal gedecodeerd wanneer een tag wordt geparseerd: title="Tom & Jerry" komt als Tom & Jerry bij de template aan en wordt bij uitvoer opnieuw ge-escaped. Waarden tussen aanhalingstekens kunnen > bevatten, zoals varianten van Tailwind en animatieselectoren, zowel in tags die zichzelf sluiten als in gekoppelde tags.
Elk ander attribuut dat een blok niet declareert, waaronder class, bereikt de HTML nooit. Als WP_DEBUG is ingeschakeld, meldt Blockstudio elk dergelijk attribuut eenmaal per verzoek via _doing_it_wrong(). Declareer hiervoor een veld of schrijf het als attribuut data-, aria- of 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>
Aangepaste renderers
Registreer aangepaste blokrenderers voor extra bloktypen. Renderers ontvangen een attributenarray en een string met de binneninhoud, en geven een WordPress-blokarray terug:
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);
Voeg voor containerblokken die de binneninhoud in onderliggende blokken moeten parseren een tweede item toe aan hetzelfde filter:
$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 geldt voor zowel bloktags als aangepaste blokken die zijn geselecteerd via blockstudio/parser/element_mapping. Dit is de juiste hook wanneer een projectblok met elementmapping binnentekst moet verplaatsen naar een veld Blockstudio of een aangepaste blokarray moet samenstellen.
blockstudio/block_tags/renderers en blockstudio/parser/renderers ontvangen hetzelfde register en dezelfde callbackstructuur. Ze blijven beschikbaar voor compatibiliteit en laatste parseroverschrijvingen. De filters worden in deze volgorde uitgevoerd:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Een later filter kan een renderer vervangen die door een eerder filter is geregistreerd.
Programmatisch gebruik
Pas tagrendering toe op elke string uit PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Componenten
Bloktags werken goed samen met Componenten. Componenten zijn blokken die alleen programmatisch worden gerenderd en nooit in de editor verschijnen.
<bs:mytheme-card title="My Card" description="Card content." />
Parser
Bloktags worden verwerkt door een lichte strings scanner die DOMDocument vervangt. De parser verwerkt zowel de syntaxis <bs:> als <block>, geneste tags met dezelfde naam door de diepte bij te houden, attribuutwaarden tussen aanhalingstekens en recursieve containerblokken. De scanner is speciaal voor dit gebruik ontwikkeld, presteert volgens benchmarks beter dan zowel DOMDocument als de WP_HTML_Tag_Processor van WordPress en vermijdt bekende problemen van DOMDocument met het verwijderen van namespaceprefixes en het omzetten van attribuutnamen naar kleine letters.
Voor Pagina’s, patronen en sitetemplates verwerkt dezelfde parser ook ruwe elementen HTML (<p>, <div>, <h1> enzovoort) en koppelt die aan de bijbehorende coreblokken van WordPress.
Wanneer een elementmapping <p> koppelt aan een geregistreerd niet-coreblok van Blockstudio dat een attribuut content voor richtext declareert, wordt de binneninhoud van HTML automatisch naar dat attribuut content geleid. Dit geldt ook voor inline-tags zoals code en img die op blokniveau aan elementen zijn gekoppeld. Een alinea met alleen een afbeelding als onderliggend element wordt het blok waaraan <img> is gekoppeld. Geneste bloktags en blokniveau-HTML gebruiken nog steeds de normale parsing van binnenblokken. <block name="core/shortcode"> behoudt de shortcode-tekst als blokinhoud.