Vai al contenuto

Tipi di campi personalizzati

I tipi di campo personalizzati consentono a un tema o plugin di aggiungere nuovi controlli di campo Blockstudio. Sono diversi dai campi personalizzati:

  • custom/{name} fa riferimento a un gruppo riutilizzabile di campi esistenti.
  • namespace/type-name usa un tipo di campo registrato con un proprio controllo di modifica e una struttura del valore.

Blockstudio fornisce il sistema di registrazione. Il tema o plugin fornisce il controllo.

Quando usarli

Usate un tipo di campo personalizzato quando un progetto richiede un controllo di modifica specifico che debba comportarsi come un campo nativo Blockstudio ovunque:

  • attributi dei blocchi
  • gruppi di campi custom/{name} riutilizzabili
  • gruppi, schede e repeater
  • modelli PHP, Twig e Blade
  • metadati dei contenuti e archiviazione delle opzioni
  • modelli di estensione come {attributes.margin.top}

Ad esempio, un controllo per la spaziatura può memorizzare un unico oggetto invece di quattro campi di testo separati:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Denominazione

I nomi dei tipi di campo personalizzati devono essere in minuscolo, includere uno spazio dei nomi e usare il formato dashcase:

Text
namespace/type-name

Esempi validi:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Spazi dei nomi riservati:

  • custom/ è riservato ai gruppi di campi personalizzati riutilizzabili.
  • blockstudio/ è riservato al core di Blockstudio.

I nomi non validi vengono ignorati dal filtro API e rifiutati dall’helper API.

Registrazione di PHP

Registrate i metadati del tipo di campo in PHP:

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});

bs_register_field_type() restituisce true se la registrazione riesce e false se il nome o la definizione non sono validi. È possibile annullare una registrazione manuale con bs_unregister_field_type().

Potete anche usare il filtro API:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

Chiavi della definizione

Chiave Tipo Descrizione
attribute string, array, null Tipo di attributo WordPress. Usate string, number, boolean, object, array oppure un array di questi tipi.
default mixed Valore predefinito a livello di registro quando un campo non ne definisce uno proprio.
source string WordPress sorgente dell’attributo per i casi di serializzazione personalizzata.
produces_attribute boolean Impostate su false per i controlli di sola visualizzazione. Il valore predefinito è true.
editor_script string or array Handle di script registrato da accodare nell’editor dei blocchi quando viene usato il tipo.
editor_style string or array Handle di stile registrato da accodare nell’editor dei blocchi quando viene usato il tipo.
storage array Tipo del valore di archiviazione e indicazioni sullo schema REST per i meta e le opzioni dei post.
supports array Flag di capacità facoltativi per il proprio controllo.
translate boolean Impostate su true quando il valore è testo da tradurre con WPML. Richiede attribute string.

Una definizione con un valore translate che non è booleano, oppure con translate impostato su true e un attribute diverso da string, non è valida. bs_register_field_type() restituisce false e il filtro API la ignora.

WPML

wp bs wpml config non può determinare dalla sola registrazione se il valore di un tipo di campo personalizzato è testo, quindi esclude tali campi e stampa un avviso per ciascuno. Impostate translate su true nella registrazione di un tipo di campo che memorizza una stringa di testo semplice; il comando dichiara i suoi campi come campi text. È comunque possibile escludere un campo con "translate": false. Consultate WPMLTesto traducibile.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

Registrazione di JavaScript

Lo script dell’editor registra il controllo React corrispondente:

JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

registerFieldType() restituisce true quando la registrazione viene accettata. Rimuovete una registrazione client con:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

Il componente riceve le proprietà della definizione del campo, oltre a queste proprietà stabili:

Proprietà Descrizione
type Nome del tipo di campo.
id ID del campo.
field Definizione completa del campo da block.json.
value Valore attualmente salvato.
defaultValue Valore predefinito del campo.
onChange Memorizza direttamente un nuovo valore.
attributes Attributi del blocco corrente.
block Definizione del tipo del blocco corrente.
clientId ID client del blocco corrente nell’editor.
inRepeater Indica se il campo si trova in una riga di repeater.
repeaterId Percorso del repeater corrente, se presente.
disabled Indica se il campo è disattivato nell’editor.

I valori dei tipi di campo personalizzati vengono archiviati direttamente. Non passano attraverso la normalizzazione nativa delle opzioni di select, radio, color o gradient.

Rendering dei valori

I valori degli oggetti sono disponibili come qualsiasi altro attributo Blockstudio.

PHP

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

Anche i percorsi degli oggetti annidati funzionano nei modelli di estensione:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Archiviazione

Quando un tipo di campo personalizzato viene usato con l’archiviazione postMeta o option, Blockstudio usa il tipo di valore di archiviazione registrato e lo schema REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

Per i valori array e object, definite storage.rest_schema nella registrazione del tipo di campo. Gli elementi discendenti dei repeater continuano a usare un’archiviazione basata su array perché un repeater memorizza righe.

Comportamento di riserva

Se PHP conosce il tipo di campo, ma lo script dell’editor non registra un controllo corrispondente, Blockstudio conserva il valore salvato e mostra una notifica non modificabile nell’editor. Il rendering frontend riceve comunque il valore salvato.

Se un tipo di campo non è registrato in PHP, Blockstudio lo esclude dagli attributi WordPress generati. Registrate la definizione PHP prima che venga eseguita l’individuazione dei blocchi, di solito su init prima che Blockstudio crei i blocchi.