Udvidelser
Med udvidelser kan du udvide enhver registreret blok i din WordPress-installation ved hjælp af en enkel .json-baseret API, der minder om konfigurationen for block.json. Det omfatter kerneblokke, tredjepartsblokke og blokke oprettet med Blockstudio.
Alle felttyper kan føjes til enhver blok, og dataene gemmes i blokkens attributter. Det komplette funktionssæt for attributter er tilgængeligt i udvidelser, herunder filtrering, deaktivering, betinget logik og udfyldning af valgmuligheder.
Udvidelsestyper
Udvidede værdier kan bruges på mange forskellige måder:
- class: Føj en klasse til blokken ved hjælp af attributværdien
- style: Føj inline-typografier til blokken ved hjælp af attributværdien
- attributes: Angiv enhver attributværdi direkte på blokken
- data attributes: Brug udvidelsesværdier til at angive specifikke dataattributter
Opsætning
Forestil dig følgende scenarie: Du vil føje et felt til en brugerdefineret klasse select i hver kerneblok. Du skal blot tilføje denne fil .json hvor som helst i din blokmappe, så registreres den automatisk som en udvidelse.
{
"$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}"
}
]
}
]
}
}
Dette føjer et customColor-felt til hver kerneblok, så du kan angive farven på blokkens tekst.
Filnavn
Da der ikke findes nogen skabelon til rendering, behøver en udvidelse ikke en tilsvarende index-fil og skal derfor ikke hedde block.json. Dermed kan alle udvidelser nemt gemmes i én mappe. Flere filer kan udvide de samme blokke, f.eks. to filer med "name": "core/*"; hver fil registrerer sine egne felter.
Skema
Blockstudio leverer et brugerdefineret JSON-skema til udvidelseskonfigurationer:
Navn
Egenskaben name for konfigurationsobjektet angiver, hvilke blokke der skal udvides. Afhængigt af dine behov er der tre muligheder:
- blockName: Et enkelt bloknavn, e.g.
core/paragraph - [blockNameA, blockNameB]: En liste med bloknavne, e.g.
["core/paragraph", "core/heading"] - core/*: Et jokertegn, der udvider alle blokke af en bestemt type
Ethvert navn, der slutter med en stjerne, er et præfikswildcard, ikke kun core/*. Følgende udvidelse gælder for alle blokke, hvis navn begynder med my-plugin/,
herunder blokke oprettet med Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Udelukkelse af blokke
Brug et array på øverste niveau exclude til at springe blokke over, der ellers ville matche name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Udelukkelser bruger samme matchning af præcise navne og præfikser med afsluttende * som name.
De har forrang frem for enkelte navne, navnelister og wildcards. En udelukket
blok får hverken udvidelsens editorfelter eller dens frontend-attributter
eller aktiver. Andre matchende udvidelser påvirkes ikke. Udelad exclude, eller brug et tomt array for at bevare den eksisterende funktionsmåde.
Blockstudio-nøgle
Ligesom når du bruger block.json til brugerdefinerede blokke, skal egenskaben blockstudio være til stede i konfigurationsobjektet med extend angivet til true.
Placering
Som standard vises udvidelser i deres egen fane i blokinspektøren. Hvis du vil flytte udvidelserne til en anden placering, kan du bruge egenskaben group:
- settings: Standardplaceringen
- styles: Fanen med typografier
- advanced: Fanen Avanceret
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Prioritet
Egenskaben priority giver dig mulighed for at angive den rækkefølge, som udvidelser vises i. Udvidelser med højere prioritet vises senere. Angiv den på filens øverste niveau som i opsætningseksemplet eller inde i extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Når begge er angivet, vinder blockstudio.extend.priority.
Attributter
Se afsnittet om attributter for at få flere oplysninger om, hvordan attributter fungerer.
Det eneste, du skal vide om attributter i udvidelser, er egenskaben set. Den bruges til at anvende attributværdien på en af udvidelsestyperne.
{
"$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}"
}
]
}
]
}
}
Hent værdier
Punktnotation i krøllede parenteser bruges til at hente værdien af en attribut.
Det er også muligt at hente indlejrede værdier, når attributter ikke returnerer en enkelt værdi, f.eks. når returformatet angives til both for felttyper med valgmuligheder.
{
"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}"
}
]
}
]
}
Eksemplet ovenfor angiver attributten style til color: #f00 eller color: #00f og attributten data-color til Red eller Blue, afhængigt af værdien.
Indtil videre kan kun værdier fra den aktuelle attribut bruges i set-definitioner. Muligheden for at bruge værdier fra andre attributter kan blive tilføjet senere.
Lister
Når du bruger lister, anvendes egenskaben set på hvert element i listen.
Hvert element tilføjer sin egen klasse eller stildeklaration. Alle andre attributter har en enkelt værdi, så hvert element overskriver den foregående, og det sidste element vinder. Sæt join til true for i stedet at skrive resultaterne fra alle elementer, adskilt af mellemrum og uden tomme eller gentagne værdier, så en selector som [data-langs~="en"] matcher hvert valgt element. join har ingen virkning på class og style eller på felter, der returnerer en enkelt værdi.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Hvis du vælger begge muligheder, gengives data-langs="en de". Uden join gengives data-langs="de".
Attributfelt
Når du bruger feltet attributes, er egenskaben set ikke nødvendig, da feltet automatisk knytter værdierne til attributtens navn og værdi.
Inspektion af udvidelsesfelter
bs_block_extension_fields('core/paragraph') returnerer feltdefinitionerne for
enhver udvidelse, der matcher en blok. Se
Inspektion af blokke for returværdien
og hvordan den hænger sammen med bs_block_fields().