Gå til indhold

Brugerdefinerede felter

Brugerdefinerede felter lader dig definere genanvendelige feltgrupper, der kan bruges på tværs af flere blokke. Tænk på dem som feltskabeloner: Definer én gang, og brug dem overalt.

Brugerdefinerede felter er ikke det samme som brugerdefinerede felttyper. Brug custom/{name} til genanvendelige grupper af eksisterende felter. Brug en brugerdefineret felttype med navnerum som acme/dimensions, når et tema eller plugin registrerer en ny redigeringskontrol og værdistruktur.

Registrering af filsystem

Opret en field.json-fil i en fields/-mappe i din blockstudio-mappe:

Kode
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

Filterregistrering af PHP

Registrer brugerdefinerede felter programmatisk med filteret blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

Brug i block.json

Henvis til et brugerdefineret felt ved at bruge typen custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Dette indsætter felterne fra definitionen af det brugerdefinerede felt direkte. De indsatte felter beholder deres oprindelige ID’er (heading, description, enabled).

Brugerdefinerede felter kan også genbruge komplette gruppedefinitioner:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Underfelterne i gruppen gemmes som section-header_kicker, section-header_title osv. Brug bs_get_group() i skabeloner for at udtrække dem til et overskueligt gruppeobjekt.

ID-struktur

Brug idStructure til at sætte præfiks på eller omdanne felt-ID’er. Pladsholderen {id} erstattes med det oprindelige felt-ID:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Dette giver felter med ID’erne: hero_heading, hero_description, hero_enabled.

Tilsidesættelser

Tilpas individuelle felter for hver forekomst med overrides. Nøglerne er de oprindelige felt-ID’er fra definitionen:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Tilsidesættelsesegenskaber flettes oven i den oprindelige feltdefinition. En tilsidesættelse af id omgår mønsteret idStructure. I eksemplet ovenfor bliver enabled til active i stedet for hero_enabled.

Sammenfletningen går kun ét niveau ned: En egenskab, du tilsidesætter, erstatter den oprindelige egenskab som helhed. En options-tilsidesættelse er den komplette liste over valgmuligheder, ikke en tilføjelse til den, og det samme gælder for conditions og for en gruppes attributes. Betingelser på referencen tilføjes stadig bagefter.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Denne blok tilbyder kun White og Grey, uanset hvor mange valgmuligheder definitionen angiver.

Betingelser

Betingelser i brugerdefinerede feltdefinitioner omskrives automatisk, når idStructure anvendes. Et felt, der betinget afhænger af et søsterfelt, fortsætter med at fungere efter udvidelsen.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio udvider dette til title_font_enable, title_font_min, title_font_max og omskriver betingelserne, så de henviser til title_font_enable i stedet for enable. Til/fra-knapperne fungerer præcis, som hvis felterne var defineret direkte.

Betingelser på referenceniveau

Tilføj conditions til referencen for at anvende dem på alle udvidede felter. Det er nyttigt, hvis en hel gruppe skal skjules bag en ekstern til/fra-knap:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Disse betingelser flettes sammen med eventuelle betingelser, der allerede er defineret i feltdefinitionen. Betingelses-ID’er omskrives også via idStructure.

Flere brugerdefinerede felter

Du kan bruge flere brugerdefinerede felter i én blok sammen med almindelige felter:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Indlejring

Brugerdefinerede felter fungerer i grupper, faner og repeatere:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Yderligere registreringsstier

Brug filteret blockstudio/fields/paths til at føje flere mapper til registreringen af felter:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Statisk analyse

Pakken blockstudio/phpstan udvider filbaserede referencer til custom/*, når den validerer PHP, Twig, Blade, bloktags og udledte attributstrukturer. Udvidelsen følger de samme regler for indlejring, idStructure og overrides, som er beskrevet ovenfor.

For definitioner uden for det analyserede projekt skal du føje biblioteksmappen til blockstudioScanRoots i phpstan.neon. Felter, der kun registreres via filteret blockstudio/fields PHP, findes ved kørsel og kan ikke udledes statisk.