Gå til indhold

Udfyldning af indstillinger

I stedet for at angive forskellige felttyper som indlæg, brugere eller termer giver Blockstudio mulighed for modulært at udfylde data direkte fra block.json. Funktionen virker med felttyperne select, radio, checkbox, color og gradient.

Data kan udfyldes på fire måder:

  • Forespørgsel – Returnerer resultater fra en forespørgsel efter indlæg, brugere eller termer
  • Hent – Returnerer resultater fra en ekstern kilde
  • Funktion – Returnerer resultater fra en brugerdefineret funktion
  • Brugerdefineret – Returnerer resultater fra et brugerdefineret datasæt

Forespørgsel

I forespørgselstilstand kan Indlæg, Brugere eller Termer udfyldes.

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 tilgængelige forespørgselstyper bruger disse WordPress-funktioner internt:

Forespørgsel Funktion
posts get_posts
users get_users
terms get_terms

Argumenter

Brugerdefinerede argumenter kan angives med attributten arguments:

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

Returformat

Som standard returnerer Blockstudio:

Forespørgsel Værdi Etiket
posts indlægsobjekt post_title
users brugerobjekt display_name
terms termobjekt name

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

Hentetilstand

Aktivér dynamisk søgning med indstillingen fetch:

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

Dette aktiverer stylisedUi og henter de første 20 indlæg til at begynde med. Når der skrives i valgfeltet, søges der efter indlæg med argumentet s.

Funktion

Brug en brugerdefineret funktion til at udfylde indstillinger:

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

Argumenter

Angiv argumenter som et array (bruger 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"
          }
        }
      }
    ]
  }
}

Kombination af indstillinger

Kombinér statiske indstillinger med udfyldte 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"
        }
      }
    ]
  }
}

Indstillingen position (before eller after) styrer, hvor de udfyldte indstillinger vises i forhold til de statiske indstillinger.

Advarsel

Det understøttes ikke at kombinere indstillinger og udfyldningsdata i tilstanden fetch.

Brugerdefinerede data

Opret genanvendelige datasæt med filteret blockstudio/blocks/attributes/populate. Filteret modtager ét argument: et array med alle brugerdefinerede datasæt, indekseret efter navn. Tilføj dit datasæt under en nøgle, og returnér arrayet:

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

Henvis derefter til nøglen i din blok:

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

Eksterne data

Hent data fra en ekstern kilde:

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øgeordet føjes til urlSearch.

Dynamiske argumenter

Udfyldningsargumenter kan referere til andre blokattributter med syntaksen {attributes.*}. Når den refererede attribut ændres, henter feltet automatisk sine indstillinger igen.

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

Dette virker med alle udfyldningstyper (query, function, custom). Enhver værdi i udfyldningskonfigurationen, der indeholder {attributes.*}, opløses på klientsiden med den aktuelle attributværdi, før forespørgslen køres.

Referencer bruger editorens gemte værdier. For en valgmulighed skal du bruge {attributes.post_type.value} til dens værdi eller {attributes.post_type.label} til dens etiket; returnFormat styrer skabelonværdien, ikke denne gemte editorform.

Indlejrede argumenter løses uden at blive serialiseret til en skabelonstreng. Et argument, der består af én pladsholder, beholder sin refererede type, herunder tal, booleske værdier, arrays og objekter. En pladsholder, der er indlejret i anden tekst, bliver til en streng. Manglende referencer forbliver uændrede, og citerede værdier eller værdier med flere linjer sendes intakte. Funktions-callbacks beholder deres positionsbestemte argumentlister. Editorens tilføjer kun WordPress-søgeargumenter til query-kald til populate, ikke til funktionskald.

Gengivelse af afhængige valg

Afhængige valgmuligheder indlæses ikke, når blokken registreres, fordi hver blokinstans kan have forskellige argumenter. Gengivelsen bruger det gemte valg i stedet for at forkaste det på grund af en tom liste over valgmuligheder. Populate-callbacken køres ikke igen på frontend.

Feltets returnFormat gælder stadig:

returnFormat Enkeltvalg Flervalg
value (standard) Den gemte værdi, for eksempel "a" Et array med gemte værdier, for eksempel ["a", "b"]
label Den gemte etiket Et array med gemte etiketter
both Den gemte mulighed {value, label} Et array med gemte muligheder

For valg, der udfyldes via forespørgsler, knyttes værdierne stadig til det tilsvarende WordPress-indlæg, bruger- eller termobjekt, medmindre populate.returnFormat.value er "id". Etiketterne kommer fra det gemte valg. Hvis et importeret valg ikke har nogen etiket, bruges værdien som etiket. En matchende statisk mulighed, der er defineret i options, har forrang for den gemte mulighed, så dens aktuelle etiket gælder.

Tomme valg forbliver false (eller bruger feltets konfigurerede fallback). Dette ændrer ikke valideringen af almindelige statiske muligheder: En gemt værdi, der ikke længere findes på listen over statiske muligheder, returnerer stadig false.

Dynamiske selectfelter bevarer også valgene default og fallback, mens deres muligheder indlæses senere. Brug en skalarværdi, en mulighed af typen {value, label} eller et array med en af delene til et flervalg. En skalar bruger sin værdi som etiket, medmindre den matcher en defineret statisk mulighed. Et mulighedsobjekt bevarer sin angivne etiket; en matchende statisk mulighed har forrang. Der køres ingen udfyldningscallback på serveren for at slå disse standardværdier op.