Gå til indhold

Opbygning af en brugerdefineret felttype

Nogle værdier består af mere end én primitiv værdi. En pris er et beløb og en valuta. Med indbyggede felter modellerer du den som et talfelt og et valgfelt side om side, og hver blok, der viser en pris, gentager parret, etiketterne og logikken, der holder dem sammen. I indlægsmeta bliver det til to nøgler, og i et gentagelsesfelt til to parallelle lister.

En brugerdefineret felttype samler parret i ét felt. Du registrerer en type som acme/price én gang i PHP og i JavaScript og bruger den derefter i enhver block.json som et indbygget felt: på øverste niveau, i grupper og gentagelsesfelter, med lagring i indlægsmeta eller indstillinger samt i skabelonerne PHP, Twig og Blade. Blockstudio udleder attributten WordPress og lagringsskemaet REST fra registreringen.

Dette er noget andet end et brugerdefineret felt. En custom/{name}-reference genbruger en gruppe af eksisterende felter. En brugerdefineret felttype tilføjer en ny styring med sin egen værdistruktur.

Denne vejledning opbygger acme/price fra start til slut: registreringen af PHP, editorstyringen, en prisblok, der bruger den på øverste niveau og i et gentagelsesfelt, lagring i indlægsmeta med et strengt REST-skema og det viste output.

Registrér typen i PHP

PHP-delen angiver attributtypen, standardværdien, editorscriptet, der leverer styringen, og hvordan værdien gemmes uden for blokken:

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 er attributtypen for WordPress, her object. storage.type er dataværditypen, der bruges, når feltet gemmes i indlægsmeta eller indstillinger, og storage.rest_schema er det skema, som WordPress validerer REST-skrivninger imod. Uden en rest_schema får en objektværdi et lempeligt skema, der accepterer alle egenskaber.

Registrér på init med standardprioriteten. Blockstudio finder blokke sent på init, og en type, der ikke er registreret inden da, udelades fra de genererede blokattributter.

bs_register_field_type() returnerer true ved succes og false, hvis navnet eller definitionen er ugyldig. Navne skal være med små bogstaver, have et navnerum og bruge bindestreger, og to navnerum er reserveret:

Navn Resultat
acme/price true
Acme/Price false, ikke små bogstaver
custom/price false, reserveret til genbrugelige feltgrupper
blockstudio/price false, reserveret til Blockstudio-kernen

bs_unregister_field_type() fjerner en registrering igen, og filteret blockstudio/field_types accepterer de samme definitioner som et array indekseret efter navn.

Byg editorstyringen

Scriptet, der blev registreret ovenfor, leverer komponenten React. Det bruger komponenterne WordPress, der allerede er indlæst i editoren, så det kræver intet byggetrin:

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

Komponenten modtager alle egenskaber fra feltdefinitionen, så nøglen currencies, du angiver i block.json, modtages som props.currencies. Den modtager også stabile props: value, onChange, field, defaultValue, attributes, block, clientId, disabled og inRepeater med repeaterId, når den vises i en række i et gentagelsesfelt. onChange gemmer værdien præcis som angivet. Brugerdefinerede værdier springer den normalisering af indstillinger over, som indbyggede felter af typerne select, radio, color og gradient udfører.

Kontrollér, at værdierne er objekter, som de første linjer gør. En blok, der blev gemt, før feltet fandtes, eller med en anden struktur, skal stadig kunne åbnes i editoren.

Blockstudio indlæser acme-field-price i blokeditoren kun, når en blok, der bruger acme/price, er registreret. Hvis scriptet ikke registrerer styringen, beholder editoren den gemte værdi og viser en ikke-redigerbar besked i stedet for feltet, og frontend viser stadig værdien.

Brug den i en blok

En prisblok bruger typen to gange: én gang til en startpris, der skal kunne forespørges på uden for blokken, og én gang for hver række i et gentagelsesfelt med prisniveauer:

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

Et feltværdiniveau default har forrang over standardværdien i registret. Blockstudio gør begge felter til WordPress-attributter fra registreringen. Den registrerede bloktype indeholder:

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

Vis værdien

I skabelonen er værdien et almindeligt array. Begræns typen, før du bruger den, for en gemt værdi er kun så pålidelig som det seneste sted, der skrev til den:

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() er vigtig. Et gentagelsesfelt uden rækker kommer til skabelonen som false, ikke som et tomt array, og et ubetinget foreach over det udløser en PHP-advarsel. Linjen @var forklares under statisk analyse nedenfor.

Sådan vises blokken med en startpris og to prisniveauer:

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>

Uden data anvendes feltets standardværdi, og blokken vises som From 19.00 EUR uden prisniveauer. Twig og Blade læser den samme værdi som a.price.amount og $a['price']['amount'], og skabeloner med extension kan tilgå den som {attributes.price.amount}.

Lagring og skemaet REST

Begge felter angiver lagring i postMeta, så Blockstudio registrerer to metanøgler, når blokken oprettes. Feltet på øverste niveau bruger lagringsskemaet fra registreringen uændret:

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

Feltet i gentagelsesfeltet gemmer én værdi pr. række, så dets metanøgle er arraybaseret, og det samme skema bliver elementschemaet:

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

Når et indlæg, der indeholder blokken, gemmes, synkroniseres begge nøgler. Med de to prisniveauer ovenfor returnerer get_post_meta( $id, 'acme_price', true ) {"amount":19,"currency":"EUR"}, og acme_tier_prices returnerer listen med priser for rækkerne:

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

Begge nøgler vises i indlæggets svar fra REST under meta, og skrivninger til REST valideres mod skemaet. En skrivning med en valuta med små bogstaver afvises:

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

Meta er en kopi. Blokattributterne i indlæggets indhold forbliver kilden, og hver lagring synkroniserer dem igen med de konfigurerede nøgler. Derfor erstattes en værdi, der skrives direkte til meta, næste gang indlægget gemmes. Lagring i indstillinger fungerer på samme måde via register_setting(). Brugerdefinerede felttyper, herunder arraybaseret lagring i gentagelsesfelter, har været tilgængelige siden Blockstudio 7.5.0.

Statisk analyse

Udvidelsen PHPStan kender de indbyggede felttyper, men ikke dem, et projekt registrerer ved kørsel. For en blok, der bruger acme/price, rapporterer den felttypen som ukendt og angiver værditypen som mixed:

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

Ignorér denne diagnosticering for dine egne typer i projektkonfigurationen, og behold typebegrænsningen i skabelonen, som PHPStan skal bruge for at acceptere værdien mixed på niveau max:

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

Med denne konfiguration og skabelonen ovenfor består analysen. På 7.6 kræver skabelonen også linjen @var med mixed på pladserne for de brugerdefinerede felter. Fra og med 7.7 udleder Blockstudio selv den struktur, så linjen kan fjernes. Se Kontrollerede skabeloner med PHPStan for at køre analysen.

Næste trin