Programmatisk återgivning
Eftersom Gutenberg har blivit det främsta verktyget för att skapa webbplatser som kunder enkelt kan redigera, är det rimligt att skapa alla nödvändiga delar av webbplatsen som block. Den här metoden passar de flesta, men avancerade användare och särskilda användningsfall kan kräva att befintliga block används utanför redigeraren.
Blockstudio tillhandahåller två metoder för att återge block programmatiskt:
- Funktioner i PHP:
bs_render_blockochbs_blockför återgivning från kod i PHP - Taggar i HTML: taggar i
<bs:block-name>som ersätts med blockets utdata var som helst på sidan
Alla specifika funktioner i Blockstudio, som inline-stilar, skript och avgränsade stilar, stöds.
Öar fungerar också med dessa återgivningsvägar. En dynamisk ö som
återges med bs_render_block(), bs_block() eller en blocktagg returnerar
samma platshållarmarkör som ett block som återges från inläggsinnehåll, och
gränssnittskörningen för frontend läggs till när markören finns i svaret.
Strukturerade sammansättningar och fullständiga dokument
För verktyg, förhandsvisningar, exporter och komponentgallerier med lång livslängd använder du det versionshanterade Blockstudio\Render API. Det tar emot en deklaration eller en ordnad lista och återger utan att skriva ut:
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 kanoniska normaliserade deklarationen har fyra nycklar:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers och example är indataalternativ som normaliseras bort. Nästlade deklarationer återges rekursivt genom samma pipeline för Blockstudio.
Render::document() returnerar schemaVersion, html, body, blocks,
assets, warnings och errors. Värdet assets skiljer mellan head,
footer, styles, scripts, modules, interactivity, ui och tailwind.
Blocklistan och resurserna omfattar beroenden som refereras till av de valda mallarna,
men utesluter orelaterade resurser och resurser som endast används i redigeraren.
Fullständiga dokument kan ange bodyClasses/bodyAttributes och vid behov omsluta
den återgivna body:n med contentElement, contentClasses och
contentAttributes. Omslutningen begränsas till ett säkert elementnamn; det
returnerade body förblir det omslutna, återgivna innehållet.
Alternativen head och footer lägger till betrodd dokumentmarkup på sina
respektive positioner och ingår i den returnerade resursavslutningen.
För att sätta ihop ett dokument runt redan återgiven HTML anger du de kända namnen på rotblocken:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Använd Render::content() för serialiserat innehåll i WordPress-block. Konsumenter som renderar flera oberoende dokument i en begäran bör anropa Blockstudio\Batch_Render::reset() mellan dem; Canvas::documents() gör detta automatiskt.
Rendering utanför sidan
Blockstudio infogar en <!--blockstudio/namespace/slug-->-kommentar framför
varje block som den renderar. På en frontend-sida läser bufferten kommentarerna för att
se vilka block som finns, laddar deras tillgångar och tar bort kommentarerna
innan svaret skickas.
Utdata som inte passerar genom den bufferten behåller kommentarerna. Det gäller
REST-svar, flöden, AJAX-hanterare och HTML som du lagrar eller skickar någon annanstans
efter do_blocks(), Render::content() eller bs_render_block(). Använd
bs_strip_render_markers() för att ta bort dem:
$html = bs_strip_render_markers(do_blocks($post->post_content));
Funktionen tar bort kommentarerna för registrerade Blockstudio-block och lämnar
allt annat orört, inklusive andra HTML-kommentarer. Den matchar samma
markörer som sidbufferten tar bort. Anropa den efter blockregistreringen (init eller senare).
Ta inte bort uppmärkning som fortfarande skrivs ut på en buffrad frontend-sida. Sidan behöver kommentarerna för att veta vilka blocktillgångar som ska laddas, och Blockstudio tar själv bort dem i slutet.
Att ta bort kommentarerna lägger inte till några tillgångar. Blockens CSS- och JavaScript-filer
infogas bara av sidbufferten. Använd
bs_block_assets() eller
Render::document() när även den som använder dem behöver dem.
Granska block
Använd bs_block_fields() efter blockregistreringen (på init eller senare) för att hämta
de lösta fältdefinitionerna utan att läsa interna register:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Returvärdet är den registrerade arrayen med fältdefinitioner, inklusive attributfilter,
utökade anpassade fält, åsidosättningar och nästlade grupper, flikar och
repeaters. Ett Blockstudio-block utan fält returnerar []. Resultatet är en
kopia: ändringar i den påverkar inte det registrerade blocket.
Det här är definitioner, inte sparade värden. Om du vill validera sparad markup använder du bs_validate_block() i stället för att underhålla en separat fältgenomgång. Om du vill beskriva vilka värden ett block accepterar använder du bs_block_schema(). Attribut som ägs av WordPress förblir separata.
Fält som läggs till av tillägg ingår inte i
bs_block_fields(). Använd bs_block_extension_fields() för att hämta dem. Funktionen matchar
tillägg efter blocknamn, så den fungerar även för kärnblock och block från tredje part:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Returvärdet listar fältdefinitionerna för varje matchande tillägg, i
tilläggens registreringsordning och med samma struktur som
bs_block_fields(). Ett block som inget tillägg matchar returnerar []. Tilläggens
värden sparas i samma attrs.blockstudio.attributes-objekt som
blockets egna fältvärden, så alla id:n delar samma namnrymd. Om två tillägg
definierar samma id returneras båda definitionerna och de redigerar samma värde. Vid
rendering gäller definitionen från det tillägg som registrerades sist.
Använd
bs_block_values() för att läsa värdena för ett sparat block så som dess mall tar emot dem.
Använd bs_block_assets() för att
granska blockets upptäckta CSS och JavaScript. Om du vill ha ett fullständigt förhandsvisningsdokument,
inklusive nästlade block och delade körningsberoenden, använder du Render::document() enligt beskrivningen ovan.
Validera lagrade värden
Använd bs_validate_block() efter blockregistreringen (init eller senare) för att kontrollera
programmatiskt genererade eller importerade blockattribut innan du sparar dem:
$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.
}
Skicka in hela arrayen med attrs, inte bara blockstudio.attributes. En
Blockstudio-rendering godtar även deklarerade fält på toppnivå,
och nästlade värden prioriteras om båda anges. Tillägg till kärnblock och block från tredje part
läser bara blockstudio.attributes. Ett tomt Blockstudio-block är
hanterat och returnerar [], inte null.
Valideringen är uttrycklig och skrivskyddad. Den renderar inte mallar, ändrar värden, sparar inlägg, söker efter media eller kör återanropsfunktioner för ifyllnad. Den körs inte automatiskt när du sparar, synkroniserar sidor eller renderar. Den är inte en sanerare, en behörighetskontroll eller en kontroll av om en bilaga finns.
Varje resultat innehåller följande stabila nycklar:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Använd code, inte den översatta message, i verktyg. source är block eller
extension. Sökvägar använder lagringsnycklar och nollbaserade index för
repeater-rader eller val, utan inledande snedstreck. Bokstavliga ~ och / i en nyckel
escapas som ~0 och ~1. En grupp på toppnivå lägger till ett prefix på sina underordnade fält (cta_title); anonyma grupper
och flikar lägger inte till någon nivå. Grupper med ett ID inuti en annan grupp eller en repeater
stöds inte av byggverktyget, så deras nycklar godtas inte. Meddelandefält har inget lagrat värde. Ett filfält tillåter sin
<id>__size-motsvarighet. Vid roten av ett Blockstudio-block räknas nycklar för intern hantering och globala HTML-
attribut som vidarebefordras till det renderade elementet inte som okända fält. Detta
tillåter inte godtyckliga nycklar i repeater-rader eller utökningar av kärnblock.
| Kod | Betydelse | expected |
|---|---|---|
unknown_field |
Inget fält som behållits deklarerar den här lagringsnyckeln. | Kända lagringsnycklar. |
unknown_option |
Ett val finns inte bland de kända alternativen. | Tillåtna alternativvärden. |
wrong_type |
Den lagrade strukturen stöds inte av fältet. | Förväntad lagringsfamilj eller typ. |
too_few_rows, too_many_rows |
En repeater som finns ligger utanför sitt min eller max. |
Radgränsen. |
definition_conflict |
Tillämpliga definitioner för en nyckel kräver olika lagringsstrukturer. | Källa och fälttyp för varje definition. |
shadowed_value |
Ett nästlat värde åsidosätter ett annat fältvärde på toppnivå. | Det vinnande nästlade värdet. |
extension_top_level |
Mallen kan läsa ett värde på toppnivå, men bindningar för utökningar kan inte det. | Den obligatoriska sökvägen under blockstudio/attributes. |
unknown_attribute |
En nyckel på toppnivå i ett Blockstudio-block läses inte av renderingssökvägen och tas bort. | Registrerade attributnamn, utökningsfält och blockstudio. |
missing_container |
attributes, disabled, name eller editor lagras på toppnivå och blockstudio saknas. |
Den obligatoriska sökvägen under blockstudio. |
invalid_container |
blockstudio eller blockstudio.attributes är inte ett objekt. |
object. |
Meddelandet för en unknown_field-träff anger den närmaste lagringsnyckeln på samma nivå, om den ligger inom tre ändringar, vilket är regeln som okända inställningar använder: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected listar fortfarande alla kända nycklar.
Matchningen ignorerar skiftlägeskänslighet och tar bara hänsyn till lagringsnycklar i den behållaren. Meddelanden översätts; integrationer bör använda code, path och expected i stället för att tolka meddelandetexten.
En nyckel på toppnivå i ett Blockstudio-block som varken är ett registrerat attribut
(dess fält, attributen som WordPress lägger till för supports, lock och
metadata), ett fält i en matchande utökning, blockstudio, en nyckel för intern hantering eller ett vidarebefordrat HTML-attribut tas bort innan mallen
körs. En sådan nyckel, till exempel ett felstavat fält-ID eller ett värdeobjekt som lagrats
utan sin blockstudio-omslutning, ger en träff eftersom blocket
renderas utan värdet. Block som bara innehåller utökningsfält kontrolleras inte för nycklar på toppnivå.
De godtagna strukturerna följer renderingen: flervalsfält och kryssrutor kan
innehålla en lista, ett alternativobjekt eller en importerad skalär, inklusive numeriskt
noll. Numeriska strängar godtas för tal. Filer kan innehålla bilage-ID:n, ID-objekt, listor eller strängreferenser. Länk- och ikonvärden måste vara objekt; anpassade fälttyper använder sin registrerade attributtyp.
Ett attributes-fält innehåller en lista med par med ett icke-tomt namn för attribute
och ett skalärt värde för value; valfria metadata som data.media bevaras.
WordPress validerar registrerade attribut på toppnivå före rendering, vilket
kan avvisa en struktur som godtas inuti blockstudio.attributes. Till exempel fungerar ett
radiovärde på "a" i det nästlade objektet, men tas bort på toppnivå,
där dess registrerade typ är object. Ett sådant värde ger wrong_type.
Använd det nästlade objektet för samma lagringsstruktur som redigeraren skriver.
Fält måste inte finnas. Tomma nästlade värden (null, false, '',
[]) och inaktiverade fält ger inga värdefel. En uttryckligen tom
repeater kontrolleras ändå mot min; en repeater som saknas eller är inaktiverad gör det inte.
Ett tomt värde på toppnivå rapporteras om WordPress tar bort det och återställer ett
icke-tomt standardvärde i stället. Samma värde i det nästlade objektet kan rensa det.
Definitionskonflikter rapporteras även när nyckeln saknar sparat värde.
Statiska alternativ och alternativ som hämtats in och lösts vid registreringen
kontrolleras utan att hämtningsfunktionen anropas igen. Alternativ från fjärranslutna fetch och hämtningsargument som innehåller {attributes.*} hoppas över. Färg- och gradientvärden
kan vara anpassade om inte disableCustomColors eller disableCustomGradients har angetts.
Det här kontrollerar lagrade värden, inte default, fallback eller redigerarens valideringsregler.
Matchande utökningsfält tas med för varje block de gäller för. Senare
definitioner vinner inom blocket eller dess utökningar på rotnivå, precis som vid rendering.
Blockets eget fält och ett utökningsfält är separata definitioner av
samma nyckel, och båda gäller. I repeater-rader läser renderaren det
första fältet med ett matchande ID från varje källa, så dess alternativ och gränser
gäller. Dubbla definitioner behålls för konfliktdiagnostik:
oförenliga lagringsstrukturer ger definition_conflict, även när en
senare dubblett inte läses vid rendering.
Funktionen kontrollerar ett block. Gå igenom innerBlocks när du validerar ett dokument;
synkroniserade mönster och andra referenser expanderas inte automatiskt. Kommandot
wp bs blocks validate går igenom blocken i ett eller flera inlägg och rapporterar deras blocksökvägar.
Webbplatser med en anpassad resolver vid rendering kan anpassa resultaten utan att ändra lagrade data:
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);
Returnera alltid en lista med resultat; om du returnerar [] godtas blocket. Filtret
körs endast för hanterade block, aldrig för resultatet från null.
Beskriva lagrade värden
Använd bs_block_schema() efter blockregistrering (init eller senare) för att beskriva värdena som ett block lagrar, till exempel för att generera blockmarkup i ett verktyg eller en AI-integration, eller kontrollera indata i en REST-rutt:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Resultatet är ett JSON-schema för objektet som sparas i attrs.blockstudio.attributes. Det omfattar blockets fält och fälten från matchande utökningar, med de lagringsnycklar som valideringen använder: en grupp på toppnivå ger sina underordnade fält ett prefix, namnlösa grupper och flikar tillför ingen nivå, och ett filfält lägger till sin motsvarighet <id>__size. Repeaterfält är listor med radobjekt som har minItems och maxItems från min och max. additionalProperties är false vid fältlagringens rot och i repeaterfältens rader. Fält med objektvärden, som länkar och anpassade objekt, kan ha egna metadata. Ett block utan fält har ingen properties, så endast ett tomt objekt matchar.
Varje fält beskrivs i en kanonisk form som accepteras av bs_validate_block():
| Fält | Schema |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
En sträng. |
number, range |
Ett tal, med minimum och maximum från min och max. |
toggle |
Ett booleskt värde. |
select, radio, checkbox |
Ett alternativvärde, eller en lista med alternativvärden för checkbox och multiple, med enum. |
color, gradient |
En sträng, med enum när disableCustomColors eller disableCustomGradients är inställt. |
token |
En lista med strängar. |
files |
Ett icke-negativt ID för en bilaga, eller en lista med ID:n med multiple. |
link |
Ett objekt med url, title och opensInNewTab; url krävs. |
icon |
Ett objekt med set, subSet och icon; set och icon krävs. |
attributes |
En lista med objekt som har ett icke-tomt attribute och ett skalärt value. |
repeater |
En lista med radobjekt. |
| Anpassade fälttyper | Deras registrerade attributtyp. |
enum listar alternativen som valideringen kontrollerar: statiska alternativ och ifyllda alternativ som redan har lösts vid registreringen. Alternativ från fjärrkällor i fetch och ifyllnadsargument som innehåller {attributes.*} saknar enum. En nyckel med definitioner som har olika lagringsformer utelämnas, eftersom valideringen rapporterar alla värden som lagras under den. När ett blockfält och ett utökningsfält delar en nyckel listar enum de värden som båda accepterar. Delade repeaterfält kombinerar sina underordnade fält och tillämpar de striktare radgränserna från båda definitionerna. I repeaterfältens rader används det första fältet med ett matchande ID från varje källa, precis som vid rendering. Ett uttryckligt fält med namnet <id>__size har företräde framför en automatiskt tillagd motsvarighet för filstorlek.
När ett låst fält saknar tillgängliga alternativ, eller två tillämpliga alternativuppsättningar saknar överlappning, är det kanoniska värdet null vid ett enda val eller en tom lista vid flera val. En tom lista med alternativ gör inte fältet obegränsat. Alternativ från fjärrkällor och attributberoende alternativ förblir öppna.
Ett fälts label blir title, dess help blir description och dess default behålls som en anteckning. Schemat har blockets titel som sitt eget title. Fält är aldrig obligatoriska, och villkorslogik ingår inte i schemat.
Begränsningarna använder bara nyckelord som rest_validate_value_from_schema() kontrollerar, så schemat fungerar direkt som indataschema för en REST-rutt eller en förmåga:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Schemat beskriver ett formulär per fält; valideringen godtar även importerade former som alternativobjekt, numeriska strängar och ID-objekt. Det ersätter inte bs_validate_block(): definitionskonflikter är konfigurationsproblem och kan fortfarande ge träffar även när den konfliktande nyckeln utelämnas. Valideringsfilter kan också införa platsspecifika regler. Använd bs_validate_block() för att kontrollera lagrat innehåll. Webbplatser med en anpassad resolver vid rendering kan anpassa schemat med filtret blockstudio/blocks/attributes/schema.
PHP-funktioner
Utan data
I sin enklaste form tar funktionen emot ett enda värde, som är ID:t för blocket som ska renderas på sidan.
bs_render_block('blockstudio/cta');
Med data
Om blocket ska renderas med anpassade data måste den första parametern vara en array i stället för ett enskilt värde. Värdet i nyckeln data skickas till variabeln $attributes och $a i blockmallen.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Nästling
Block kan nästlas i varandra med funktionen bs_block tillsammans med den kraftfulla variabeln $content i blockmallarna.
<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',
]
])
]);
Knappblocket renderas i stället för variabeln $content i blockmallen.
Inbäddade block som renderas med bs_render_block() eller bs_block() skriver alltid ut frontend-upplöst HTML, även när föräldrablocket renderar en förhandsvisning i redigeraren. Pseudokomponenter för mallar, som <RichText /> och <InnerBlocks />, löses upp innan det inbäddade blocket returneras.
Flera platser
Det går också att skapa flera innehållsplatser genom att göra variabeln $content till en associativ array och anropa motsvarande nycklar i funktionen 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']
])
]
]);
Blocktaggar
Bädda in valfritt block med taggsyntaxen HTML. Två format stöds:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Båda renderar samma block. Syntaxen <bs:> omvandlar ett bindestreck till namnrymdsavgränsaren (acme-hero blir acme/hero). Bindestrecken prövas från vänster till höger, och den första registrerade kandidaten används. Därför fungerar även namnrymder med bindestreck: <bs:acme-ui-button> prövar acme/ui-button och därefter acme-ui/button. Syntaxen <block> tar hela blocknamnet som ett attribut för name.
Både Blockstudio-block och kärnblock från WordPress fungerar. Blockstudio-block går genom hela bearbetningskedjan (mallar, Tailwind, tillgångar). Kärnblock renderas via blockrenderingssystemet i WordPress med de inbyggda blockrenderarna.
Så fungerar det
Blocktaggar fungerar olika beroende på var de förekommer:
I blockmallar och inläggsinnehåll ersätts taggar med renderade HTML vid körning. Utdata är den slutliga uppmärkningen för det refererade blocket, inbäddad direkt på sidan. Det finns inget WordPress-block för dessa i redigeraren. De är endast en renderingsmekanism.
I Sidor, mönster och webbplatsmallar omvandlas taggar till inbyggda WordPress-block innan filkällan synkroniseras eller registreras med WordPress. Det innebär att blocken visas i redigeraren, kan redigeras där målet stöder redigering och följer hela blocklivscykeln i WordPress. Taggsyntaxen är en genväg för att definiera blockinnehåll i mallfiler.
Den här skillnaden spelar roll: blocktaggar i mallar genererar utdata, medan blocktaggar på sidor, i mönster och i webbplatsmallar skapar inbyggda block.
I blockmallar
Blocktaggar renderas automatiskt i Twig- och PHP-mallar. Ingen inställning behövs. Detta omfattar syntaxerna <bs:> och <block> samt alla registrerade taggar med prefixet prefix och alias-taggar, så en mall kan återge dem direkt i stället för att anropa bs_render_block(). Utdata återges HTML inbäddade direkt i blockets mallutdata:
<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 inläggsinnehåll
Renderingen på sidnivå (inläggsinnehåll, widgetområden) är valfri:
{
"blockTags": {
"enabled": true
}
}
Eller via ett filter:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Syntax
Självstängande taggar:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Parade taggar med inre innehåll:
<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>
Blanda fritt. Båda syntaxerna kan nästlas i varandra:
<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>
Prefixgenvägar
Blocktaggar kan också använda projektspecifika prefixgenvägar. Registrera ett prefix med en eller flera namnrymder, så löser Blockstudio upp <prefix-slug> till det första registrerade blocket i den ordningen:
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 />
Med exemplet ovan löses <theme-card> upp till theme-components/card, <theme-button> faller tillbaka på bsui/button när theme-components/button inte är registrerat, och <theme-ui-feature-matrix> löses upp till theme-components/ui-feature-matrix.
Prefix kan också kombineras. Om en tagg med prefix inte löses upp direkt och den återstående sluggen själv är en registrerad tagg med prefix, fortsätter upplösningen rekursivt. Då kan ett varumärkesprefix ligga ovanpå ett namnrymdsprefix:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> har inget theme-components/ui-input-block och faller därför vidare till prefixet ui, som löser upp bsui/input. Direkta matchningar prioriteras alltid framför nästlad upplösning, och reglerna för tillåtna och nekade block gäller det slutligt upplösta blocket.
Du kan också konfigurera prefix i blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Prefix måste bestå av gemener eller siffror, börja med en bokstav och får inte innehålla bindestreck. Uttryckliga alias från blockstudio/block_tags/tag_aliases har företräde framför prefixupplösning. Okända taggar med prefix lämnas orörda.
Taggar med prefix och alias stöds fortfarande som praktiska hjälpmedel vid redigering. Den kanoniska, portabla stavningen är alltid <bs:namespace-slug>, eftersom den anger det verkliga blocknamnet utan att vara beroende av projektfilter:
<bs:theme-components-card />
<bs:bsui-input />
Exempel med Blockstudio, genererad diagnostik och programmatiska utdata använder denna kanoniska stavning. Projekt som vill ta bort en äldre kortform kan använda den fristående, torrkörningsbaserade kanoniska taggmigreringen utan att starta WordPress.
Kärnblock
Alla block med en registrerad renderare kan användas:
<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 syntaxen <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>
Listor över tillåtna och nekade block
Styr vilka block som kan renderas via taggar:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow begränsar till enbart matchande mönster. deny utesluter matchande mönster och har företräde. Båda stöder jokertecknet * via fnmatch(). Dessa gäller för båda syntaxerna och för rendering på både mall- och sidnivå.
Filter: blockstudio/block_tags/allow och blockstudio/block_tags/deny.
Genomsläpp för HTML
Attribut med prefixet data- skickas vidare till det renderade blockets rotelement. Attribut med prefixet html- skickas också vidare, men prefixet tas bort. Fungerar med båda syntaxerna. Ett attribut som skickas vidare ersätter rotelementets befintliga värde i stället för att slås ihop med det, så html-class ersätter blockets egna klasser.
Ett Blockstudio-block placerar också de globala attribut som det inte deklarerar som fält på sitt rotelement: id, style, role, title, lang, dir, hidden, tabindex och varje attribut av typen aria-*. Ett deklarerat fält har alltid företräde, så ett block med ett title-fält får i stället värdet i $a['title']. Vidarebefordrade stilar går via safecss_filter_attr(); filtret WordPress tillämpas på stilattribut i inläggsinnehåll och läggs till en stil som mallen redan anger.
Attributvärden är HTML, så entiteter avkodas en gång när en tagg tolkas: title="Tom & Jerry" når mallen som Tom & Jerry och escapes igen vid utmatning. Citerade värden kan innehålla >, vilket används av varianter av Tailwind och animeringsväljare, både i självstängande och parade taggar.
Alla andra attribut som ett block inte deklarerar, däribland class, når aldrig HTML. När WP_DEBUG är aktiverat rapporterar Blockstudio varje sådant attribut en gång per begäran via _doing_it_wrong(). Deklarera ett fält för attributet eller skriv det som ett attribut av typen data-, aria- eller 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>
Anpassade renderare
Registrera anpassade blockrenderare för ytterligare blocktyper. Renderare tar emot en attributarray och en sträng med inre innehåll och returnerar en WordPress-blockarray:
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);
För behållarblock som behöver tolka det inre innehållet till underordnade block, lägg till en andra post i samma 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 gäller både blocktaggar och anpassade block som valts via blockstudio/parser/element_mapping. Detta är rätt krok när ett projektblock med elementmappning behöver flytta inre text till ett Blockstudio-fält eller skapa en anpassad blockarray.
blockstudio/block_tags/renderers och blockstudio/parser/renderers får samma register och återanropsformat. De finns kvar för kompatibilitet och slutliga åsidosättningar på parsernivå. Filtren körs i denna ordning:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Ett senare filter kan ersätta en renderare som registrerats av ett tidigare filter.
Programmatisk användning
Tillämpa taggrendering på valfri sträng från PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Komponenter
Blocktaggar passar bra ihop med Komponenter. Komponenter är block som endast renderas programmatiskt och aldrig visas i redigeraren.
<bs:mytheme-card title="My Card" description="Card content." />
Parser
Blocktaggar bearbetas av en lättviktig strängskanner som ersätter DOMDocument. Parsern hanterar både syntaxen <bs:> och <block>, nästlade taggar med samma namn genom djupspårning, citerade attributvärden och rekursiva behållarblock. Den är specialbyggd för detta användningsfall, presterar bättre i riktmärken än både DOMDocument och WordPresss WP_HTML_Tag_Processor, och undviker kända problem i DOMDocument med borttagning av namnrymdsprefix och omvandling av attributnamn till gemener.
För Sidor, mönster och webbplatsmallar hanterar samma parser också råa element av typen HTML (<p>, <div>, <h1> osv.) och mappar dem till motsvarande kärnblock i WordPress.
När en elementmappning pekar ut <p> till ett registrerat block utanför kärnan av typen Blockstudio som deklarerar ett richtext-attribut content, skickas det inre innehållet HTML automatiskt till det attributet content, inklusive infogade taggar som code och img som elementmappas på blocknivå. Ett stycke vars enda underordnade element är en bild blir det block som <img> mappar till. Nästlade blocktaggar eller blockelement av typen HTML använder fortfarande den vanliga tolkningen av inre block. <block name="core/shortcode"> behåller sin kortkodstext som blockets innehåll.