Rozšíření
Rozšíření umožňují rozšiřovat libovolný registrovaný blok v instalaci WordPress pomocí jednoduché konfigurace API založené na .json, která se podobá konfiguraci block.json. Zahrnuje to bloky jádra, bloky třetích stran i bloky vytvořené pomocí Blockstudio.
Všechny typy polí lze přidat do libovolného bloku a jejich data se ukládají do atributů bloku. Rozšíření mají k dispozici kompletní sadu funkcí atributů, jako je filtrování, zakázání, podmíněná logika a naplňování možností.
Typy rozšíření
Rozšířené hodnoty lze využít různými způsoby:
- class: Přidá bloku třídu pomocí hodnoty atributu
- style: Přidá bloku vložené styly pomocí hodnoty atributu
- attributes: Nastaví libovolnou hodnotu atributu přímo bloku
- data attributes: Pomocí rozšířených hodnot nastaví konkrétní datové atributy
Nastavení
Představte si následující situaci: chcete přidat pole select s vlastní třídou do každého bloku jádra. Stačí přidat tento soubor .json kamkoli do složky bloku a automaticky se zaregistruje jako rozšíření.
{
"$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}"
}
]
}
]
}
}
Tím se do každého bloku jádra přidá pole customColor, které umožňuje nastavit barvu textu bloku.
Název souboru
Protože rozšíření nemá šablonu pro vykreslování, nepotřebuje odpovídající soubor index, a nemusí se tedy jmenovat block.json. Všechna rozšíření tak lze pohodlně ukládat do jediné složky. Stejné bloky může rozšiřovat několik souborů, například dva soubory s "name": "core/*"; každý z nich zaregistruje vlastní pole.
Schéma
Blockstudio poskytuje vlastní schéma JSON pro konfigurace rozšíření:
Název
Vlastnost name konfiguračního objektu určuje, které bloky se mají rozšířit. Podle potřeby jsou k dispozici tři možnosti:
- blockName: Název jednoho bloku, e.g.
core/paragraph - [blockNameA, blockNameB]: Pole názvů bloků, e.g.
["core/paragraph", "core/heading"] - core/*: Zástupný znak pro rozšíření všech bloků určitého typu
Každý název končící hvězdičkou je zástupný znak pro prefix, nejen core/*. Následující rozšíření se použije na každý blok, jehož název začíná na my-plugin/, včetně bloků vytvořených pomocí Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Vyloučení bloků
Pomocí pole exclude na nejvyšší úrovni přeskočte bloky, které by jinak odpovídaly name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Vyloučení používají stejné porovnávání přesných názvů a prefixů s koncovým * jako name.
Mají přednost před jednotlivými názvy, seznamy názvů i zástupnými znaky. Vyloučený
blok nedostane pole editoru rozšíření ani atributy nebo prostředky pro frontend.
Ostatní odpovídající rozšíření nejsou ovlivněna. Vynechte exclude nebo použijte
prázdné pole, chcete-li zachovat stávající chování.
Klíč Blockstudio
Stejně jako při použití block.json pro vlastní bloky musí být v konfiguračním objektu uvedena vlastnost blockstudio s hodnotou extend nastavenou na true.
Pozice
Ve výchozím nastavení se rozšíření zobrazují na vlastní kartě v inspektoru bloku. Pokud je chcete přesunout jinam, můžete použít vlastnost group:
- settings: Výchozí pozice
- styles: Karta stylů
- advanced: Karta pokročilých nastavení
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Priorita
Vlastnost priority umožňuje určit pořadí vykreslování rozšíření. Rozšíření s vyšší prioritou se vykreslí později. Nastavte ji na nejvyšší úrovni souboru, jako v příkladu nastavení, nebo uvnitř extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Pokud jsou nastaveny obě, přednost má blockstudio.extend.priority.
Atributy
Další informace o fungování atributů najdete v části o atributech.
Jediné, co potřebujete vědět o atributech v rozšířeních, je vlastnost set. Používá se k přiřazení hodnoty atributu k jednomu z typů rozšíření.
{
"$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}"
}
]
}
]
}
}
Získání hodnot
Hodnotu atributu získáte pomocí tečkové notace ve složených závorkách.
Vnořené hodnoty lze získat také v případě, že atributy nevracejí jedinou hodnotu, například když je u typů polí s možnostmi nastaven formát návratové hodnoty na both.
{
"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}"
}
]
}
]
}
Výše uvedený příklad nastaví atribut style na hodnotu color: #f00 nebo color: #00f a atribut data-color na hodnotu Red nebo Blue podle příslušné hodnoty.
V definicích set lze zatím používat pouze hodnoty z aktuálního atributu. Možnost používat hodnoty z jiných atributů může být přidána v budoucnu.
Pole
Při použití polí se vlastnost set použije na každou položku pole.
Každá položka přidá vlastní třídu nebo deklaraci stylu. Každý jiný atribut obsahuje jednu hodnotu, takže ji každá položka přepíše a platí poslední položka. Nastavením join na true zapíšete výsledky všech položek, oddělené mezerami a bez prázdných či opakujících se hodnot, takže selektor jako [data-langs~="en"] odpovídá každé vybrané položce. join nemá vliv na class a style ani na pole vracející jednu hodnotu.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Při výběru obou možností se vykreslí data-langs="en de". Bez join se vykreslí data-langs="de".
Pole attributes
Při použití pole attributes není potřeba vlastnost set, protože pole automaticky mapuje hodnoty na název a hodnotu atributu.
Prohlížení polí rozšíření
bs_block_extension_fields('core/paragraph') vrací definice polí
všech rozšíření odpovídajících bloku. Informace o návratové
hodnotě a jejím vztahu k bs_block_fields() najdete v části
Prohlížení bloků.