Ugrás a tartalomhoz

Egyéni mezőtípus készítése

Egyes értékek több egyszerű adattípusból állnak. Egy ár összegből és pénznemből áll. Beépített mezőkkel ezt egy számmezőként és egy mellette lévő választómezőként modellezi, majd minden árat megjelenítő blokkban megismétli a mezőpárt, a címkéket és az összetartozásukat biztosító logikát. A bejegyzés metaadataiban két kulcs lesz belőle, egy ismétlőn belül pedig két párhuzamos lista.

Az egyéni mezőtípus a mezőpárt egyetlen mezővé alakítja. Egyszer regisztrál egy olyan típust, mint a acme/price, a PHP és a JavaScript helyen, majd bármely block.json mezőben natív mezőként használja: legfelső szinten, csoportokban és ismétlőkben, bejegyzés-metaadatként vagy beállításként tárolva, valamint PHP, Twig és Blade sablonokban. A Blockstudio a regisztrációból származtatja a WordPress attribútumot és a tárolási REST sémát.

Ez eltér az egyéni mezőtől. Az custom/{name} hivatkozás már létező mezők csoportját használja újra. Az egyéni mezőtípus saját értékszerkezetű új vezérlőt ad hozzá.

Ez az útmutató elejétől a végéig elkészíti a acme/price típust: a PHP regisztrációt, a szerkesztővezérlőt, egy árazási blokkot, amely legfelső szinten és egy ismétlőn belül is használja, a bejegyzés-metaadatok szigorú REST sémájú tárolását, valamint a megjelenített kimenetet.

A típus regisztrálása itt: PHP

A PHP oldal deklarálja az attribútum típusát, az alapértelmezett értéket, a vezérlőt biztosító szerkesztői szkriptet és azt, hogyan tárolódik az érték a blokkon kívül:

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 az WordPress attribútumtípus, itt object. A storage.type a mező bejegyzésmetaadatokban vagy beállításokban való tárolásakor használt értéktípus, a storage.rest_schema pedig az a séma, amely alapján a WordPress ellenőrzi a REST írásokat. rest_schema nélkül az objektumérték megengedő sémát kap, amely bármilyen tulajdonságot elfogad.

Regisztrálja a init elemet az alapértelmezett prioritással. A Blockstudio későn fedezi fel a blokkokat a init során, és az addigra még nem regisztrált típus nem kerül bele a létrehozott blokkattribútumokba.

Siker esetén a bs_register_field_type() értéke true, érvénytelen név vagy definíció esetén pedig false. A neveknek kisbetűsnek, névtérrel ellátottnak és kötőjeles formátumúnak kell lenniük; két névtér foglalt:

Név Eredmény
acme/price true
Acme/Price false, nem kisbetűs
custom/price false, újrahasználható mezőcsoportok számára fenntartva
blockstudio/price false, a Blockstudio alaprendszer számára fenntartva

A bs_unregister_field_type() eltávolítja a regisztrációt, a blockstudio/field_types szűrő pedig név szerint tömbbe rendezett, ugyanilyen definíciókat fogad el.

A szerkesztővezérlő elkészítése

A fent regisztrált szkript biztosítja a React komponenst. A szerkesztőben már betöltött WordPress komponenseket használja, így nincs szükség fordítási lépésre:

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 });
          },
        }),
      ),
    );
  },
});

A komponens megkapja a meződefiníció minden tulajdonságát, ezért az block.json helyre írt currencies kulcs props.currencies formában érkezik meg. Stabil tulajdonságokat is kap: value, onChange, field, defaultValue, attributes, block, clientId, disabled és repeaterId értékkel a inRepeater mezőhöz, amikor ismétlősorban jelenik meg. A onChange pontosan a megadott értéket tárolja. Az egyéni értékeknél kimarad az az opciónormalizálás, amelyet a natív select, radio, color és gradient mezők alkalmaznak.

Védekezzen az objektumtól eltérő értékek ellen, ahogy azt az első sorok teszik. A mező létezése előtt, vagy eltérő szerkezetben mentett blokkoknak továbbra is meg kell nyílniuk a szerkesztőben.

A Blockstudio csak akkor tölti be a acme-field-price elemet a blokkszerkesztőben, ha regisztrálva van egy olyan blokk, amely használja a acme/price elemet. Ha a szkript nem regisztrálja a vezérlőt, a szerkesztő megtartja a mentett értéket, és a mező helyén nem szerkeszthető értesítést jelenít meg; a frontend továbbra is megjeleníti az értéket.

Használat blokkban

Egy árazási blokk kétszer használja a típust: egyszer a blokkon kívül is lekérdezhető kezdőárhoz, majd az ismétlő minden egyes árszintjénél:

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"
            }
          }
        ]
      }
    ]
  }
}

A mezőszintű default felülírja a regisztráció alapértelmezett értékét. A Blockstudio mindkét mezőt a regisztrációból származó WordPress attribútummá alakítja. A regisztrált blokktípus tartalmazza:

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" }
      }
    ]
  }
}

Az érték megjelenítése

A sablonban az érték közönséges tömb. Használat előtt szűkítse a típusát, mert a tárolt érték megbízhatósága attól függ, mi írta be utoljára:

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>

A ?: array() fontos. Ha az ismétlőben nincs sor, a sablon false értéket kap, nem üres tömböt, és egy egyszerű foreach ezen PHP figyelmeztetést vált ki. A @var sort az alábbi statikus elemzés rész magyarázza.

A blokk megjelenítése kezdőárral és két árszinttel:

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>

Adat nélkül érvényesül a mező alapértelmezett értéke, és a blokk From 19.00 EUR alakban jelenik meg, árszintek nélkül. A Twig és a Blade ugyanazt az értéket olvassa, mint a a.price.amount és a $a['price']['amount'], a kiterjesztési sablonokban pedig {attributes.price.amount} néven érhető el.

Tárolás és a REST séma

Mindkét mező postMeta tárolást deklarál, így a Blockstudio a blokk létrehozásakor két meta kulcsot regisztrál. A legfelső szintű mező változatlanul a regisztrált tárolási sémát használja:

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
    }
  }
}

Az ismétlőn belüli mező soronként egy értéket tárol, ezért a meta kulcs tömbalapú, a séma pedig ugyanaz marad az elemek sémájaként:

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
      }
    }
  }
}

Ha elment egy blokkot tartalmazó bejegyzést, mindkét kulcs szinkronizálódik. A fenti két árszinttel a get_post_meta( $id, 'acme_price', true ) értéke {"amount":19,"currency":"EUR"}, a acme_tier_prices pedig visszaadja a sorok árait tartalmazó listát:

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

Mindkét kulcs megjelenik a bejegyzés REST válaszában, a meta alatt, és a REST írásait a séma ellenőrzi. Az írás elutasítja a kisbetűs pénznemet:

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

A metaadat másolat. A bejegyzés tartalmában lévő blokkattribútumok maradnak az adatforrások, és minden mentés újra szinkronizálja őket a beállított kulcsokkal, ezért a közvetlenül a metaadatokba írt érték a bejegyzés következő mentésekor lecserélődik. A beállítástárolás is ugyanígy működik a register_setting() segítségével. Az egyéni mezőtípusok, köztük az ismétlők tömbalapú tárolása, Blockstudio 7.5.0 óta érhetők el.

Statikus elemzés

A PHPStan bővítmény a beépített mezőtípusokat ismeri, a projekt által futásidőben regisztráltakat nem. Ha egy blokk a acme/price elemet használja, a mezőtípust ismeretlenként jelzi, az érték típusát pedig mixed-ként határozza meg:

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

A projekt beállításaiban hagyja figyelmen kívül ezt a diagnosztikát a saját típusainál, és tartsa meg a sablonban a típus szűkítését, amely szükséges ahhoz, hogy a PHPStan elfogadja a mixed értéket a max szinten:

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

A fenti beállítással és sablonnal az elemzés sikeres. A 7.6-os verzióban a sablonnak szüksége van a @var sorra is, az egyéni mezők helyén mixed értékekkel; a Blockstudio 7.7-es verziója önállóan következtet erre a szerkezetre, így a sor elhagyható. Az elemzés futtatásához lásd: Ellenőrzött sablonok PHPStan.

Következő lépések

  • Egyéni mezőtípusok: minden definíciós kulcs, a API szűrő és a komponens tulajdonságainak teljes listája.
  • Tárolás: bejegyzés-metaadatok és beállítástárolás bármilyen mezőhöz.
  • Mezőminták szakácskönyve: csoportok, ismétlők és újrafelhasználható mezőszerkezetek.
  • Egyéni mezők: újrafelhasználható mezőcsoportok a custom/{name} segítségével.