Preskočiť na obsah

Napĺňanie možností

Namiesto poskytovania rôznych typov polí, ako sú Príspevky, Používatelia alebo Výrazy, Blockstudio umožňuje modulárne napĺňať údaje priamo z block.json. Táto funkcia podporuje typy polí select, radio, checkbox, color a gradient.

Údaje možno napĺňať štyrmi spôsobmi:

  • Dotaz – Vráti výsledky dotazu na príspevky, používateľov alebo výrazy
  • Načítanie – Vráti výsledky z externého zdroja
  • Funkcia – Vráti výsledky vlastnej funkcie
  • Vlastné údaje – Vráti výsledky z vlastnej množiny údajov

Dotaz

Pri výbere režimu dotazu možno naplniť Príspevky, Používateľov alebo Výrazy.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

Dostupné typy dotazov interne používajú tieto funkcie WordPress:

Dotaz Funkcia
posts get_posts
users get_users
terms get_terms

Argumenty

Vlastné argumenty možno odovzdať pomocou atribútu arguments:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Formát návratovej hodnoty

Predvolene funkcia Blockstudio vracia:

Dotaz Hodnota Označenie
posts objekt príspevku post_title
users objekt používateľa display_name
terms objekt výrazu name

Odpoveď upravte pomocou returnFormat:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

Režim načítania

Dynamické vyhľadávanie zapnete možnosťou fetch:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Tým sa zapne stylisedUi a na začiatku sa načíta prvých 20 príspevkov. Písaním do výberového poľa vyhľadáte príspevky pomocou argumentu s.

Funkcia

Na naplnenie možností použite vlastnú funkciu:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

Argumenty

Argumenty odovzdajte ako pole (interne používa call_user_func_array):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Formát návratovej hodnoty

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

Kombinovanie možností

Skombinujte statické možnosti s naplnenými údajmi:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

Možnosť position (before alebo after) určuje, kde sa naplnené možnosti zobrazia vzhľadom na statické možnosti.

Upozornenie

Kombinovanie možností a napĺňanie údajov nie je podporované v režime fetch.

Vlastné údaje

Pomocou filtra blockstudio/blocks/attributes/populate vytvorte opakovane použiteľné množiny údajov. Filter prijíma jeden argument: pole všetkých vlastných množín údajov, ktorých kľúčmi sú ich názvy. Pridajte svoju množinu údajov pod kľúč a vráťte pole:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

Potom na kľúč odkážte vo svojom bloku:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

Externé údaje

Načítajte údaje z externého zdroja:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

Hľadaný výraz sa pridá na koniec urlSearch.

Dynamické argumenty

Argumenty na naplnenie môžu odkazovať na ďalšie atribúty bloku pomocou syntaxe {attributes.*}. Keď sa zmení odkazovaný atribút, možnosti poľa sa automaticky načítajú znova.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

Funguje to so všetkými typmi napĺňania (query, function, custom). Každá hodnota v konfigurácii napĺňania obsahujúca {attributes.*} sa pred spustením dotazu vyrieši na strane klienta pomocou aktuálnej hodnoty atribútu.

Odkazy používajú hodnoty uložené v editore. Pri možnosti výberového zoznamu použite {attributes.post_type.value} pre jej hodnotu alebo {attributes.post_type.label} pre jej štítok; returnFormat riadi hodnotu šablóny, nie túto uloženú podobu z editora.

Vnorené argumenty sa vyriešia bez serializácie do reťazca šablóny. Argument pozostávajúci z jedného zástupného symbolu si zachová svoj typ vrátane čísel, logických hodnôt, polí a objektov. Zástupný symbol vložený do iného textu vytvorí reťazec. Chýbajúce odkazy zostanú nezmenené a citované hodnoty aj hodnoty s viacerými riadkami sa odovzdajú bez úprav. Spätné volania funkcií si zachovávajú zoznamy pozičných argumentov. Editor pridáva vyhľadávacie argumenty WordPress iba pri napĺňaní query, nie pri volaní funkcií.

Vykresľovanie závislých výberov

Závislé možnosti sa nenačítajú pri registrácii bloku, pretože každá inštancia bloku môže mať odlišné argumenty. Pri vykreslení sa použije uložený výber namiesto jeho zahodenia pre prázdny zoznam možností. Funkcia spätného volania na napĺňanie sa na rozhraní stránky už znova nespustí.

Stále platí returnFormat daného poľa:

returnFormat Jednoduchý výber Viacnásobný výber
value (predvolené) Uložená hodnota, napríklad "a" Pole uložených hodnôt, napríklad ["a", "b"]
label Uložený štítok Pole uložených štítkov
both Uložená možnosť {value, label} Pole uložených možností

Pri výberoch naplnených z dopytu sa hodnoty naďalej rozpoznávajú ako zodpovedajúci objekt príspevku, používateľa alebo taxonomického výrazu WordPress, pokiaľ populate.returnFormat.value nie je "id". Štítky pochádzajú z uloženého výberu. Ak importovaný výber nemá štítok, ako štítok sa použije jeho hodnota. Zodpovedajúca statická možnosť definovaná v options má prednosť pred uloženou možnosťou, preto sa použije jej aktuálny štítok.

Prázdne výbery zostávajú false (alebo majú nakonfigurovanú fallback poľa). Tým sa nemení validácia bežných statických možností: uložená hodnota, ktorá už nie je v zozname statických možností, stále vracia false.

Dynamické výbery zachovávajú aj výbery default a fallback, kým sú ich možnosti odložené. Pri viacnásobnom výbere použite skalárnu hodnotu, možnosť {value, label} alebo pole obsahujúce jednu z nich. Pri skalárnej hodnote sa ako štítok použije jej hodnota, pokiaľ sa nezhoduje s deklarovanou statickou možnosťou. Objekt možnosti zachová zadaný štítok; zodpovedajúca statická možnosť má prednosť. Na serveri sa nespúšťa žiadna funkcia populate na vyhľadanie týchto predvolených hodnôt.