Liigu sisu juurde

Kohandatud väljatüübi loomine

Mõned väärtused koosnevad rohkemast kui ühest algtüübist. Hind koosneb summast ja valuutast. Sisseehitatud väljade puhul modelleeritakse see kõrvuti oleva numbri- ja valikuväljana ning iga hinda kuvav plokk kordab seda paari, silte ja neid koos hoidvat loogikat. Postituse metaandmetes muutub see kaheks võtmeks ja kordajas kaheks paralleelseks loendiks.

Kohandatud väljatüüp muudab selle paari üheks väljaks. Registreerid tüübi, näiteks acme/price, üks kord nii PHP-is kui ka JavaScript-is ning kasutad seda seejärel igas block.json-is nagu algupärast välja: tipptasemel, rühmades ja kordajates, postituse metaandmete või suvandite salvestusega ning mallides PHP, Twig ja Blade. Blockstudio tuletab registreeringust WordPress atribuudi ja salvestuse REST skeemi.

See erineb kohandatud väljast. custom/{name} viide kasutab olemasolevat väljade rühma uuesti. Kohandatud väljatüüp lisab uue juhtelemendi, millel on oma väärtuse kuju.

See juhend loob acme/price otsast lõpuni: PHP registreeringu, redaktori juhtelemendi, hinnaploki, mis kasutab seda nii tipptasemel kui ka kordaja sees, postituse metaandmete salvestuse range REST skeemiga ja renderdatud väljundi.

Registreeri tüüp PHP-is

PHP-i poolel määratakse atribuudi tüüp, vaikeväärtus, juhtelemendi pakkuv redaktori skript ja see, kuidas väärtus salvestatakse väljaspool plokki:

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 on atribuudi WordPress tüüp, siin object. storage.type on väärtuse tüüp, mida kasutatakse välja salvestamisel post meta’sse või valikutesse, ning storage.rest_schema on skeem, mille alusel WordPress kontrollib kirjutatavaid väärtusi REST. Kui rest_schema puudub, saab objektiväärtus lubava skeemi, mis aktsepteerib kõiki omadusi.

Registreeri init vaikimisi prioriteediga. Blockstudio avastab plokid hilja init-is ning selleks ajaks registreerimata tüüpi ei lisata loodud plokiatribuutidele.

bs_register_field_type() tagastab õnnestumisel true ja vigase nime või määratluse korral false. Nimed peavad olema väiketähtedes, nimeruumiga ja sidekriipsudega eraldatud ning kaks nimeruumi on reserveeritud:

Nimi Tulemus
acme/price true
Acme/Price false, mitte väiketähtedes
custom/price false, reserveeritud korduvkasutatavatele väljarühmadele
blockstudio/price false, reserveeritud Blockstudio tuumiku jaoks

bs_unregister_field_type() eemaldab registreeringu ning filter blockstudio/field_types aktsepteerib samu määratlusi nimede järgi võtmetega massiivina.

Redaktori juhtelemendi loomine

Eespool registreeritud skript pakub komponenti React. See kasutab WordPress komponente, mis on redaktoris juba laaditud, seega pole koostamisetappi vaja:

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

Komponent saab kõik välja määratluse omadused, seega saab block.json lisatud võti currencies väärtuseks props.currencies. Samuti saab see stabiilsed atribuudid: value, onChange, field, defaultValue, attributes, block, clientId, disabled ja inRepeater koos väärtusega repeaterId, kui see kuvatakse kordaja real. onChange salvestab väärtuse täpselt etteantud kujul. Kohandatud väärtused jätavad vahele valikute normaliseerimise, mida rakendavad natiivsed select, radio, color ja gradient väljad.

Kontrolli väärtust, et see poleks objekt, nagu tehakse esimestel ridadel. Enne välja olemasolu või teistsuguse struktuuriga salvestatud plokk peaks redaktoris siiski avanema.

Blockstudio lisab redaktoris acme-field-price järjekorda ainult siis, kui registreeritud on plokk, mis kasutab acme/price. Kui skriptil ei õnnestu juhtelementi registreerida, säilitab redaktor salvestatud väärtuse ja kuvab välja asemel mitteredigeeritava teate; kasutajaliideses renderdatakse väärtus ikkagi.

Kasuta seda plokis

Hinnaplokk kasutab tüüpi kaks korda: kord väljaspool plokki päringutega leitava alghinna jaoks ning kord iga kordaja hinnataseme rea kohta:

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

Väljataseme default on registri vaikeväärtusest ülimuslik. Blockstudio muudab mõlemad väljad registreeringust saadud WordPress atribuutideks. Registreeritud plokitüüp sisaldab järgmist:

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

Renderda väärtus

Mallis on väärtus tavaline massiiv. Piira selle tüüpi enne kasutamist, sest salvestatud väärtus on täpselt nii usaldusväärne, kui usaldusväärne oli viimane selle kirjutanud allikas:

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>

?: array() on oluline. Ilma ridadeta kordaja jõuab mallini väärtusena false, mitte tühja massiivina, ning selle otsene foreach põhjustab PHP hoiatuse. Rida @var selgitatakse allpool jaotises staatiline analüüs.

Ploki renderdamine alghinna ja kahe hinnatasemega:

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>

Ilma andmeteta rakendub välja vaikeväärtus ja plokk renderdatakse väärtusega From 19.00 EUR, ilma hinnatasemeteta. Twig ja Blade loevad sama väärtust nagu a.price.amount ja $a['price']['amount'] ning laiendus mallides saab sellele viidata kui {attributes.price.amount}.

Salvestus ja REST skeem

Mõlemad väljad määravad postMeta salvestuse, seega registreerib Blockstudio ploki loomisel kaks meta võtit. Tipptaseme väli kasutab registreeritud salvestusskeemi muutmata kujul:

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

Kordaja sees olev väli salvestab ühe väärtuse rea kohta, seega põhineb selle meta võti massiivil ja samast skeemist saab üksuse skeem:

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

Plokki sisaldava postituse salvestamisel sünkroonitakse mõlemad võtmed. Eespool toodud kahe hinnataseme puhul tagastab get_post_meta( $id, 'acme_price', true ) väärtuse {"amount":19,"currency":"EUR"} ja acme_tier_prices tagastab reahindade loendi:

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

Mõlemad võtmed kuvatakse postituse REST vastuses jaotises meta ning REST kirjutusi valideeritakse skeemi alusel. Väiketähtedega valuutat sisaldav kirjutus lükatakse tagasi:

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

Metaandmed on koopia. Postituse sisus olevad plokiatribuudid jäävad algallikaks ning iga salvestamine sünkroonib need seadistatud võtmetega uuesti; seega asendatakse otse metaandmetesse kirjutatud väärtus järgmisel postituse salvestamisel. Suvandite salvestus toimib samamoodi register_setting() kaudu. Kohandatud väljatüübid, sealhulgas kordajates massiivil põhinev salvestus, on saadaval alates versioonist Blockstudio 7.5.0.

Staatiline analüüs

PHPStan laiendus tunneb sisseehitatud väljatüüpe, mitte neid, mida projekt käitusajal registreerib. Tüüpi acme/price kasutaval plokil teatab see väljatüübi tundmatuks ja väärtuse tüübiks mixed:

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

Eira projekti seadistuses oma tüüpide puhul seda diagnostikateadet ning jäta tüübi kitsendamine mallis alles; seda vajab PHPStan, et aktsepteerida mixed väärtust tasemel max:

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

Selle seadistuse ja ülaltoodud malliga analüüs õnnestub. Versioonis 7.6 vajab mall ka rida @var, kus kohandatud väljade kohtadel on mixed; Blockstudio 7.7 tuletab selle struktuuri ise ja rea võib eemaldada. Analüüsi käivitamise kohta vt kontrollitud mallid koos PHPStan.

Järgmised sammud