Tillägg
Med tillägg kan du utöka valfritt registrerat block i din WordPress-installation med hjälp av en enkel .json-baserad API, som liknar konfigurationen för block.json. Detta omfattar kärnblock, block från tredje part och block som skapats med Blockstudio.
Alla fältstyper kan läggas till i valfritt block, och data sparas i blockets attribut. Hela funktionsuppsättningen för attribut, till exempel filtrering, inaktivering, villkorslogik och ifyllning av alternativ, är tillgänglig för tillägg.
Tilläggstyper
Utökade värden kan användas på många olika sätt:
- class: Lägg till en klass i blocket med attributvärdet
- style: Lägg till inline-format i blocket med attributvärdet
- attributes: Ange valfritt attributvärde direkt på blocket
- data attributes: Använd tilläggsvärden för att ange specifika dataattribut
Konfiguration
Föreställ dig följande scenario: du vill lägga till ett anpassat fält select för klass i varje kärnblock. Allt du behöver göra är att lägga till den här filen .json var som helst i blockmappen, så registreras den automatiskt som ett tillägg.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Detta lägger till ett fält customColor i varje kärnblock, så att du kan ange blockets textfärg.
Filnamn
Eftersom det inte finns någon renderingsmall behöver ett tillägg ingen motsvarande fil index och behöver därför inte heta block.json. Det gör att alla tillägg enkelt kan förvaras i en enda mapp. Flera filer kan utöka samma block, till exempel två filer med "name": "core/*"; var och en registrerar sina egna fält.
Schema
Blockstudio tillhandahåller ett anpassat JSON-schema för tilläggskonfigurationer:
Namn
Egenskapen name i konfigurationsobjektet anger vilka block som ska utökas. Det finns tre alternativ beroende på dina behov:
- blockName: Ett enskilt blocknamn, e.g.
core/paragraph - [blockNameA, blockNameB]: En array med blocknamn, e.g.
["core/paragraph", "core/heading"] - core/*: Ett jokertecken för att utöka alla block av en viss typ
Alla namn som slutar med en asterisk är ett prefixjokertecken, inte bara core/*. Följande tillägg gäller för varje block vars namn börjar med my-plugin/,
inklusive block som skapats med Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Utesluta block
Använd en array på toppnivå i exclude för att hoppa över block som annars skulle matcha name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Undantag använder samma matchning på exakta namn och prefix som slutar med * som name.
De har företräde framför enstaka namn, namnlistor och jokertecken. Ett uteslutet
block får varken tilläggets redigerarfält eller dess frontendattribut
eller resurser. Andra matchande tillägg påverkas inte. Utelämna exclude eller använd en
tom array för att behålla det befintliga beteendet.
Blockstudio-nyckel
Precis som när du använder block.json för anpassade block måste egenskapen blockstudio finnas i konfigurationsobjektet med extend inställt på true.
Position
Som standard visas tillägg på en egen flik i blockinspektören. Om du vill flytta tilläggen till en annan position kan du använda egenskapen group:
- settings: Standardpositionen
- styles: Fliken för stilar
- advanced: Fliken för avancerat
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Prioritet
Egenskapen priority låter dig ange i vilken ordning tilläggen renderas. Tillägg med högre prioritet renderas senare. Ange den på filens toppnivå, som i konfigurationsexemplet, eller inuti extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Om båda anges vinner blockstudio.extend.priority.
Attribut
Mer information om hur attribut fungerar finns i avsnittet om attribut.
Det enda du behöver känna till om attribut i tillägg är egenskapen set. Den används för att tillämpa attributets värde på en av tilläggstyperna.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Hämta värden
Punktnotation inom klammerparenteser används för att hämta värdet för ett attribut.
Det går också att hämta nästlade värden när attribut inte returnerar ett enskilt värde, till exempel när returformatet ställs in på both för fälttyper med alternativ.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
Exemplet ovan ställer in attributet style på color: #f00 eller color: #00f och attributet data-color på Red eller Blue, beroende på värdet.
För närvarande kan endast värden från det aktuella attributet användas i definitioner av set. Möjligheten att använda värden från andra attribut kan läggas till i framtiden.
Arrayer
När du använder arrayer tillämpas egenskapen set på varje objekt i arrayen.
Varje objekt lägger till sin egen klass eller stilregel. Alla andra attribut innehåller ett enda värde, så varje objekt skriver över det föregående och det sista vinner. Sätt join till true för att i stället skriva resultaten från alla objekt, åtskilda av blanksteg och utan tomma eller upprepade värden, så att en väljare som [data-langs~="en"] matchar alla valda objekt. join påverkar inte class och style eller fält som returnerar ett enda värde.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Om du väljer båda alternativen återges data-langs="en de". Utan join återges data-langs="de".
Attributfält
När du använder fältet attributes behövs ingen egenskap set, eftersom fältet automatiskt mappar värdena till attributets namn och värde.
Granska tilläggsfält
bs_block_extension_fields('core/paragraph') returnerar fältdefinitionerna för
t varje tillägg som matchar ett block. Se
Granska block för returvärdet
och hur det förhåller sig till bs_block_fields().