Vai al contenuto

Creare un tipo di campo personalizzato

Alcuni valori sono composti da più di un elemento primitivo. Un prezzo è formato da un importo e una valuta. Con i campi integrati lo si rappresenta con un campo numerico e uno di selezione affiancati, e ogni blocco che mostra un prezzo ripete la coppia, le etichette e la logica che li mantiene insieme. Nei metadati dell’articolo diventano due chiavi e, all’interno di un ripetitore, due elenchi paralleli.

Un tipo di campo personalizzato riunisce la coppia in un solo campo. Registrate una volta un tipo come acme/price in PHP e in JavaScript, poi usatelo in qualsiasi block.json come un campo nativo: al livello principale, all’interno di gruppi e ripetitori, con i metadati dell’articolo o lo storage delle opzioni, e nei template PHP, Twig e Blade. Blockstudio ricava l’attributo WordPress e lo schema di storage REST dalla registrazione.

È diverso da un campo personalizzato. Un riferimento custom/{name} riutilizza un gruppo di campi esistenti. Un tipo di campo personalizzato aggiunge un nuovo controllo con una propria struttura del valore.

Questa guida crea acme/price dall’inizio alla fine: la registrazione PHP, il controllo dell’editor, un blocco per i prezzi che lo usa al livello principale e all’interno di un ripetitore, lo storage nei metadati dell’articolo con uno schema REST rigoroso e l’output renderizzato.

Registrare il tipo in PHP

La parte PHP dichiara il tipo di attributo, il valore predefinito, lo script dell’editor che fornisce il controllo e il modo in cui il valore viene salvato fuori dal blocco:

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

	bs_register_field_type( 'acme/price', array(
		'attribute'     => 'object',
		'default'       => array(),
		'editor_script' => 'acme-field-price',
		'storage'       => array(
			'type'        => 'object',
			'rest_schema' => array(
				'type'                 => 'object',
				'properties'           => array(
					'amount'   => array( 'type' => 'number', 'minimum' => 0 ),
					'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
				),
				'additionalProperties' => false,
			),
		),
	) );
} );

attribute è il tipo di attributo WordPress, qui object. storage.type è il tipo di valore usato quando il campo viene salvato nei metadati dell’articolo o nelle opzioni, mentre storage.rest_schema è lo schema WordPress con cui vengono convalidate le scritture di REST. Senza un rest_schema, un valore oggetto riceve uno schema permissivo che accetta qualsiasi proprietà.

Registrate su init con la priorità predefinita. Blockstudio rileva i blocchi in ritardo su init e un tipo non registrato entro quel momento viene escluso dagli attributi del blocco generati.

bs_register_field_type() restituisce true in caso di successo e false se il nome o la definizione non sono validi. I nomi devono essere in minuscolo, con namespace e in formato dashcase; sono riservati due namespace:

Nome Risultato
acme/price true
Acme/Price false, non in minuscolo
custom/price false, riservato ai gruppi di campi riutilizzabili
blockstudio/price false, riservato al core di Blockstudio

bs_unregister_field_type() rimuove una registrazione; il filtro blockstudio/field_types accetta le stesse definizioni in un array indicizzato per nome.

Creare il controllo dell’editor

Lo script registrato sopra fornisce il componente React. Usa i componenti WordPress già caricati nell’editor, quindi non richiede una fase di build:

JavaScript
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/price', {
  component(props) {
    const value =
      props.value && typeof props.value === 'object' && !Array.isArray(props.value)
        ? props.value
        : {};
    const currencies = props.currencies || ['EUR'];

    return el(
      Flex,
      { align: 'flex-end' },
      el(
        FlexBlock,
        {},
        el(TextControl, {
          label: props.label,
          type: 'number',
          min: 0,
          step: 0.01,
          disabled: props.disabled,
          value: value.amount ?? '',
          onChange(next) {
            props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
          },
        }),
      ),
      el(
        FlexItem,
        {},
        el(SelectControl, {
          label: 'Currency',
          hideLabelFromVision: true,
          disabled: props.disabled,
          value: value.currency || currencies[0],
          options: currencies.map((code) => ({ label: code, value: code })),
          onChange(next) {
            props.onChange({ ...value, currency: next });
          },
        }),
      ),
    );
  },
});

Il componente riceve tutte le proprietà della definizione del campo, quindi la chiave currencies inserita in block.json arriva come props.currencies. Riceve anche proprietà stabili: value, onChange, field, defaultValue, attributes, block, clientId, disabled e inRepeater con repeaterId quando viene renderizzato all’interno di una riga del ripetitore. onChange salva il valore esattamente come fornito. I valori personalizzati saltano la normalizzazione delle opzioni applicata dai campi nativi select, radio, color e gradient.

Come nelle prime righe, gestite i valori che non sono oggetti. Un blocco salvato prima che il campo esistesse, o con una struttura diversa, dovrebbe comunque aprirsi nell’editor.

Blockstudio accoda acme-field-price nell’editor dei blocchi solo quando viene registrato un blocco che usa acme/price. Se lo script non riesce a registrare il controllo, l’editor conserva il valore salvato e mostra un avviso non modificabile al posto del campo, mentre il frontend continua a renderizzare il valore.

Usarlo in un blocco

Un blocco per i prezzi usa il tipo due volte: una per un prezzo iniziale consultabile anche fuori dal blocco e una per ogni riga di un ripetitore per le fasce:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/pricing",
  "title": "Pricing",
  "blockstudio": {
    "attributes": [
      {
        "id": "price",
        "type": "acme/price",
        "label": "Starting price",
        "currencies": ["EUR", "USD"],
        "default": { "amount": 19, "currency": "EUR" },
        "storage": {
          "type": "postMeta",
          "postMetaKey": "acme_price"
        }
      },
      {
        "id": "tiers",
        "type": "repeater",
        "label": "Tiers",
        "min": 0,
        "max": 4,
        "attributes": [
          { "id": "name", "type": "text", "label": "Name", "default": "" },
          {
            "id": "price",
            "type": "acme/price",
            "label": "Price",
            "currencies": ["EUR", "USD"],
            "default": { "amount": 0, "currency": "EUR" },
            "storage": {
              "type": "postMeta",
              "postMetaKey": "acme_tier_prices"
            }
          }
        ]
      }
    ]
  }
}

Un default a livello di campo prevale sul valore predefinito del registro. Blockstudio trasforma entrambi i campi in attributi WordPress definiti dalla registrazione. Il tipo di blocco registrato contiene:

JSON
{
  "price": {
    "blockstudio": true,
    "type": "object",
    "field": "acme/price",
    "id": "price",
    "default": { "amount": 19, "currency": "EUR" },
    "storage": { "type": "postMeta", "postMetaKey": "acme_price" }
  },
  "tiers": {
    "blockstudio": true,
    "type": "array",
    "field": "repeater",
    "id": "tiers",
    "attributes": [
      { "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
      {
        "blockstudio": true,
        "type": "object",
        "field": "acme/price",
        "id": "price",
        "default": { "amount": 0, "currency": "EUR" },
        "storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
      }
    ]
  }
}

Renderizzare il valore

Nel template, il valore è un normale array. Verificatene il tipo prima di usarlo, perché un valore salvato è affidabile solo quanto l’ultima operazione che lo ha scritto:

PHP
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
	if ( ! is_array( $price ) ) {
		return '';
	}
	$amount   = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
	$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';

	return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
  <p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
  <?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
    <div class="acme-tier">
      <h3><?php echo esc_html( $tier['name'] ); ?></h3>
      <p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
    </div>
  <?php endforeach; ?>
</section>

La parte ?: array() è importante. Un ripetitore senza righe raggiunge il template come false, non come array vuoto, e un foreach diretto su di esso genera un avviso PHP. La riga @var è spiegata nella sezione analisi statica più avanti.

Rendering del blocco con un prezzo iniziale e due fasce:

PHP
echo bs_block( array(
	'name' => 'acme/pricing',
	'data' => array(
		'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
		'tiers' => array(
			array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
			array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
		),
	),
) );
HTML
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
  <p>From 19.00 EUR</p>
      <div class="acme-tier">
      <h3>Starter</h3>
      <p>19.00 EUR</p>
    </div>
      <div class="acme-tier">
      <h3>Team</h3>
      <p>49.00 EUR</p>
    </div>
  </section>

Senza dati, si applica il valore predefinito del campo e il blocco viene renderizzato From 19.00 EUR senza fasce. Twig e Blade leggono lo stesso valore di a.price.amount e $a['price']['amount'], e i template di estensione extension possono accedervi come {attributes.price.amount}.

Storage e schema REST

Entrambi i campi dichiarano lo storage postMeta, quindi Blockstudio registra due chiavi meta quando crea il blocco. Il campo di livello principale usa lo schema di storage registrato così com’è:

JSON
{
  "type": "object",
  "single": true,
  "show_in_rest": {
    "schema": {
      "type": "object",
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      },
      "additionalProperties": false
    }
  }
}

Il campo all’interno del ripetitore salva un valore per riga, quindi la sua chiave meta è basata su un array e lo stesso schema diventa lo schema dell’elemento:

JSON
{
  "type": "array",
  "single": true,
  "show_in_rest": {
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
        },
        "additionalProperties": false
      }
    }
  }
}

Quando si salva un articolo che contiene il blocco, entrambe le chiavi vengono sincronizzate. Con le due fasce mostrate sopra, get_post_meta( $id, 'acme_price', true ) restituisce {"amount":19,"currency":"EUR"} e acme_tier_prices restituisce l’elenco dei prezzi delle righe:

JSON
[
  { "amount": 19, "currency": "EUR" },
  { "amount": 49, "currency": "EUR" }
]

Entrambe le chiavi compaiono nella risposta REST dell’articolo sotto meta, e le scritture REST vengono convalidate rispetto allo schema. Una scrittura con la valuta in minuscolo viene rifiutata:

JSON
{
  "code": "rest_invalid_pattern",
  "message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
  "data": { "status": 400 }
}

I metadati sono una copia. Gli attributi del blocco nel contenuto dell’articolo restano la fonte e ogni salvataggio li sincronizza nuovamente con le chiavi configurate; quindi, un valore scritto direttamente nei metadati viene sostituito al salvataggio successivo dell’articolo. Lo storage delle opzioni funziona allo stesso modo tramite register_setting(). I tipi di campo personalizzati, incluso lo storage basato su array nei ripetitori, sono disponibili da Blockstudio 7.5.0.

Analisi statica

L’estensione PHPStan conosce i tipi di campo integrati, non quelli registrati dal progetto in fase di esecuzione. In un blocco che usa acme/price indica il tipo di campo come sconosciuto e assegna al suo valore il tipo mixed:

Text
  2      block.json field "price" has unknown type "acme/price" in
         blockstudio/pricing/block.json
         🪪  blockstudio.blockJson.type

Ignorate questa diagnostica per i vostri tipi nella configurazione del progetto e mantenete il controllo del tipo nel template: è ciò che serve a PHPStan per accettare il valore mixed al livello max:

Neon
parameters:
    level: max
    ignoreErrors:
        -
            identifier: blockstudio.blockJson.type
            message: '#unknown type "acme/price"#'

Con questa configurazione e il template qui sopra, l’analisi ha esito positivo. Nella versione 7.6 il template richiede anche la riga @var, con mixed nelle posizioni dei campi personalizzati; dalla versione 7.7 Blockstudio deduce autonomamente questa struttura e la riga può essere rimossa. Consultate Template verificati con PHPStan per eseguire l’analisi.

Passaggi successivi