Ugrás a tartalomhoz

Egyéni mezőtípusok

Az egyéni mezőtípusok lehetővé teszik, hogy egy téma vagy bővítmény új Blockstudio mezővezérlőket adjon hozzá. Ezek különböznek az egyéni mezőktől:

  • A custom/{name} meglévő mezők újrafelhasználható csoportjára hivatkozik.
  • A namespace/type-name saját szerkesztővezérlővel és értékszerkezettel rendelkező regisztrált mezőtípust használ.

A Blockstudio biztosítja a regisztrációs rendszert. A vezérlőt a téma vagy bővítmény biztosítja.

Mikor használja őket

Akkor használjon egyéni mezőtípust, ha a projektnek olyan egyetlen célra szolgáló szerkesztővezérlőre van szüksége, amely mindenhol natív Blockstudio mezőként működik:

  • blokkattribútumok
  • újrafelhasználható custom/{name} mezőcsoportok
  • csoportok, fülek és ismétlők
  • PHP, Twig és Blade sablonok
  • bejegyzésmetaadatok és beállítások tárolása
  • bővítménysablonok, például {attributes.margin.top}

Például egy térközvezérlő négy külön szövegmező helyett egyetlen objektumot tárolhat:

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

Elnevezés

Az egyéni mezőtípusok neveinek kisbetűsnek, névtérrel ellátottnak és kötőjeles formátumúnak kell lenniük:

Text
namespace/type-name

Érvényes példák:

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

Fenntartott névterek:

  • A custom/ az újrafelhasználható egyéni mezőcsoportok számára van fenntartva.
  • A blockstudio/ a Blockstudio alapcsomag számára van fenntartva.

Az érvénytelen neveket a API szűrő figyelmen kívül hagyja, a API segédfüggvény pedig elutasítja.

PHP regisztráció

Regisztrálja a mezőtípus metaadatait a PHP fájlban:

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

A bs_register_field_type() sikeres regisztráció esetén true értéket ad vissza, érvénytelen név vagy definíció esetén pedig false értéket. A kézi regisztrációt a bs_unregister_field_type() segítségével vonhatja vissza.

Használhatja a API szűrőt is:

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

    return $types;
});

Definíciós kulcsok

Kulcs Típus Leírás
attribute string, array, null WordPress attribútumtípus. Használja a string, number, boolean, object, array értékek egyikét vagy ezek tömbjét.
default vegyes Regiszterszintű alapértelmezett érték, ha egy mező nem határoz meg saját alapértelmezett értéket.
source karakterlánc WordPress attribútumforrás egyéni szerializálási esetekhez.
produces_attribute logikai Állítsa false értékre a csak megjelenítésre szolgáló vezérlőknél. Alapértelmezett értéke true.
editor_script karakterlánc vagy tömb A blokk szerkesztőben használt típushoz betöltendő regisztrált parancsfájl-azonosító vagy -azonosítók.
editor_style karakterlánc vagy tömb A blokk szerkesztőben használt típushoz betöltendő regisztrált stílusazonosító vagy -azonosítók.
storage tömb A tárolási érték típusa és REST sématippjei a bejegyzésmetához és a beállításokhoz.
supports tömb Opcionális képességjelzők a saját vezérlőhöz.
translate logikai Állítsa true értékre, ha az érték a WPML által fordítandó szöveg. Ehhez szükséges: attribute string.

Érvénytelen az a definíció, amelynek translate értéke nem logikai, vagy amelyben a translate értéke true, az attribute pedig nem string. A bs_register_field_type() false értéket ad vissza, a API szűrő pedig figyelmen kívül hagyja.

WPML

wp bs wpml config a regisztráció alapján nem tudja megállapítani, hogy az egyéni mezőtípus értéke szöveg-e, ezért kihagyja az ilyen mezőket, és mindegyikhez figyelmeztetést jelenít meg. Állítsa a translate értékét true-re a sima szöveges karakterláncot tároló mezőtípus regisztrációjában, és a parancs az ilyen mezőket text mezőkként deklarálja. A mezők a "translate": false használatával továbbra is kihagyhatók. Lásd: WPML.

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

JavaScript regisztráció

A szerkesztőszkript regisztrálja a hozzá tartozó React vezérlőt:

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

A registerFieldType() akkor adja vissza a true értéket, ha a regisztrációt elfogadja. Az ügyféloldali regisztráció eltávolítása:

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

A komponens megkapja a meződefiníció tulajdonságait, valamint ezeket az állandó tulajdonságokat:

Tulajdonság Leírás
type Mezőtípus neve.
id Mezőazonosító.
field A teljes meződefiníció innen: block.json.
value Jelenleg mentett érték.
defaultValue A mező alapértelmezett értéke.
onChange Új érték közvetlen mentése.
attributes Aktuális blokkattribútumok.
block Aktuális blokk típusának definíciója.
clientId Aktuális szerkesztőblokk ügyfélazonosítója.
inRepeater A mező ismétlősorban van-e.
repeaterId Aktuális ismétlőútvonal, ha van.
disabled A mező le van-e tiltva a szerkesztőben.

Az egyéni mezőtípusok értékei közvetlenül tárolódnak. Nem esnek át a natív select, radio, color vagy gradient beállításnormalizáláson.

Értékek megjelenítése

Az objektumértékek ugyanúgy elérhetők, mint bármely más Blockstudio attribútum.

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>

A beágyazott objektumútvonalak is működnek a bővítménysablonokban:

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

Tárolás

Ha egyéni mezőtípust használ a postMeta vagy a option tárolással, a Blockstudio a regisztrált tárolási értéktípust és a REST sémát használja.

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

A array és object értékeknél határozza meg a storage.rest_schema értéket a mezőtípus regisztrációjában. Az ismétlők leszármazottai továbbra is tömbalapú tárolást használnak, mivel az ismétlő sorokat tárol.

Visszaesési viselkedés

Ha a PHP ismeri a mezőtípust, de a szerkesztőszkript nem regisztrál hozzá illő vezérlőt, a Blockstudio megőrzi a mentett értéket, és nem szerkeszthető értesítést jelenít meg a szerkesztőben. A frontend megjelenítése továbbra is megkapja a mentett értéket.

Ha a mezőtípus nincs regisztrálva a PHP rendszerben, a Blockstudio kihagyja a létrehozott WordPress attribútumokból. Regisztrálja a PHP definíciót a blokkok felderítése előtt, általában a init ponton, mielőtt a Blockstudio létrehozza a blokkokat.