Estensioni
Le estensioni consentono di estendere qualsiasi blocco registrato nell’installazione WordPress usando un semplice .json basato su API, simile alla configurazione block.json. È possibile includere blocchi core, di terze parti e realizzati con Blockstudio.
Tutti i tipi di campo possono essere aggiunti a qualsiasi blocco, salvando i dati negli attributi del blocco. Per le estensioni è disponibile l’intero set di funzionalità degli attributi, come il filtraggio, la disattivazione, la logica condizionale e il popolamento delle opzioni.
Tipi di estensione
I valori estesi possono essere utilizzati in vari modi:
- class: aggiunge una classe al blocco usando il valore dell’attributo
- style: aggiunge stili inline al blocco usando il valore dell’attributo
- attributes: imposta direttamente sul blocco qualsiasi valore di attributo
- data attributes: usa i valori dell’estensione per impostare specifici attributi data
Configurazione
Immaginate il seguente scenario: volete aggiungere un campo select di classe personalizzata a ogni blocco core. Vi basta aggiungere questo file .json in una qualsiasi posizione nella cartella dei blocchi: verrà registrato automaticamente come estensione.
{
"$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}"
}
]
}
]
}
}
Questo aggiungerà un campo customColor a ogni blocco core, consentendovi di impostare il colore del testo del blocco.
Nome del file
Poiché non è previsto un template di rendering, un’estensione non necessita di un file index corrispondente e quindi non deve chiamarsi block.json. In questo modo è possibile archiviare comodamente tutte le estensioni in un’unica cartella. Più file possono estendere gli stessi blocchi, ad esempio due file con "name": "core/*"; ognuno registra i propri campi.
Schema
Blockstudio fornisce uno schema JSON personalizzato per le configurazioni delle estensioni:
Nome
La proprietà name dell’oggetto di configurazione definisce quali blocchi estendere. In base alle vostre esigenze, sono disponibili tre opzioni:
- blockName: un singolo nome di blocco, e.g.
core/paragraph - [blockNameA, blockNameB]: un array di nomi di blocchi, e.g.
["core/paragraph", "core/heading"] - core/*: un carattere jolly per estendere tutti i blocchi di un determinato tipo
Qualsiasi nome che termina con un asterisco è un carattere jolly per i prefissi, non solo core/*. La
seguente estensione si applica a ogni blocco il cui nome inizia con my-plugin/,
inclusi i blocchi creati con Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Escludere blocchi
Usate un array di primo livello exclude per ignorare i blocchi che altrimenti corrisponderebbero a name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Le esclusioni usano la stessa corrispondenza per nome esatto e per prefisso con * finale di name.
Hanno la precedenza sui singoli nomi, sulle liste di nomi e sui caratteri jolly. Un
blocco escluso non riceve né i campi dell’editor né gli attributi o gli asset frontend
dell’estensione. Le altre estensioni corrispondenti non sono interessate. Omettete exclude o usate un
array vuoto per mantenere il comportamento esistente.
Chiave Blockstudio
Come quando si usa block.json per i blocchi personalizzati, la proprietà blockstudio deve essere presente nell’oggetto di configurazione, con extend impostato su true.
Posizione
Per impostazione predefinita, le estensioni vengono visualizzate in una scheda dedicata nell’ispettore dei blocchi. Se volete spostarle in un’altra posizione, potete usare la proprietà group:
- settings: posizione predefinita
- styles: scheda degli stili
- advanced: scheda delle opzioni avanzate
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Priorità
La proprietà priority consente di definire l’ordine di visualizzazione delle estensioni. Quelle con priorità più alta vengono visualizzate dopo. Impostatela al livello principale del file, come nell’esempio di configurazione, oppure all’interno di extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Se sono impostate entrambe, ha la precedenza blockstudio.extend.priority.
Attributi
Per ulteriori informazioni sul funzionamento degli attributi, consultate la sezione sugli attributi.
L’unica cosa da sapere sugli attributi nelle estensioni è la proprietà set. Serve ad applicare il valore dell’attributo a uno dei tipi di estensione.
{
"$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}"
}
]
}
]
}
}
Recuperare i valori
Per recuperare il valore di un attributo si usa la notazione con il punto all’interno delle parentesi graffe.
È possibile recuperare anche valori annidati quando gli attributi non restituiscono un singolo valore, ad esempio impostando il formato di restituzione su both nei tipi di campo con opzioni.
{
"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}"
}
]
}
]
}
A seconda del valore, l’esempio precedente imposterà l’attributo style su color: #f00 o color: #00f e l’attributo data-color su Red o Blue.
Per ora, nelle definizioni di set si possono usare solo valori dell’attributo corrente. In futuro potrebbe essere possibile usare valori di altri attributi.
Array
Quando si usano array, la proprietà set viene applicata a ogni elemento dell’array.
Ogni elemento aggiunge la propria classe o dichiarazione di stile. Qualsiasi altro attributo contiene un singolo valore, quindi ogni elemento lo sovrascrive e prevale l’ultimo. Impostate join su true per scrivere invece i risultati di tutti gli elementi, separati da spazi e senza valori vuoti o ripetuti, così che un selettore come [data-langs~="en"] corrisponda a ogni elemento scelto. join non ha effetto su class e style, né sui campi che restituiscono un singolo valore.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Selezionando entrambe le opzioni viene visualizzato data-langs="en de". Senza join, viene visualizzato data-langs="de".
Campo degli attributi
Quando si usa il campo attributes, non è necessaria la proprietà set, perché il campo associa automaticamente i valori al nome e al valore dell’attributo.
Esaminare i campi delle estensioni
bs_block_extension_fields('core/paragraph') restituisce le definizioni dei campi
di ogni estensione corrispondente a un blocco. Consultate
Esaminare i blocchi per conoscere il valore restituito
e il suo rapporto con bs_block_fields().