Hoppa till innehåll

Fylla alternativ

I stället för att tillhandahålla olika fälttyper som inlägg, användare eller termer gör Blockstudio det möjligt att fylla data på ett modulärt sätt direkt från block.json. Funktionen fungerar med fälttyperna select, radio, checkbox, color och gradient.

Data kan hämtas på fyra sätt:

  • Fråga – Returnerar resultat från en fråga om inlägg, användare eller termer
  • Hämtning – Returnerar resultat från en extern källa
  • Funktion – Returnerar resultat från en anpassad funktion
  • Anpassad – Returnerar resultat från en anpassad datauppsättning

Fråga

I frågeläge kan Inlägg, Användare eller Termer fyllas i.

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

Tillgängliga frågetyper använder dessa WordPress-funktioner internt:

Fråga Funktion
posts get_posts
users get_users
terms get_terms

Argument

Anpassade argument kan skickas med attributet arguments:

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

Returformat

Som standard returnerar Blockstudio:

Fråga Värde Etikett
posts inläggsobjekt post_title
users användarobjekt display_name
terms termobjekt name

Anpassa svaret med 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"
          }
        }
      }
    ]
  }
}

Hämtläge

Aktivera dynamisk sökning med alternativet fetch:

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

Detta aktiverar stylisedUi och hämtar de första 20 inläggen från början. När du skriver i urvalsfältet söks inlägg med argumentet s.

Funktion

Använd en anpassad funktion för att fylla alternativ:

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

Argument

Skicka argument som en array (använder call_user_func_array internt):

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

Returformat

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

Blanda alternativ

Kombinera statiska alternativ med hämtade data:

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

Alternativet position (before eller after) styr var hämtade alternativ visas i förhållande till statiska alternativ.

Varning

Det går inte att blanda alternativ och fylla data i fetch-läget.

Anpassade data

Skapa återanvändbara datauppsättningar med filtret blockstudio/blocks/attributes/populate. Filtret tar emot ett enda argument, en array med alla anpassade datauppsättningar sorterade efter namn. Lägg till din datauppsättning under en nyckel och returnera arrayen:

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

Referera sedan till nyckeln i ditt block:

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

Externa data

Hämta data från en extern källa:

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

Söktermen läggs till i urlSearch.

Dynamiska argument

Fyllningsargument kan referera till andra blockattribut med syntaxen {attributes.*}. När det refererade attributet ändras hämtar fältet automatiskt sina alternativ på nytt.

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

Detta fungerar med alla typer av ifyllning (query, function, custom). Alla värden i ifyllningskonfigurationen som innehåller {attributes.*} löses upp på klientsidan med det aktuella attributvärdet innan frågan körs.

Referenser använder redigerarens sparade värden. För ett val i en urvalslista använder du {attributes.post_type.value} för dess värde eller {attributes.post_type.label} för dess etikett; returnFormat styr mallvärdet, inte den här sparade redigerarformen.

Nästlade argument löses utan att serialiseras till en mallsträng. Ett argument som består av en enda platshållare behåller sin refererade typ, inklusive tal, booleska värden, arrayer och objekt. En platshållare som bäddas in i annan text ger en sträng. Saknade referenser lämnas oförändrade, och citerade värden eller värden med flera rader skickas intakta. Callbackfunktioner behåller sina positionsbaserade argumentlistor. Redigeraren lägger endast till sökargumentet WordPress i query-populeringar, inte i funktionsanrop.

Återgivning av beroende val

Beroende alternativ laddas inte när blocket registreras, eftersom varje blockinstans kan ha olika argument. Vid återgivning används det sparade valet i stället för att ta bort det mot en tom alternativlista. Populeringscallbacken körs inte igen i frontend.

Fältets returnFormat gäller fortfarande:

returnFormat Enval Flerval
value (standard) Det sparade värdet, till exempel "a" En matris med sparade värden, till exempel ["a", "b"]
label Den sparade etiketten En matris med sparade etiketter
both Det sparade alternativet {value, label} En matris med sparade alternativ

För val som fylls med en fråga kopplas värden fortfarande till motsvarande WordPress-inlägg, användar- eller termobjekt, såvida inte populate.returnFormat.value är "id". Etiketterna hämtas från det sparade valet. Om ett importerat val saknar etikett används dess värde som etikett. Ett matchande statiskt alternativ som deklarerats i options har företräde framför det sparade alternativet, så dess aktuella etikett används.

Tomma val förblir false (eller fältets konfigurerade fallback). Detta ändrar inte valideringen av vanliga statiska alternativ: ett sparat värde som inte längre finns i en statisk alternativlista returnerar fortfarande false.

Dynamiska urval bevarar också default– och fallback-val medan alternativen hämtas senare. Använd ett skalärt värde, ett alternativ av typen {value, label} eller en matris med något av dessa för ett flerval. Ett skalärt värde använder sitt värde som etikett om det inte matchar ett deklarerat statiskt alternativ. Ett alternativobjekt bevarar den angivna etiketten; ett matchande statiskt alternativ har företräde. Ingen populate-callback körs på servern för att slå upp dessa standardvärden.