Siirry sisältöön

Mukautetut kentät

Mukautettujen kenttien avulla voit määrittää uudelleenkäytettäviä kenttäryhmiä, joihin voidaan viitata useissa lohkoissa. Ne ovat kuin kenttämalleja: määritä kerran ja käytä kaikkialla.

Mukautetut kentät eivät ole sama asia kuin mukautetut kenttätyypit. Käytä custom/{name}-määritystä olemassa olevien kenttien uudelleenkäytettäviin ryhmiin. Käytä nimiavaruudellista mukautettua kenttätyyppiä, kuten acme/dimensions, kun teema tai lisäosa rekisteröi uuden editorin ohjaimen ja arvomuodon.

Rekisteröinti tiedostojärjestelmässä

Luo field.json-tiedosto fields/-hakemiston sisälle blockstudio-hakemistossasi:

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

Rekisteröinti PHP-suodattimella

Rekisteröi mukautetut kentät ohjelmallisesti blockstudio/fields-suodattimella:

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

Käyttö kohteessa block.json

Viittaa mukautettuun kenttään käyttämällä tyyppiä custom/{name}:

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

Tämä laajennetaan suoraan mukautetun kentän määrityksessä määritettyihin kenttiin. Laajennetut kentät käyttävät alkuperäisiä tunnuksiaan (heading, description, enabled).

Mukautetuissa kentissä voidaan käyttää uudelleen myös täydellisiä ryhmämäärityksiä:

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

Ryhmän alikohteet tallennetaan arvoina section-header_kicker, section-header_title ja niin edelleen. Voit poimia ne siistiksi ryhmäobjektiksi mallissa käyttämällä arvoa bs_get_group().

Tunnusrakenne

Käytä arvoa idStructure kenttätunnusten etuliitteenä tai niiden muuntamiseen. Paikkamerkki {id} korvataan alkuperäisellä kenttätunnuksella:

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

Näin syntyvät tunnukset: hero_heading, hero_description, hero_enabled.

Ylikirjoitukset

Voit mukauttaa yksittäisiä kenttiä instanssikohtaisesti käyttämällä arvoa overrides. Avaimet ovat määrityksestä peräisin olevia alkuperäisiä kenttätunnuksia:

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

Ohitusominaisuudet yhdistetään alkuperäiseen kenttämääritykseen. id-ohitus ohittaa mallin idStructure. Yllä olevassa esimerkissä arvosta enabled tulee active arvon hero_enabled sijaan.

Yhdistäminen tapahtuu vain yhden tason syvyydeltä: yliajamasi ominaisuus korvaa alkuperäisen ominaisuuden kokonaan. options-yliajo on koko vaihtoehtoluettelo, ei sen täydennys, ja sama pätee ryhmän conditions– ja attributes-kohtiin. Viitteen ehdot lisätään silti jälkikäteen.

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

Tämä lohko tarjoaa vain valkoisen ja harmaan, vaikka määritelmässä olisi kuinka monta vaihtoehtoa.

Ehdot

Mukautettujen kenttämääritysten ehdot kirjoitetaan automaattisesti uudelleen, kun idStructure otetaan käyttöön. Kenttä, jonka näyttäminen riippuu ehdollisesti sisarkentästä, toimii edelleen laajentamisen jälkeen.

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 laajentaa tämän muotoon title_font_enable, title_font_min, title_font_max ja kirjoittaa ehdot uudelleen viittaamaan arvoon title_font_enable arvon enable sijaan. Kytkimet toimivat juuri niin kuin kentät olisi määritetty suoraan.

Viitetason ehdot

Lisää viitteeseen conditions, jotta ehdot koskevat jokaista laajennettua kenttää. Tästä on hyötyä, kun haluat piilottaa koko ryhmän ulkoisen kytkimen taakse:

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

Nämä ehdot yhdistetään kaikkiin kenttämäärityksessä jo oleviin ehtoihin. Ehtojen tunnukset kirjoitetaan myös uudelleen arvon idStructure avulla.

Useita mukautettuja kenttiä

Voit käyttää samassa lohkossa useita mukautettuja kenttiä tavallisten kenttien rinnalla:

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

Sisäkkäisyys

Mukautetut kentät toimivat ryhmien, välilehtien ja toistimien sisällä:

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

Muita etsintäpolkuja

Lisää kenttien etsintähakemistoja käyttämällä suodatinta blockstudio/fields/paths:

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

Staattinen analyysi

blockstudio/phpstan-paketti laajentaa tiedostoihin perustuvat custom/*-viittaukset, kun se tarkistaa PHP-, Twig- ja Blade-arvot, lohkotunnisteet sekä päätellyt määritearvojen muodot. Laajennuksessa noudatetaan yllä kuvattuja sisäkkäisyys-, idStructure– ja overrides-sääntöjä.

Lisää analysoidun projektin ulkopuoliset kirjastohakemistot kohteeseen blockstudioScanRoots tiedostossa phpstan.neon. Vain ajonaikaisesti rekisteröidyt blockstudio/fields PHP-suodattimen kautta tehdyt rekisteröinnit eivät ole pääteltävissä staattisesti.