Preskočiť na obsah

Vlastné typy polí

Typy vlastných polí umožňujú téme alebo pluginu pridať nové Blockstudio ovládacie prvky polí. Líšia sa od vlastných polí:

  • custom/{name} odkazuje na opätovne použiteľnú skupinu existujúcich polí.
  • namespace/type-name používa zaregistrovaný typ poľa s vlastným ovládacím prvkom editora a štruktúrou hodnoty.

Blockstudio poskytuje registračný systém. Ovládací prvok dodáva vaša téma alebo plugin.

Kedy ich použiť

Vlastný typ poľa použite, keď projekt potrebuje jednoúčelový ovládací prvok úprav, ktorý sa má všade správať ako natívne pole Blockstudio:

  • atribúty bloku
  • opätovne použiteľné skupiny polí custom/{name}
  • skupiny, karty a opakovače
  • šablóny PHP, Twig a Blade
  • metaúdaje príspevku a ukladanie nastavení
  • rozširujúce šablóny, napríklad {attributes.margin.top}

Napríklad ovládací prvok rozostupov môže ukladať jeden objekt namiesto štyroch samostatných textových polí:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Pomenovanie

Názvy vlastných typov polí musia byť napísané malými písmenami, mať menný priestor a používať pomlčky:

Text
namespace/type-name

Platné príklady:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Rezervované menné priestory:

  • custom/ je rezervovaný pre opätovne použiteľné skupiny vlastných polí.
  • blockstudio/ je rezervovaný pre jadro Blockstudio.

Neplatné názvy filter API ignoruje a pomocná funkcia API odmietne.

Registrácia PHP

Zaregistrujte metadáta typu poľa v PHP:

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

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});

bs_register_field_type() vracia true, keď sa registrácia podarí, a false, keď je názov alebo definícia neplatná. Ručnú registráciu môžete zrušiť pomocou bs_unregister_field_type().

Môžete tiež použiť filter API:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

Kľúče definície

Kľúč Typ Popis
attribute string, array, null Typ atribútu WordPress. Použite string, number, boolean, object, array alebo pole týchto typov.
default mixed Predvolená hodnota na úrovni registra, ak pole nemá vlastnú predvolenú hodnotu.
source string Zdroj atribútu WordPress pre vlastné prípady serializácie.
produces_attribute boolean Pri ovládacích prvkoch určených iba na zobrazenie nastavte na false. Predvolená hodnota je true.
editor_script string or array Registrovaný identifikátor skriptu alebo identifikátory, ktoré sa majú zaradiť do frontu v editore blokov pri použití daného typu.
editor_style string or array Registrovaný identifikátor štýlu alebo identifikátory, ktoré sa majú zaradiť do frontu v editore blokov pri použití daného typu.
storage array Typ ukladanej hodnoty a náznaky schémy REST pre metaúdaje príspevkov a možnosti.
supports array Voliteľné príznaky schopností pre vlastný ovládací prvok.
translate boolean Ak je hodnota textom určeným na preklad pomocou WPML, nastavte na true. Vyžaduje attribute string.

Definícia s hodnotou translate, ktorá nie je booleovská, alebo s translate nastaveným na true a hodnotou attribute odlišnou od string, je neplatná. bs_register_field_type() vráti false a filter API ju ignoruje.

WPML

wp bs wpml config nedokáže z registrácie samotnej určiť, či je hodnota vlastného typu poľa textom, preto takéto polia vynechá a pri každom vypíše upozornenie. Pri registrácii typu poľa, ktorý ukladá obyčajný textový reťazec, nastavte translate na true a príkaz bude jeho polia deklarovať ako polia text. Pole možno stále vynechať pomocou "translate": false. Pozrite si WPMLdokumentáciu.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

Registrácia JavaScript

Skript editora zaregistruje zodpovedajúci ovládací prvok React:

JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

registerFieldType() vráti true, keď je registrácia prijatá. Registráciu na strane klienta odstráňte takto:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

Komponent dostane vlastnosti definície poľa a tieto stabilné vlastnosti:

Vlastnosť Opis
type Názov typu poľa.
id ID poľa.
field Úplná definícia poľa z block.json.
value Aktuálna uložená hodnota.
defaultValue Predvolená hodnota poľa.
onChange Uloží novú hodnotu priamo.
attributes Aktuálne atribúty bloku.
block Aktuálna definícia typu bloku.
clientId Aktuálne ID bloku na strane klienta v editore.
inRepeater Informácia, či je pole v riadku opakovača.
repeaterId Aktuálna cesta k opakovaču, ak existuje.
disabled Informácia, či je pole v editore zakázané.

Hodnoty typov vlastných polí sa ukladajú priamo. Neprechádzajú normalizáciou natívnych možností select, radio, color ani gradient.

Vykresľovanie hodnôt

Hodnoty objektov sú dostupné rovnako ako akýkoľvek iný atribút Blockstudio.

PHP

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

V šablónach rozšírení fungujú aj vnorené cesty k objektom:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Ukladanie

Keď sa vlastný typ poľa používa s úložiskom postMeta alebo option, Blockstudio používa zaregistrovaný typ ukladanej hodnoty a schému REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

Pre hodnoty array a object definujte storage.rest_schema v registrácii typu poľa. Potomkovia opakovača naďalej používajú úložisko založené na poliach, pretože opakovač ukladá riadky.

Záložné správanie

Ak PHP pozná typ poľa, ale skript editora nezaregistruje zodpovedajúci ovládací prvok, Blockstudio zachová uloženú hodnotu a zobrazí v editore upozornenie, ktoré nemožno upravovať. Vykresľovanie na frontende naďalej dostáva uloženú hodnotu.

Ak typ poľa nie je zaregistrovaný v PHP, Blockstudio ho vynechá z vygenerovaných atribútov WordPress. Definíciu PHP zaregistrujte ešte pred spustením zisťovania blokov, zvyčajne v init predtým, ako Blockstudio vytvorí bloky.