Vai al contenuto

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.

JSON
{
  "$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:

Schema dell’estensione View

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:

JSON
{
  "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:

JSON
{
  "$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
JSON
{
  "$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:

JSON
{
  "$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.

JSON
{
  "$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.

JSON
{
  "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.

JSON
{
  "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().