Preskoči na vsebino

Vrste polj po meri

Vrste polj po meri omogočajo temi ali vtičniku dodajanje novih kontrolnikov polj Blockstudio. Razlikujejo se od polj po meri:

  • custom/{name} se nanaša na skupino obstoječih polj, ki jo je mogoče znova uporabiti.
  • namespace/type-name uporablja registrirano vrsto polja z lastnim kontrolnikom urejevalnika in obliko vrednosti.

Blockstudio zagotavlja sistem za registracijo. Vaša tema ali vtičnik zagotovi kontrolnik.

Kdaj jih uporabiti

Vrsto polja po meri uporabite, kadar projekt potrebuje namenski kontrolnik za urejanje, ki naj se povsod obnaša kot izvorno polje Blockstudio:

  • atributi blokov
  • skupine polj custom/{name} za večkratno uporabo
  • skupine, zavihki in ponavljalniki
  • predloge PHP, Twig in Blade
  • metapodatki objav in shranjevanje možnosti
  • razširitvene predloge, kot je {attributes.margin.top}

Kontrolnik za razmik lahko na primer shrani en objekt namesto štirih ločenih besedilnih polj:

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

Poimenovanje

Imena vrst polj po meri morajo biti zapisana z malimi črkami, imeti imenski prostor in uporabljati zapis z vezaji:

Text
namespace/type-name

Veljavni primeri:

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

Rezervirani imenski prostori:

  • custom/ je rezerviran za skupine polj po meri za večkratno uporabo.
  • blockstudio/ je rezerviran za jedro Blockstudio.

Neveljavna imena filter API prezre, pomožna funkcija API pa jih zavrne.

Registracija PHP

Metapodatke vrste polja registrirajte 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() vrne true, če je registracija uspešna, in false, če sta ime ali definicija neveljavna. Ročno registracijo lahko odjavite z bs_unregister_field_type().

Uporabite lahko tudi 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;
});

Ključi definicije

Ključ Vrsta Opis
attribute string, array, null Vrsta atributa WordPress. Uporabite string, number, boolean, object, array ali polje teh vrst.
default mixed Privzeta vrednost na ravni registra, kadar polje ne določa svoje privzete vrednosti.
source string Vir atributa WordPress za primere serializacije po meri.
produces_attribute boolean Za kontrolnike, namenjene samo prikazu, nastavite na false. Privzeta vrednost je true.
editor_script string or array Registriran ročaj skripta ali ročaji, ki jih je treba vključiti v urejevalnik blokov, ko je uporabljena ta vrsta.
editor_style string or array Registriran ročaj sloga ali ročaji, ki jih je treba vključiti v urejevalnik blokov, ko je uporabljena ta vrsta.
storage array Namigi za vrsto shranjene vrednosti in shemo REST za metapodatke objave in možnosti.
supports array Izbirne zastavice zmogljivosti za vaš kontrolnik.
translate boolean Nastavite na true, kadar je vrednost besedilo, ki ga mora prevesti WPML. Zahteva attribute string.

Definicija z vrednostjo translate, ki ni logična, ali z nastavitvijo translate na true in vrednostjo attribute, ki ni string, je neveljavna. bs_register_field_type() vrne false, filter API pa jo prezre.

WPML

wp bs wpml config samo na podlagi registracije ne more ugotoviti, ali je vrednost vrste polja po meri besedilo, zato taka polja izpusti in za vsako izpiše opozorilo. V registraciji vrste polja, ki shranjuje navadno besedilo, nastavite translate na true, in ukaz njegova polja obravnava kot polja text. Polje lahko to še vedno izključi z nastavitvijo "translate": false. Glejte WPML.

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

Registracija JavaScript

Skript urejevalnika registrira ustrezni kontrolnik 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() vrne true, če je registracija sprejeta. Registracijo v odjemalcu odstranite tako:

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

Komponenta prejme lastnosti definicije polja in te nespremenljive lastnosti:

Lastnost Opis
type Ime vrste polja.
id ID polja.
field Celotna definicija polja iz block.json.
value Trenutno shranjena vrednost.
defaultValue Privzeta vrednost polja.
onChange Neposredno shrani novo vrednost.
attributes Trenutni atributi bloka.
block Trenutna definicija vrste bloka.
clientId Trenutni ID bloka v odjemalcu urejevalnika.
inRepeater Ali je polje v vrstici ponavljalnika.
repeaterId Trenutna pot ponavljalnika, če obstaja.
disabled Ali je polje v urejevalniku onemogočeno.

Vrednosti vrst polj po meri se shranijo neposredno. Ne gredo skozi normalizacijo možnosti za izvorna polja select, radio, color ali gradient.

Izrisovanje vrednosti

Vrednosti objektov so na voljo kot kateri koli drug 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>

Gnezdene poti objektov delujejo tudi v razširitvenih predlogah:

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

Shranjevanje

Kadar se vrsta polja po meri uporablja s shranjevanjem postMeta ali option, Blockstudio uporabi registrirano vrsto vrednosti za shranjevanje in shemo REST.

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

Za vrednosti array in object določite storage.rest_schema pri registraciji vrste polja. Podrejeni elementi ponavljalnika še naprej uporabljajo shranjevanje na osnovi matrike, ker ponavljalnik shranjuje vrstice.

Nadomestno delovanje

Če PHP pozna vrsto polja, vendar skript urejevalnika ne registrira ustreznega kontrolnika, Blockstudio ohrani shranjeno vrednost in v urejevalniku prikaže obvestilo, ki ga ni mogoče urejati. Izrisovanje na sprednji strani še vedno prejme shranjeno vrednost.

Če vrsta polja ni registrirana v PHP, jo Blockstudio izpusti iz ustvarjenih atributov WordPress. Definicijo PHP registrirajte, preden se začne odkrivanje blokov, običajno v init, preden Blockstudio zgradi bloke.