Siirry sisältöön

Mukautetut kenttätyypit

Mukautettujen kenttätyyppien avulla teema tai lisäosa voi lisätä uusia Blockstudio-kenttäohjaimia. Ne eroavat mukautetuista kentistä:

  • custom/{name} viittaa uudelleenkäytettävään ryhmään olemassa olevia kenttiä.
  • namespace/type-name käyttää rekisteröityä kenttätyyppiä, jolla on oma editorin ohjaimensa ja arvomuotonsa.

Blockstudio sisältää rekisteröintijärjestelmän. Teema tai lisäosa sisältää ohjaimen.

Milloin niitä käytetään

Käytä mukautettua kenttätyyppiä, kun projekti tarvitsee yhteen tarkoitukseen suunnitellun muokkausohjaimen, jonka tulee toimia kaikkialla kuten natiivi Blockstudio-kenttä:

  • lohkomääritteet
  • uudelleenkäytettävät custom/{name}-kenttäryhmät
  • ryhmät, välilehdet ja toistimet
  • PHP-, Twig- ja Blade-mallit
  • sisältömetatiedot ja asetusten tallennus
  • laajennusmallit, kuten {attributes.margin.top}

Esimerkiksi välistysohjaimella voidaan tallentaa yksi objekti neljän erillisen tekstikentän sijaan:

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

Nimeäminen

Mukautettujen kenttätyyppien nimien on oltava pieniä kirjaimia, nimiavaruudellisia ja yhdysmerkein erotettuja:

Text
namespace/type-name

Kelvollisia esimerkkejä:

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

Varatut nimiavaruudet:

  • custom/ on varattu uudelleenkäytettäville mukautetuille kenttäryhmille.
  • blockstudio/ on varattu Blockstudio-ytimelle.

Virheelliset nimet ohitetaan suodattimessa API ja hylätään apufunktiossa API.

PHP-rekisteröinti

Rekisteröi kenttätyypin metatiedot kohteessa 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() palauttaa arvon true, kun rekisteröinti onnistuu, ja arvon false, kun nimi tai määritys on virheellinen. Voit poistaa manuaalisen rekisteröinnin käyttämällä funktiota bs_unregister_field_type().

Voit myös käyttää suodatinta API:

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

    return $types;
});

Määrityksen avaimet

Avain Tyyppi Kuvaus
attribute string, array, null WordPress-attribuutin tyyppi. Käytä string-, number-, boolean-, object– tai array-tyyppiä tai näiden tyyppien taulukkoa.
default mixed Rekisterin tason oletusarvo, kun kentälle ei ole määritetty omaa oletusarvoa.
source string WordPress-attribuutin lähde mukautettuja sarjallistamistapauksia varten.
produces_attribute boolean Aseta arvoksi false vain näyttäviä ohjaimia varten. Oletusarvo on true.
editor_script string or array Rekisteröity komentosarjan tunniste tai tunnisteet, jotka lisätään lohkoeditoriin, kun tyyppiä käytetään.
editor_style string or array Rekisteröity tyylin tunniste tai tunnisteet, jotka lisätään lohkoeditoriin, kun tyyppiä käytetään.
storage array Tallennusarvon tyyppi sekä REST skeemavihjeet artikkelien metatiedoille ja asetuksille.
supports array Valinnaiset toimintoliput omaa ohjainta varten.
translate boolean Aseta arvoksi true, kun arvo on tekstiä, jonka WPML voi kääntää. Edellyttää attribute string.

Määritys, jonka translate-arvo ei ole totuusarvo tai jossa translate on asetettu arvoon true ja attribute on jokin muu kuin string, on virheellinen. bs_register_field_type() palauttaa arvon false, ja suodatin API ohittaa sen.

WPML

wp bs wpml config ei voi päätellä pelkän rekisteröinnin perusteella, onko mukautetun kenttätyypin arvo tekstiä, joten se jättää tällaiset kentät pois ja tulostaa kustakin varoituksen. Aseta translate arvoon true sellaisen kenttätyypin rekisteröinnissä, joka tallentaa pelkän tekstimerkkijonon, niin komento ilmoittaa sen kentät kuten text-kentät. Kentän voi silti jättää pois asetuksella "translate": false. Katso WPMLsiirrettävien mediatiedostojen viitteet.

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

JavaScript-rekisteröinti

Editorin skripti rekisteröi vastaavan React-ohjaimen:

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() palauttaa arvon true, kun rekisteröinti hyväksytään. Poista asiakaspuolen rekisteröinti näin:

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

Komponentti saa kentän määrityksen ominaisuudet sekä nämä pysyvät ominaisuudet:

Ominaisuus Kuvaus
type Kenttätyypin nimi.
id Kentän tunnus.
field Koko kentän määritys lähteestä block.json.
value Nykyinen tallennettu arvo.
defaultValue Kentän oletusarvo.
onChange Tallenna uusi arvo suoraan.
attributes Nykyiset lohkomääritteet.
block Nykyisen lohkotyypin määritys.
clientId Nykyisen editorilohkon asiakastunnus.
inRepeater Onko kenttä toistinrivillä.
repeaterId Nykyinen toistimen polku, jos sellainen on.
disabled Onko kenttä poistettu käytöstä editorissa.

Mukautettujen kenttätyyppien arvoja ei tallenneta suoraan. Niitä ei käsitellä natiivien select-, radio-, color– tai gradient-asetusten normalisoinnissa.

Arvojen renderöinti

Objektin arvot ovat käytettävissä kuten muutkin Blockstudio-määritteet.

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>

Sisäkkäiset objektipolut toimivat myös laajennusmalleissa:

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

Tallennus

Kun mukautettua kenttätyyppiä käytetään tallennuksessa postMeta tai option, Blockstudio käyttää rekisteröityä tallennettavan arvon tyyppiä ja skeemaa REST.

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

Määritä rekisteröinnissä kenttätyypille storage.rest_schema, kun kyseessä ovat arvot array ja object. Toistimen alikohteet käyttävät edelleen taulukkopohjaista tallennusta, koska toistin tallentaa rivejä.

Varatoiminta

Jos PHP tuntee kenttätyypin, mutta editorin skripti ei rekisteröi vastaavaa ohjainta, Blockstudio säilyttää tallennetun arvon ja näyttää editorissa huomautuksen, jota ei voi muokata. Käyttöliittymän renderöinti saa edelleen tallennetun arvon.

Jos kenttätyyppiä ei rekisteröidä kohteessa PHP, Blockstudio jättää sen pois luoduista WordPress-määritteistä. Rekisteröi määritys PHP ennen lohkojen tunnistusta, yleensä kohteessa init ennen kuin Blockstudio luo lohkot.