Přejít k obsahu

Naplnění možností

Místo poskytování různých typů polí, jako jsou příspěvky, uživatelé nebo termíny, umožňuje Blockstudio modulární naplňování dat přímo z block.json. Tato funkce funguje pro typy polí select, radio, checkbox, color a gradient.

Data lze naplnit čtyřmi způsoby:

  • Dotaz – Vrátí výsledky dotazu na příspěvky, uživatele nebo termíny
  • Načtení – Vrátí výsledky z externího zdroje
  • Funkce – Vrátí výsledky vlastní funkce
  • Vlastní data – Vrátí výsledky vlastní datové sady

Dotaz

Při výběru režimu dotazu lze naplnit příspěvky, uživatele nebo termíny.

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 dotazů interně používají tyto funkce WordPress:

Dotaz Funkce
posts get_posts
users get_users
terms get_terms

Argumenty

Vlastní argumenty lze předat pomocí atributu arguments:

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

Formát návratové hodnoty

Ve výchozím nastavení Blockstudio vrací:

Dotaz Hodnota Popisek
posts objekt příspěvku post_title
users objekt uživatele display_name
terms objekt termínu name

Odpověď upravte pomocí 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čítání

Povolte dynamické vyhledávání pomocí možnosti 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 se povolí stylisedUi a zpočátku se načte prvních 20 příspěvků. Zadáním textu do výběrového pole vyhledáte příspěvky pomocí argumentu s.

Funkce

K naplnění možností použijte vlastní funkci:

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

Argumenty

Argumenty předávejte jako pole (interně používá 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ávratové 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"
          }
        }
      }
    ]
  }
}

Kombinování možností

Kombinujte statické možnosti s naplněnými daty:

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žnost position (before nebo after) určuje, kde se naplněné možnosti zobrazí vzhledem ke statickým možnostem.

Varování

Kombinování možností a naplněných dat není v režimu načítání podporováno.

Vlastní data

Vytvářejte opakovaně použitelné datové sady pomocí filtru blockstudio/blocks/attributes/populate. Filtr přijímá jeden argument: pole všech vlastních datových sad, jejichž klíčem je název. Přidejte svou datovou sadu pod příslušný klíč a vrať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;
});

Poté v bloku odkažte na klíč:

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

Externí data

Načtěte data z externího zdroje:

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"
          }
        }
      }
    ]
  }
}

Hledaný výraz se připojí k urlSearch.

Dynamické argumenty

Argumenty pro naplnění mohou pomocí syntaxe {attributes.*} odkazovat na jiné atributy bloku. Když se odkazovaný atribut změní, pole automaticky znovu načte své možnosti.

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 se všemi typy naplnění (query, function, custom). Každá hodnota v konfiguraci naplnění obsahující {attributes.*} se před spuštěním dotazu vyhodnotí na straně klienta s aktuální hodnotou atributu.

Odkazy používají hodnoty uložené v editoru. U možnosti výběru použijte {attributes.post_type.value} pro její hodnotu nebo {attributes.post_type.label} pro její popisek; returnFormat řídí hodnotu šablony, nikoli tuto podobu uloženou v editoru.

Vnořené argumenty se vyhodnocují bez serializace do řetězce šablony. Argument tvořený jediným zástupným symbolem zachovává typ odkazované hodnoty, včetně čísel, logických hodnot, polí a objektů. Zástupný symbol vložený do jiného textu vytvoří řetězec. Chybějící odkazy zůstávají beze změny a hodnoty v uvozovkách nebo na více řádcích se předávají beze změny. Zpětná volání funkcí zachovávají své poziční seznamy argumentů. Editor přidává argumenty vyhledávání WordPress pouze do query, nikoli do volání funkcí.

Vykreslování závislých výběrů

Závislé možnosti se nenačítají při registraci bloku, protože každá instance bloku může mít jiné argumenty. Při vykreslování se použije uložený výběr, místo aby byl zamítnut kvůli prázdnému seznamu možností. Zpětné volání pro naplnění se na frontendu nespouští znovu.

Nastavení returnFormat pole stále platí:

returnFormat Výběr jedné možnosti Výběr více možností
value (výchozí) Uložená hodnota, například "a" Pole uložených hodnot, například ["a", "b"]
label Uložený štítek Pole uložených štítků
both Uložená možnost {value, label} Pole uložených možností

U výběrů naplněných z dotazu se hodnoty stále převádějí na odpovídající objekty příspěvků, uživatelů nebo výrazů WordPress, pokud populate.returnFormat.value není "id". Štítky pocházejí z uloženého výběru. Pokud importovaný výběr nemá štítek, jako štítek se použije jeho hodnota. Odpovídající statická možnost deklarovaná v options má přednost před uloženou možností, takže se použije její aktuální štítek.

Prázdné výběry zůstávají false (nebo odpovídají nastavení fallback pole). Tím se nemění ověřování běžných statických možností: uložená hodnota, která už není v seznamu statických možností, stále vrací false.

Dynamické výběry také zachovávají výběry default a fallback, zatímco se jejich možnosti načítají později. U výběru jedné možnosti použijte skalární hodnotu nebo možnost {value, label}; u výběru více možností lze použít pole kterékoli z těchto hodnot. Skalární hodnota použije svou hodnotu jako štítek, pokud neodpovídá deklarované statické možnosti. Objekt možnosti zachová dodaný štítek; odpovídající statická možnost má přednost. Na serveru se kvůli vyhledání těchto výchozích hodnot nespouští žádné zpětné volání pro naplnění možností.