Liigu sisu juurde

Kohandatud väljatüübid

Kohandatud väljatüübid võimaldavad teemal või pluginatil lisada uusi Blockstudio-väljade juhtelemente. Need erinevad kohandatud väljadest:

  • custom/{name} viitab korduvkasutatavale rühmale, mis koosneb olemasolevatest väljadest.
  • namespace/type-name kasutab registreeritud väljatüüpi, millel on oma redaktori juhtelement ja väärtuse kuju.

Blockstudio sisaldab registreerimissüsteemi. Teema või plugin sisaldab juhtelementi.

Millal neid kasutada

Kasutage kohandatud väljatüüpi, kui projekt vajab kindla otstarbega redigeerimisjuhtelementi, mis peaks kõikjal toimima nagu Blockstudio algne väli:

  • ploki atribuudid
  • korduvkasutatavad custom/{name}-väljarühmad
  • rühmad, vahekaardid ja kordajad
  • PHP, Twig ja Blade mallid
  • postituse metaandmed ja suvandite salvestus
  • laiendusmallid, näiteks {attributes.margin.top}

Näiteks saab vahe juhtelement salvestada ühe objekti nelja eraldi tekstivälja asemel:

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 andmine

Kohandatud väljatüüpide nimed peavad olema väiketähtedega, nimeruumiga ja sidekriipsudega eraldatud:

Text
namespace/type-name

Kehtivad näited:

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

Reserveeritud nimeruumid:

  • custom/ on reserveeritud korduvkasutatavate kohandatud väljarühmade jaoks.
  • blockstudio/ on reserveeritud Blockstudio tuuma jaoks.

Filtri API abil eiratakse kehtetuid nimesid ja abifunktsioon API lükkab need tagasi.

PHP registreerimine

Registreerige väljatüübi metaandmed asukohas 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() tagastab registreerimise õnnestumisel väärtuse true ja juhul, kui nimi või definitsioon on vigane, väärtuse false. Käsitsi registreeringu saab eemaldada funktsiooniga bs_unregister_field_type().

Võite kasutada ka filtrit API:

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

    return $types;
});

Definitsiooni võtmed

Võti Tüüp Kirjeldus
attribute string, array, null WordPress atribuudi tüüp. Kasutage string, number, boolean, object, array või nende tüüpide massiivi.
default mixed Registritaseme vaikeväärtus, kui väli ei määra oma vaikeväärtust.
source string WordPress atribuudi allikas kohandatud serialiseerimisjuhtude jaoks.
produces_attribute boolean Ainult kuvamiseks mõeldud juhtelementide korral määrake väärtuseks false. Vaikimisi on true.
editor_script string or array Registreeritud skripti käepide või käepidemed, mis lisatakse plokiredaktori järjekorda tüübi kasutamisel.
editor_style string or array Registreeritud stiili käepide või käepidemed, mis lisatakse plokiredaktori järjekorda tüübi kasutamisel.
storage array Salvestusväärtuse tüüp ja REST skeemivihjed post meta ja valikute jaoks.
supports array Valikulised võimekuse lipud oma juhtelemendi jaoks.
translate boolean Määrake väärtuseks true, kui väärtus on tekst, mida WPML peaks tõlkima. Vajab attribute string.

Määratlus, mille translate väärtus ei ole tõeväärtus või mille puhul translate väärtuseks on määratud true ja attribute erineb väärtusest string, on vigane. bs_register_field_type() tagastab false ja filter API eirab seda.

WPML

wp bs wpml config ei saa registreeringu põhjal üksi kindlaks teha, kas kohandatud väljatüübi väärtus on tekst, seega jätab see sellised väljad välja ja kuvab igaühe kohta hoiatuse. Määrake translate väärtuseks true sellise väljatüübi registreeringus, mis salvestab lihtteksti stringi; seejärel käsitleb käsk selle välju nagu text välju. Välja saab endiselt välistada väärtusega "translate": false. Lisateavet leiate jaotisest WPMLkaasaskantavad meediaviited.

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

JavaScript registreerimine

Redaktori skript registreerib vastava React juhtelemendi:

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() tagastab registreerimise kinnitamisel väärtuse true. Kliendipoolse registreeringu eemaldamiseks kasutage:

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

Komponent saab väljadefinitsiooni atribuudid ning järgmised püsivad rekvisiidid:

Rekvisiit Kirjeldus
type Väljatüübi nimi.
id Välja ID.
field Täielik väljadefinitsioon asukohast block.json.
value Praegu salvestatud väärtus.
defaultValue Välja vaikeväärtus.
onChange Uue väärtuse otse salvestamine.
attributes Praeguse ploki atribuudid.
block Praeguse ploki tüübi definitsioon.
clientId Praeguse redaktori ploki kliendi ID.
inRepeater Kas väli asub kordaja reas.
repeaterId Praegune kordaja tee, kui see on olemas.
disabled Kas väli on redaktoris keelatud.

Kohandatud väljatüübi väärtused salvestatakse otse. Neid ei teisendata algse select, radio, color ega gradient suvandite normaliseerimise kaudu.

Väärtuste renderdamine

Objektväärtused on saadaval nagu kõik muud Blockstudio-atribuudid.

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>

Pesastatud objektide teed toimivad ka laiendusmallides:

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

Salvestus

Kui kohandatud väljatüüpi kasutatakse salvestusega postMeta või option, kasutab Blockstudio registreeritud salvestusväärtuse tüüpi ja REST skeemi.

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

Väärtuste array ja object puhul määrake registreerimisel väljatüübil storage.rest_schema. Kordaja järglased kasutavad edasi massiivi põhist salvestust, sest kordaja salvestab ridu.

Varukäitumine

Kui PHP tunneb väljatüüpi, kuid redaktori skript ei registreeri sellele vastavat juhtelementi, säilitab Blockstudio salvestatud väärtuse ja kuvab redaktoris mitteredigeeritava teate. Eesosa renderdus saab salvestatud väärtuse endiselt kätte.

Kui väljatüüpi pole asukohas PHP registreeritud, jätab Blockstudio selle genereeritud WordPress atribuutidest välja. Registreerige PHP definitsioon enne ploki tuvastamise käivitumist, tavaliselt kohas init enne, kui Blockstudio plokid koostab.