Ugrás a tartalomhoz

Egyéni mezők

Az egyéni mezőkkel újrafelhasználható mezőcsoportokat határozhat meg, amelyekre több blokkban is hivatkozhat. Tekintse őket mezősablonoknak: egyszer definiálja, használja bárhol.

Az egyéni mezők nem azonosak az egyéni mezőtípusokkal. Használja a custom/{name} lehetőséget meglévő mezők újrafelhasználható csoportjaihoz. Használjon névtérrel ellátott egyéni mezőtípust, például a acme/dimensions elemet, ha egy téma vagy bővítmény új szerkesztővezérlőt és értékszerkezetet regisztrál.

Regisztráció a fájlrendszerben

Hozzon létre egy field.json fájlt egy fields/ könyvtárban a blockstudio könyvtárán belül:

Kód
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" }
  ]
}

Regisztráció a PHP szűrővel

Regisztráljon egyéni mezőket programozottan a blockstudio/fields szűrővel:

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

Használat block.json alatt

Hivatkozzon egy egyéni mezőre a custom/{name} típus használatával:

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

Ez beágyazottan kiterjeszti az egyéni mező definíciójában meghatározott mezőket. A kiterjesztett mezők az eredeti azonosítóikat használják (heading, description, enabled).

Az egyéni mezők teljes csoportdefiníciókat is újrafelhasználhatnak:

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

A csoport gyermekei section-header_kicker, section-header_title stb. néven tárolódnak. A sablonokban használja a bs_get_group() elemet, hogy tiszta csoportobjektummá alakítsa őket.

Azonosítóstruktúra

Használja a idStructure elemet a mezőazonosítók előtagolására vagy átalakítására. A {id} helyőrző az eredeti mezőazonosítóval helyettesítődik:

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

Ez a következő azonosítójú mezőket hozza létre: hero_heading, hero_description, hero_enabled.

Felülbírálások

Az egyes mezőket példányonként testre szabhatja a overrides használatával. A kulcsok a definíció eredeti mezőazonosítói:

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

A felülíró tulajdonságok az eredeti meződefinícióhoz adódnak hozzá. A id felülírás megkerüli a idStructure mintát. A fenti példában a enabled értéke active lesz hero_enabled helyett.

Az összevonás egy szint mély: a felülírt tulajdonság teljes egészében lecseréli az eredeti tulajdonságot. Egy options felülírás a teljes opciólista, nem annak kiegészítése, és ugyanez érvényes a conditions elemre, valamint egy csoport attributes értékére is. A hivatkozás feltételei ezután is hozzáadódnak.

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

Ez a blokk csak fehér és szürke színt kínál, függetlenül attól, hány lehetőség szerepel a definícióban.

Feltételek

Az egyéni meződefiníciókon belüli feltételek automatikusan átíródnak a idStructure alkalmazásakor. A testvérmezőtől feltételesen függő mezők a kiterjesztés után is működnek.

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

A Blockstudio ezt a következőkre terjeszti ki: title_font_enable, title_font_min, title_font_max, és átírja a feltételeket, hogy a title_font_enable elemre hivatkozzanak enable helyett. A kapcsolók pontosan úgy működnek, mintha a mezők beágyazottan lennének definiálva.

Hivatkozási szintű feltételek

Adja hozzá a conditions elemet a hivatkozáshoz, hogy minden kiterjesztett mezőre alkalmazza őket. Ez hasznos, ha egy teljes csoportot egy külső kapcsoló mögé szeretne rejteni:

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

Ezek a feltételek összeolvadnak a meződefiníción belül már meghatározott feltételekkel. A feltételazonosítók szintén átíródnak a idStructure segítségével.

Több egyéni mező

Egyetlen blokkban több egyéni mezőt is használhat a normál mezők mellett:

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

Beágyazás

Az egyéni mezők csoportokon, füleken és ismétlőkön belül is működnek:

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

További felderítési útvonalak

Használja a blockstudio/fields/paths szűrőt további könyvtárak hozzáadásához a mezők felderítéséhez:

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

Statikus elemzés

A blockstudio/phpstan csomag kiterjeszti a fájlalapú custom/* hivatkozásokat a PHP, Twig, Blade, blokkcímkék és következtetett attribútumformák ellenőrzésekor. A kiterjesztés ugyanazokat a beágyazási, idStructure és overrides szabályokat követi, amelyeket fent ismertettünk.

Az elemzett projekten kívüli definíciók esetén adja hozzá a könyvtárat a blockstudioScanRoots beállításhoz a phpstan.neon fájlban. A kizárólag a blockstudio/fields PHP szűrőn keresztül regisztrált mezők futásidőben léteznek, ezért statikusan nem következtethetők ki.