Vai al contenuto

Campi personalizzati

I campi personalizzati consentono di definire gruppi di campi riutilizzabili a cui fare riferimento in più blocchi. Sono come modelli di campo: definite una volta e usateli ovunque.

I campi personalizzati non sono la stessa cosa dei tipi di campo personalizzati. Usate custom/{name} per i gruppi riutilizzabili di campi esistenti. Usate un tipo di campo personalizzato con spazio dei nomi, come acme/dimensions, quando un tema o plugin registra un nuovo controllo di modifica e una nuova struttura del valore.

Registrazione del file system

Create un file field.json all’interno di una directory fields/ nella vostra directory blockstudio:

Codice
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

Registrazione del filtro PHP

Registrate i campi personalizzati a livello di codice usando il filtro blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

Uso in block.json

Fate riferimento a un campo personalizzato usando il tipo custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Questo espande i campi definiti nella definizione del campo personalizzato direttamente in linea. I campi espansi usano i loro ID originali (heading, description, enabled).

I campi personalizzati possono anche riutilizzare definizioni di gruppi complete:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Gli elementi figlio del gruppo vengono archiviati come section-header_kicker, section-header_title e così via. Nei modelli, usate bs_get_group() per estrarli in un oggetto gruppo ordinato.

Struttura degli ID

Usate idStructure per anteporre un prefisso o trasformare gli ID dei campi. Il segnaposto {id} viene sostituito con l’ID originale del campo:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Questo genera campi con gli ID: hero_heading, hero_description, hero_enabled.

Sovrascritture

Personalizzate i singoli campi per istanza usando overrides. Le chiavi sono gli ID originali dei campi definiti:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Le proprietà di override vengono unite alla definizione originale del campo. Un override id ignora lo schema idStructure. Nell’esempio precedente, enabled diventa active invece di hero_enabled.

L’unione avviene a un solo livello: una proprietà sovrascritta sostituisce per intero quella originale. Una sovrascrittura options costituisce l’elenco completo delle opzioni, non un’aggiunta; lo stesso vale per conditions e per attributes di un gruppo. Le condizioni sul riferimento vengono comunque aggiunte in seguito.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Questo blocco offre solo Bianco e Grigio, indipendentemente dal numero di opzioni elencate nella definizione.

Condizioni

Le condizioni nelle definizioni dei campi personalizzati vengono riscritte automaticamente quando si applica idStructure. Un campo che dipende condizionalmente da un campo fratello continua a funzionare dopo l’espansione.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio espande il contenuto in title_font_enable, title_font_min, title_font_max e riscrive le condizioni affinché facciano riferimento a title_font_enable invece di enable. Gli interruttori funzionano esattamente come se i campi fossero definiti in linea.

Condizioni a livello di riferimento

Aggiungete conditions al riferimento per applicarle a ogni campo espanso. È utile per nascondere un intero gruppo dietro un interruttore esterno:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Queste condizioni si combinano con quelle già definite nel campo. Anche gli ID delle condizioni vengono riscritti tramite idStructure.

Più campi personalizzati

Potete usare più campi personalizzati in un singolo blocco, insieme ai campi standard:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Annidamento

I campi personalizzati funzionano all’interno di gruppi, schede e repeater:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Percorsi di individuazione aggiuntivi

Usate il filtro blockstudio/fields/paths per aggiungere directory supplementari all’individuazione dei campi:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Analisi statica

Il pacchetto blockstudio/phpstan espande i riferimenti custom/* basati su file durante la convalida di PHP, Twig, Blade, dei tag di blocco e delle strutture degli attributi dedotte. L’espansione segue le stesse regole di annidamento, idStructure e overrides descritte sopra.

Per le definizioni esterne al progetto analizzato, aggiungete la directory della libreria a blockstudioScanRoots in phpstan.neon. I campi registrati solo tramite il filtro blockstudio/fields PHP esistono a runtime e non possono essere dedotti staticamente.