Liigu sisu juurde

Kohandatud väljad

Kohandatud väljade abil saate määratleda korduvkasutatavaid väljarühmi, millele saab viidata mitmes plokis. Mõelge neist kui väljamallidest: määratlege üks kord, kasutage kõikjal.

Kohandatud väljad ei ole sama mis kohandatud väljatüübid. Kasutage custom/{name} olemasolevate väljade korduvkasutatavate rühmade jaoks. Kasutage nimeruumiga kohandatud väljatüüpi, näiteks acme/dimensions, kui teema või plugin registreerib uue redaktori juhtelemendi ja väärtuse kuju.

Registreerimine failisüsteemis

Looge fail field.json kataloogi fields/ oma blockstudio kataloogis:

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

Registreerimine filtri PHP abil

Registreerige kohandatud väljad programmiliselt filtri blockstudio/fields abil:

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;
});

Kasutamine kohas block.json

Viidake kohandatud väljale tüübiga custom/{name}:

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

See laiendatakse tekstisiseselt kohandatud väljadefinitsioonis määratletud väljadeks. Laiendatud väljad kasutavad oma algseid ID-sid (heading, description, enabled).

Kohandatud väljadega saab taaskasutada ka terveid rühmadefinitsioone:

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

Rühma alamväljad salvestatakse väärtustena section-header_kicker, section-header_title ja nii edasi. Mallides kasutage bs_get_group(), et eraldada need puhtaks rühmaobjektiks.

ID struktuur

Kasutage välja ID-de eesliite lisamiseks või teisendamiseks idStructure. Kohatäide {id} asendatakse algse välja ID-ga:

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

Selle tulemusel tekivad väljad ID-dega: hero_heading, hero_description, hero_enabled.

Ülekirjutused

Kohandage üksikuid välju eksemplaripõhiselt atribuudi overrides abil. Võtmed on definitsioonis kasutatavad algsed välja ID-d:

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

Ülekirjutatud omadused liidetakse algse väljedefinitsiooniga. id-ülekirjutus jätab idStructure-mustri vahele. Ülaltoodud näites saab enabled väärtuseks active, mitte hero_enabled.

Ühendamine toimub ühe taseme sügavuseni: ülekirjutatav atribuut asendab algse atribuudi tervikuna. options ülekirjutus sisaldab kogu valikuloendit, mitte ei lisa sellele midagi, ja sama kehtib ka conditions ning rühma attributes puhul. Viitele kehtivad tingimused lisatakse seejärel endiselt.

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

See plokk pakub ainult valikuid Valge ja Hall, olenemata sellest, kui palju valikuid määratluses loetletakse.

Tingimused

Kohandatud väljedefinitsioonides olevad tingimused kirjutatakse automaatselt ümber, kui rakendatakse idStructure. Väli, mille tingimus sõltub kõrvalväljast, töötab ka pärast laiendamist edasi.

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 laiendab selle kujule title_font_enable, title_font_min, title_font_max ja kirjutab tingimused ümber, et need viitaksid title_font_enable-le, mitte enable-le. Lüliti juhtelemendid toimivad täpselt nii, nagu väljad oleksid tekstisiseselt määratletud.

Viitetaseme tingimused

Lisage viitele conditions, et rakendada tingimusi igale laiendatud väljale. See on kasulik terve rühma peitmiseks välise lüliti taha:

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

Need tingimused liidetakse väljedefinitsioonis juba määratud tingimustega. Tingimuste ID-d kirjutatakse samuti ümber atribuudiga idStructure.

Mitu kohandatud välja

Ühes plokis saab kasutada mitut kohandatud välja koos tavaliste väljadega:

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

Pesastamine

Kohandatud väljad toimivad rühmade, vahekaartide ja kordajate sees:

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

Täiendavad tuvastusteed

Kasutage filtrit blockstudio/fields/paths, et lisada väljade tuvastamiseks täiendavaid katalooge:

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

Staatiline analüüs

Pakett blockstudio/phpstan laiendab failipõhised custom/* viited, kui valideeritakse PHP, Twig, Blade, plokimärgendeid ja tuletatud atribuutide kujusid. Laiendamisel järgitakse samu pesastamise, idStructure ja overrides reegleid, mida eespool kirjeldati.

Väljaspool analüüsitavat projekti olevate definitsioonide puhul lisage teegi kataloog asukohta blockstudioScanRoots failis phpstan.neon. Ainult filtri blockstudio/fields PHP kaudu registreeritud väljad on saadaval käitusajal ja neid ei saa staatiliselt tuletada.