Hoppa till innehåll

Anpassade fält

Med anpassade fält kan du definiera återanvändbara fältgrupper som kan refereras från flera block. Se dem som fältmallar: definiera en gång, använd överallt.

Anpassade fält är inte samma sak som anpassade fälttyper. Använd custom/{name} för återanvändbara grupper med befintliga fält. Använd en anpassad fälttyp med ett namnområde, till exempel acme/dimensions, när ett tema eller tillägg registrerar en ny redigeringskontroll och värdestruktur.

Registrering av filsystem

Skapa en fil field.json i en katalog fields/ i din blockstudio-katalog:

Kod
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 med PHP

Registrera anpassade fält programmatiskt med filtret 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;
});

Användning i block.json

Referera till ett anpassat fält med typen custom/{name}:

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

Detta infogas direkt och visar fälten som definierats i den anpassade fältdefinitionen. De infogade fälten använder sina ursprungliga ID:n (heading, description, enabled).

Anpassade fält kan också återanvända fullständiga gruppdefinitioner:

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

Gruppens underordnade fält lagras som section-header_kicker, section-header_title och så vidare. Använd bs_get_group() i mallar för att extrahera dem till ett tydligt gruppobjekt.

ID-struktur

Använd idStructure för att lägga till ett prefix till eller omforma fält-ID:n. Platshållaren {id} ersätts med det ursprungliga fält-ID:t:

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

Detta skapar fält med ID:n: hero_heading, hero_description, hero_enabled.

Åsidosättningar

Anpassa enskilda fält per instans med overrides. Nycklarna är de ursprungliga fält-ID:na från definitionen:

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

Åsidosatta egenskaper slås samman med den ursprungliga fältdefinitionen. Ett åsidosättande av id kringgår mönstret idStructure. I exemplet ovan blir enabled active i stället för hero_enabled.

Sammanslagningen går bara en nivå djupt: en egenskap som du åsidosätter ersätter den ursprungliga egenskapen i sin helhet. En options-åsidosättning är den fullständiga listan med alternativ, inte ett tillägg till den, och detsamma gäller för conditions och för en grupps attributes. Villkor på referensen läggs fortfarande till efteråt.

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

Det här blocket erbjuder bara White och Grey, oavsett hur många alternativ definitionen listar.

Villkor

Villkor i anpassade fältdefinitioner skrivs automatiskt om när idStructure används. Ett fält med ett villkor som beror på ett syskonfält fortsätter att fungera efter expansionen.

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 expanderar detta till title_font_enable, title_font_min, title_font_max och skriver om villkoren så att de refererar till title_font_enable i stället för enable. Växlingsknapparna fungerar precis som om fälten hade definierats direkt.

Villkor på referensnivå

Lägg till conditions i referensen för att tillämpa dem på alla expanderade fält. Det är användbart när du vill dölja en hel grupp bakom en extern växlingsknapp:

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

Dessa villkor slås samman med eventuella villkor som redan definierats i fältdefinitionen. Villkors-ID:n skrivs också om via idStructure.

Flera anpassade fält

Du kan använda flera anpassade fält i ett enda block tillsammans med vanliga fält:

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

Kapsling

Anpassade fält fungerar i grupper, flikar och repeaters:

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

Ytterligare identifieringssökvägar

Använd filtret blockstudio/fields/paths för att lägga till ytterligare kataloger där fält kan identifieras:

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

Statisk analys

Paketet blockstudio/phpstan expanderar filbaserade referenser till custom/* vid validering av PHP, Twig, Blade, blocktaggar och härledda attributstrukturer. Expansionen följer samma regler för kapsling, idStructure och overrides som beskrivs ovan.

Om definitioner finns utanför det analyserade projektet lägger du till bibliotekskatalogen i blockstudioScanRoots i phpstan.neon. Fält som endast registrerats via filtret blockstudio/fields PHP finns vid körning och kan inte härledas statiskt.