Siirry sisältöön

Mukautetun kenttätyypin rakentaminen

Jotkin arvot koostuvat useammasta kuin yhdestä alkeisarvosta. Hinta muodostuu summasta ja valuutasta. Sisäänrakennetuilla kentillä mallinnat sen rinnakkain numero- ja valintakenttinä, ja jokainen hintaa näyttävä lohko toistaa kenttäparin, otsakkeet ja niiden yhteisen logiikan. Artikkelin metatiedoissa siitä tulee kaksi avainta ja toistimessa kaksi rinnakkaista luetteloa.

Mukautettu kenttätyyppi kokoaa parin yhdeksi kentäksi. Rekisteröit esimerkiksi tyypin acme/price kerran kohteissa PHP ja JavaScript, minkä jälkeen voit käyttää sitä missä tahansa block.json-kohteessa natiivikentän tavoin: ylimmällä tasolla, ryhmissä ja toistimissa, artikkelin metatietojen tai asetusten tallennuksessa sekä malleissa PHP, Twig ja Blade. Blockstudio johtaa rekisteröinnistä WordPress-attribuutin ja tallennuksen REST-skeeman.

Tämä eroaa mukautetusta kentästä. custom/{name}-viittaus käyttää uudelleen olemassa olevien kenttien ryhmää. Mukautettu kenttätyyppi lisää uuden ohjaimen, jolla on oma arvorakenteensa.

Tässä oppaassa rakennetaan acme/price alusta loppuun: PHP-rekisteröinti, editorin ohjaus, hinnoittelulohko, joka käyttää kenttää sekä ylimmällä tasolla että toistimessa, artikkelin metatietojen tallennus tiukalla REST-skeemalla ja tulostettu sisältö.

Rekisteröi tyyppi kohteessa PHP

PHP-puoli määrittää attribuutin tyypin, oletusarvon, ohjaimen tarjoavan editoriskriptin ja tavan, jolla arvo tallennetaan lohkon ulkopuolelle:

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 attribuutin WordPress-tyyppi, tässä tapauksessa object. storage.type on arvotyyppi, jota käytetään, kun kenttä tallennetaan artikkelin metatietoihin tai asetuksiin. storage.rest_schema on skeema, jota vasten WordPress validoi REST-kirjoitukset. Ilman rest_schema-määritystä oliot saavat sallivan skeeman, joka hyväksyy kaikki ominaisuudet.

Rekisteröi kohteessa init oletusprioriteetilla. Blockstudio löytää lohkot myöhään kohteessa init, ja tyyppi, jota ei ole siihen mennessä rekisteröity, jää pois luoduista lohkoattribuuteista.

bs_register_field_type() palauttaa arvon true onnistuessaan ja false, jos nimi tai määritys on virheellinen. Nimien on oltava pienaakkosilla kirjoitettuja, nimiavaruudellisia ja tavuviivamuotoisia. Kaksi nimiavaruutta on varattu:

Nimi Tulos
acme/price true
Acme/Price false, ei pienaakkosilla
custom/price false, varattu uudelleenkäytettäville kenttäryhmille
blockstudio/price false, varattu Blockstudio-ytimelle

bs_unregister_field_type() poistaa rekisteröinnin, ja blockstudio/field_types-suodatin hyväksyy samat määritykset nimillä avaimiksi järjestettynä taulukkona.

Rakenna editorin ohjaus

Edellä rekisteröity skripti tarjoaa komponentin React. Se käyttää editorissa jo ladattuja WordPress-komponentteja, joten koontivaihetta ei tarvita:

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

Komponentti saa kaikki kentän määrityksen ominaisuudet, joten kohteeseen block.json lisäämäsi avain currencies välittyy sille arvona props.currencies. Se saa myös vakaat ominaisuudet: value, onChange, field, defaultValue, attributes, block, clientId, disabled ja inRepeater sekä arvon repeaterId, kun se piirretään toistimen rivin sisällä. onChange tallentaa arvon täsmälleen annetussa muodossa. Mukautetut arvot ohittavat normalisoinnin, jota natiivikentät select, radio, color ja gradient käyttävät.

Kuten ensimmäisillä riveillä tehdään, varmista, etteivät arvot ole muita kuin olioita. Ennen kentän olemassaoloa tallennetun tai rakenteeltaan erilaisen lohkon pitäisi silti avautua editorissa.

Blockstudio ottaa acme-field-price-skriptin käyttöön lohkoeditorissa vain, jos kohdetta acme/price käyttävä lohko on rekisteröity. Jos ohjaimen rekisteröinti epäonnistuu, editori säilyttää tallennetun arvon ja näyttää kentän sijaan ilmoituksen, jota ei voi muokata. Käyttöliittymässä arvo näkyy silti.

Käytä sitä lohkossa

Hinnoittelulohko käyttää tyyppiä kahdesti: kerran aloitushintaan, jota voi hakea lohkon ulkopuolelta, ja kerran jokaisella porrastoistimen rivillä:

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

Kenttätason default ohittaa rekisterin oletusarvon. Blockstudio muuttaa molemmat kentät rekisteröinnin mukaisiksi WordPress-attribuuteiksi. Rekisteröity lohkotyyppi sisältää:

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

Tulosta arvo

Arvo on mallissa tavallinen taulukko. Rajaa se ennen käyttöä, sillä tallennettu arvo on vain yhtä luotettava kuin viimeisin siihen kirjoittanut toiminto:

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 tärkeä. Kun toistimessa ei ole rivejä, malli saa arvoksi false eikä tyhjää taulukkoa, ja paljas foreach sen päällä aiheuttaa PHP-varoituksen. @var-rivi selitetään alla kohdassa staattinen analyysi.

Hinnoittelulohkon tulostus aloitushinnalla ja kahdella hintaportaalla:

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>

Kun tietoja ei ole lainkaan, kentän oletusarvo tulee voimaan ja lohko tulostetaan ilman portaita arvolla From 19.00 EUR. Twig ja Blade lukevat saman arvon kuin a.price.amount ja $a['price']['amount'], ja laajennus-malleissa siihen pääsee käsiksi arvona {attributes.price.amount}.

Tallennus ja REST-skeema

Molemmissa kentissä on postMeta-tallennus, joten Blockstudio rekisteröi lohkoa rakentaessaan kaksi meta-avainta. Ylimmän tason kenttä käyttää rekisteröityä tallennusskeemaa sellaisenaan:

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

Toistimen sisällä oleva kenttä tallentaa yhden arvon riviä kohden, joten sen meta-avain perustuu taulukkoon ja samasta skeemasta tulee alkioskeema:

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

Lohkon sisältävän artikkelin tallentaminen synkronoi molemmat avaimet. Edellä mainittujen kahden hintaportaan kanssa get_post_meta( $id, 'acme_price', true ) palauttaa arvon {"amount":19,"currency":"EUR"} ja acme_tier_prices palauttaa rivihintojen luettelon:

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

Molemmat avaimet näkyvät artikkelin REST-vastauksessa kohteessa meta, ja REST-kirjoitukset validoidaan skeemaa vasten. Pienillä kirjaimilla kirjoitettu valuutta hylätään:

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

Meta on kopio. Artikkelin sisällön lohkoattribuutit pysyvät lähteenä, ja jokainen tallennus synkronoi ne uudelleen määritettyihin avaimiin. Siksi suoraan metaan kirjoitettu arvo korvataan, kun artikkeli tallennetaan seuraavan kerran. Asetusten tallennus toimii samalla tavoin kohteen register_setting() kautta. Mukautetut kenttätyypit, myös toistimien taulukkomuotoinen tallennus, ovat käytettävissä versiosta Blockstudio 7.5.0 lähtien.

Staattinen analyysi

PHPStan-laajennus tuntee sisäänrakennetut kenttätyypit, mutta ei projektissa suorituksen aikana rekisteröityjä tyyppejä. Kun lohko käyttää tyyppiä acme/price, laajennus ilmoittaa kenttätyypin tuntemattomaksi ja määrittää sen arvon tyypiksi mixed:

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

Ohita tämä diagnostiikkailmoitus projektin omien tyyppien osalta projektin määrityksissä ja säilytä mallin rajaus. Sitä tarvitaan, jotta PHPStan hyväksyy mixed-arvon tasolla max:

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

Näillä määrityksillä ja edellä esitetyllä mallilla analyysi onnistuu. Versiossa 7.6 malli tarvitsee myös rivin @var, jossa mukautettujen kenttien kohdilla käytetään arvoja mixed. Blockstudio 7.7 päättelee rakenteen itse, joten rivin voi poistaa. Katso Tarkistetut mallit kohteella PHPStan-analyysin suorittamisesta.

Seuraavat vaiheet