Preskočiť na obsah

Rozšírenia

Rozšírenia umožňujú rozšíriť ľubovoľný registrovaný blok vo vašej inštalácii WordPress pomocou jednoduchého .json založeného na API, ktorý sa podobá konfigurácii block.json. Patria sem základné bloky, bloky tretích strán aj bloky vytvorené pomocou Blockstudio.

Do ľubovoľného bloku možno pridať všetky typy polí a údaje sa ukladajú do atribútov bloku. Rozšírenia môžu využívať kompletnú sadu funkcií atribútov, ako sú filtrovanie, zakázanie, podmienená logika a napĺňanie možností.

Typy rozšírení

Rozšírené hodnoty možno využiť rôznymi spôsobmi:

  • class: Pridajte bloku triedu pomocou hodnoty atribútu
  • style: Pridajte bloku vložené štýly pomocou hodnoty atribútu
  • attributes: Nastavte ľubovoľnú hodnotu atribútu priamo v bloku
  • data attributes: Pomocou hodnôt rozšírenia nastavte konkrétne dátové atribúty

Nastavenie

Predstavte si nasledujúci scenár: chcete pridať pole select vlastnej triedy do každého základného bloku. Stačí pridať tento súbor .json kamkoľvek do priečinka s blokmi a automaticky sa zaregistruje ako rozšírenie.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Tým sa pridá pole customColor do každého základného bloku, ktoré vám umožní nastaviť farbu textu bloku.

Názov súboru

Keďže neexistuje šablóna vykresľovania, rozšírenie nepotrebuje zodpovedajúci súbor index, a preto sa nemusí nazývať block.json. Všetky rozšírenia tak možno pohodlne ukladať do jedného priečinka. Ten istý blok môžu rozširovať viaceré súbory, napríklad dva súbory s "name": "core/*"; každý zaregistruje vlastné polia.

Schéma

Blockstudio poskytuje vlastnú schému JSON pre konfigurácie rozšírení:

Schéma rozšírenia View

Názov

Vlastnosť name konfiguračného objektu určuje, ktoré bloky sa majú rozšíriť. Podľa vašich potrieb si môžete vybrať z troch možností:

  • blockName: Názov jedného bloku, e.g. core/paragraph
  • [blockNameA, blockNameB]: Pole názvov blokov, e.g. ["core/paragraph", "core/heading"]
  • core/*: Zástupný znak na rozšírenie všetkých blokov určitého typu

Každý názov končiaci hviezdičkou je zástupný znak pre prefix, nielen core/*. Nasledujúce rozšírenie sa vzťahuje na každý blok, ktorého názov sa začína na my-plugin/, vrátane blokov vytvorených pomocou Blockstudio:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Vylúčenie blokov

Pomocou poľa exclude na najvyššej úrovni preskočíte bloky, ktoré by inak zodpovedali name:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Vylúčenia používajú rovnaké párovanie presných názvov a prefixov zakončených na * ako name. Majú prednosť pred jednotlivými názvami, zoznamami názvov a zástupnými znakmi. Vylúčený blok nedostane polia editora ani atribúty či zdroje rozšírenia na frontende. Ostatné zodpovedajúce rozšírenia zostanú bez zmeny. Ak chcete zachovať existujúce správanie, vynechajte exclude alebo použite prázdne pole.

Kľúč Blockstudio

Podobne ako pri použití block.json pre vlastné bloky musí byť v konfiguračnom objekte prítomná vlastnosť blockstudio a jej hodnota extend musí byť nastavená na true.

Pozícia

Rozšírenia sa predvolene vykresľujú na vlastnej karte v inšpektore bloku. Ak ich chcete presunúť na inú pozíciu, môžete použiť vlastnosť group:

  • settings: Predvolená pozícia
  • styles: Karta štýlov
  • advanced: Karta rozšírených nastavení
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Priorita

Vlastnosť priority umožňuje určiť poradie vykresľovania rozšírení. Rozšírenia s vyššou prioritou sa vykreslia neskôr. Nastavte ju na najvyššej úrovni súboru, ako v príklade nastavenia, alebo v rámci extend:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

Ak sú nastavené obe, prednosť má blockstudio.extend.priority.

Atribúty

Ďalšie informácie o fungovaní atribútov nájdete v časti o atribútoch.

Jediné, čo potrebujete vedieť o atribútoch v rozšíreniach, je vlastnosť set. Používa sa na priradenie hodnoty atribútu k jednému z typov rozšírení.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Získavanie hodnôt

Na získanie hodnoty atribútu sa používa zápis s bodkou v zložených zátvorkách.

Vnorené hodnoty možno získať aj vtedy, keď atribúty nevracajú jednu hodnotu, napríklad pri nastavení formátu návratovej hodnoty na both pre typy polí s možnosťami.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

Vyššie uvedený príklad nastaví atribút style na hodnotu color: #f00 alebo color: #00f a atribút data-color na hodnotu Red alebo Blue v závislosti od hodnoty.

Zatiaľ možno v definíciách set používať iba hodnoty z aktuálneho atribútu. Možnosť používať hodnoty z iných atribútov môže pribudnúť v budúcnosti.

Polia

Pri použití polí sa vlastnosť set použije na každú položku poľa.

Každá položka pridáva vlastnú triedu alebo deklaráciu štýlu. Každý iný atribút obsahuje jednu hodnotu, takže každá položka ju prepíše a platí posledná položka. Nastavením join na true sa namiesto toho zapíšu výsledky všetkých položiek oddelené medzerami, bez prázdnych alebo opakujúcich sa hodnôt, takže selektor ako [data-langs~="en"] zodpovedá každej vybratej položke. join nemá vplyv na class ani style, ani na polia, ktoré vracajú jednu hodnotu.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

Pri výbere oboch možností sa vykreslí data-langs="en de". Bez možnosti join sa vykreslí data-langs="de".

Pole atribútov

Pri použití poľa attributes nie je potrebná vlastnosť set, pretože pole automaticky priradí hodnoty k názvu a hodnote atribútu.

Kontrola polí rozšírenia

bs_block_extension_fields('core/paragraph') vracia definície polí každého rozšírenia, ktoré zodpovedá bloku. Informácie o návratovej hodnote a jej vzťahu k bs_block_fields() nájdete v časti Kontrola blokov.