Přejít k obsahu

Vlastní typy polí

Vlastní typy polí umožňují šabloně nebo pluginu přidat nové ovládací prvky polí Blockstudio. Liší se od vlastních polí:

  • custom/{name} odkazuje na opakovaně použitelnou skupinu existujících polí.
  • namespace/type-name používá registrovaný typ pole s vlastním ovládacím prvkem editoru a tvarem hodnoty.

Blockstudio poskytuje registrační systém. Ovládací prvek dodává vaše šablona nebo plugin.

Kdy je použít

Vlastní typ pole použijte, když projekt potřebuje jednoúčelový ovládací prvek pro úpravy, který se má všude chovat jako nativní pole Blockstudio:

  • atributy bloků
  • opakovaně použitelné skupiny polí custom/{name}
  • skupiny, karty a opakovače
  • šablony PHP, Twig a Blade
  • metadata příspěvků a ukládání nastavení
  • rozšiřující šablony, jako je {attributes.margin.top}

Například ovládací prvek pro rozestupy může ukládat jeden objekt místo čtyř 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"
        }
      }
    ]
  }
}

Pojmenování

Názvy vlastních typů polí musí být psány malými písmeny, musí být opatřené jmenným prostorem a používat pomlčky:

Text
namespace/type-name

Platné příklady:

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

Rezervované jmenné prostory:

  • custom/ je vyhrazeno pro opakovaně použitelné skupiny vlastních polí.
  • blockstudio/ je vyhrazeno pro jádro Blockstudio.

Neplatné názvy filtr API ignoruje a pomocná funkce API odmítne.

Registrace PHP

Zaregistrujte metadata typu pole 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() vrací true, pokud registrace uspěje, a false, pokud je název nebo definice neplatná. Ruční registraci můžete zrušit pomocí bs_unregister_field_type().

Můžete také použít filtr API:

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

    return $types;
});

Klíče definice

Klíč Typ Popis
attribute string, array, null Typ atributu WordPress. Použijte string, number, boolean, object, array nebo pole těchto typů.
default mixed Výchozí hodnota na úrovni registru, pokud pole nemá definovanou vlastní výchozí hodnotu.
source string Zdroj atributu WordPress pro vlastní případy serializace.
produces_attribute boolean Pro ovládací prvky určené pouze k zobrazení nastavte na false. Výchozí hodnota je true.
editor_script string or array Registrovaný skript nebo skripty, které se mají zařadit do editoru bloků, když se tento typ použije.
editor_style string or array Registrovaný styl nebo styly, které se mají zařadit do editoru bloků, když se tento typ použije.
storage array Typ ukládané hodnoty a náznaky schématu REST pro metadata příspěvků a možnosti.
supports array Volitelné příznaky schopností pro vlastní ovládací prvek.
translate boolean Nastavte na true, pokud je hodnota text určený k překladu pomocí WPML. Vyžaduje attribute string.

Definice s hodnotou translate, která není typu boolean, nebo s translate nastaveným na true a hodnotou attribute jinou než string, je neplatná. bs_register_field_type() vrací false a filtr API ji ignoruje.

WPML

wp bs wpml config nedokáže pouze z registrace určit, zda je hodnota vlastního typu pole text, proto taková pole vynechá a u každého vypíše upozornění. V registraci typu pole, který ukládá prostý textový řetězec, nastavte translate na true; příkaz pak jeho pole deklaruje jako pole typu text. Pole se může z této možnosti stále vyřadit pomocí "translate": false. Viz WPML.

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

Registrace JavaScript

Skript editoru registruje odpovídající ovládací prvek 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() vrací true, pokud je registrace přijata. Registraci na straně klienta odeberte takto:

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

Komponenta dostává vlastnosti definice pole a také tyto stabilní vlastnosti:

Vlastnost Popis
type Název typu pole.
id ID pole.
field Úplná definice pole z block.json.
value Aktuální uložená hodnota.
defaultValue Výchozí hodnota pole.
onChange Uloží novou hodnotu přímo.
attributes Aktuální atributy bloku.
block Aktuální definice typu bloku.
clientId ID bloku klienta v aktuálním editoru.
inRepeater Zda je pole uvnitř řádku opakovače.
repeaterId Aktuální cesta opakovače, pokud existuje.
disabled Zda je pole v editoru zakázáno.

Hodnoty vlastních typů polí se ukládají přímo. Neprocházejí normalizací možností nativních select, radio, color ani gradient.

Vykreslování hodnot

Hodnoty objektů jsou dostupné stejně jako jakýkoli jiný atribut 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 šablonách rozšíření fungují také vnořené cesty k objektům:

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

Ukládání

Když se vlastní typ pole používá s úložištěm postMeta nebo option, Blockstudio využívá registrovaný typ ukládané hodnoty a schéma REST.

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

U hodnot array a object definujte storage.rest_schema při registraci typu pole. Potomci opakovače nadále používají úložiště založené na polích, protože opakovač ukládá řádky.

Záložní chování

Pokud PHP zná typ pole, ale skript editoru nezaregistruje odpovídající ovládací prvek, Blockstudio zachová uloženou hodnotu a v editoru zobrazí upozornění, které nelze upravit. Frontendové vykreslování stále dostane uloženou hodnotu.

Pokud typ pole není zaregistrován v PHP, Blockstudio jej vynechá z vygenerovaných atributů WordPress. Zaregistrujte definici PHP ještě před spuštěním zjišťování bloků, obvykle v init předtím, než Blockstudio sestaví bloky.