Ga naar de inhoud

Opties vullen

In plaats van verschillende veldtypen zoals Posts, Users of Terms aan te bieden, maakt Blockstudio het mogelijk om gegevens modulair rechtstreeks vanuit de block.json te vullen. Deze functie werkt voor de veldtypen select, radio, checkbox, color en gradient.

Gegevens kunnen op vier manieren worden gevuld:

  • Query – Resultaten uit een post-, gebruikers- of termquery ophalen
  • Fetch – Resultaten uit een externe bron ophalen
  • Function – Resultaten uit een aangepaste functie ophalen
  • Custom – Resultaten uit een aangepaste dataset ophalen

Query

In de querymodus kunnen Posts, Users of Terms worden gevuld.

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

De beschikbare querytypen gebruiken intern deze WordPress-functies:

Query Functie
posts get_posts
users get_users
terms get_terms

Argumenten

Aangepaste argumenten kunnen worden meegegeven met het attribuut arguments:

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

Retourformaat

Standaard retourneert Blockstudio:

Query Waarde Label
posts postobject post_title
users gebruikersobject display_name
terms termobject name

Pas het antwoord aan met 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"
          }
        }
      }
    ]
  }
}

Fetch-modus

Schakel dynamisch zoeken in met de optie fetch:

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

Hiermee wordt stylisedUi ingeschakeld en worden in eerste instantie de eerste 20 posts opgehaald. Als u in het selectieveld typt, zoekt u naar posts met het argument s.

Functie

Gebruik een aangepaste functie om opties te vullen:

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

Argumenten

Geef argumenten mee als een array (gebruikt intern call_user_func_array):

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

Retourformaat

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

Opties combineren

Combineer statische opties met gevulde gegevens:

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

De optie position (before of after) bepaalt waar gevulde opties worden weergegeven ten opzichte van statische opties.

Waarschuwing

Het combineren van opties en gevulde gegevens wordt niet ondersteund in de modus fetch.

Aangepaste gegevens

Maak herbruikbare datasets met het filter blockstudio/blocks/attributes/populate. Het filter ontvangt één argument: een array met alle aangepaste datasets, geïndexeerd op naam. Voeg uw dataset toe onder een sleutel en retourneer de array:

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

Verwijs vervolgens in uw blok naar de sleutel:

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

Externe gegevens

Gegevens ophalen uit een externe bron:

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

De zoekterm wordt toegevoegd aan urlSearch.

Dynamische argumenten

Vulargumenten kunnen met de syntaxis {attributes.*} verwijzen naar andere blokattributen. Wanneer het kenmerk waarnaar wordt verwezen verandert, haalt het veld automatisch de opties opnieuw op.

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

Dit werkt met alle vultypen (query, function, custom). Elke waarde in de vulconfiguratie die {attributes.*} bevat, wordt aan clientzijde opgelost met de huidige attribuutwaarde voordat de query wordt uitgevoerd.

Verwijzingen gebruiken de in de editor opgeslagen waarden. Gebruik voor een selectieoptie {attributes.post_type.value} voor de waarde of {attributes.post_type.label} voor het label; returnFormat bepaalt de templatewaarde, niet deze opgeslagen editorvorm.

Geneste argumenten worden opgelost zonder ze naar een templatestring te serialiseren. Een argument dat uit één placeholder bestaat, behoudt het type waarnaar het verwijst, inclusief getallen, booleans, arrays en objecten. Een placeholder die in andere tekst is opgenomen, levert een tekenreeks op. Ontbrekende verwijzingen blijven ongewijzigd en waarden met aanhalingstekens of meerdere regels worden intact doorgegeven. Functiecallbacks behouden hun positionele argumentlijsten. De editor voegt zoekargumenten WordPress alleen toe aan query-populates, niet aan functieaanroepen.

Afhankelijke selecties weergeven

Afhankelijke opties worden niet geladen wanneer het block wordt geregistreerd, omdat elke blockinstantie andere argumenten kan hebben. Bij het weergeven wordt de opgeslagen selectie gebruikt in plaats van deze te wissen vanwege een lege optielijst. De populate-callback wordt niet opnieuw uitgevoerd aan de voorkant.

De returnFormat van het veld is nog steeds van toepassing:

returnFormat Enkelvoudige selectie Meervoudige selectie
value (standaard) De opgeslagen waarde, bijvoorbeeld "a" Een array met opgeslagen waarden, bijvoorbeeld ["a", "b"]
label Het opgeslagen label Een array met opgeslagen labels
both De opgeslagen optie {value, label} Een array met opgeslagen opties

Bij query-gevulde selecties worden waarden nog steeds omgezet naar het bijbehorende WordPress-bericht, gebruikers- of termobject, tenzij populate.returnFormat.value "id" is. Labels zijn afkomstig van de opgeslagen selectie. Heeft een geïmporteerde selectie geen label, dan wordt de waarde als label gebruikt. Een overeenkomende statische optie die is gedefinieerd in options heeft voorrang op de opgeslagen optie, zodat het huidige label wordt gebruikt.

Lege selecties blijven false (of de geconfigureerde fallback van het veld). Dit verandert niets aan de validatie van gewone statische opties: een opgeslagen waarde die niet meer in een statische optielijst staat, retourneert nog steeds false.

Dynamische selecties behouden ook default– en fallback-selecties zolang hun opties zijn uitgesteld. Gebruik een scalaire waarde, een optie van {value, label} of een array met een van beide voor een meervoudige selectie. Een scalaire waarde gebruikt zichzelf als label, tenzij deze overeenkomt met een gedefinieerde statische optie. Een optieobject behoudt het opgegeven label; een overeenkomende statische optie heeft voorrang. Er wordt op de server geen populate-callback uitgevoerd om deze standaardwaarden op te zoeken.