Siirry sisältöön

Kenttäkuvioiden keittokirja

Blockstudion kenttäjärjestelmä on yksinään yksinkertainen: lisää kenttä kohteeseen blockstudio.attributes ja käytä sitä mallipohjassasi $a-merkinnällä. Todellisissa lohkoissa on kuitenkin harvoin vain yksi kenttä. Niissä on toisiinsa liittyvien asetusten ryhmiä, muiden kenttien arvojen mukaan näytettäviä tai piilotettavia kenttiä, monimutkaisia rivirakenteita sisältäviä toistimia sekä tietoja, joita täytyy voida kysellä lohkoeditorin ulkopuolella.

Tähän oppaaseen on koottu käytännön ohjeita yleisiin kenttäkuvioihin. Jokaisessa ohjeessa näytetään block.json-määritys ja sitä vastaava mallipohjan koodi. Kopioi ne suoraan lohkoihisi ja mukauta tarvittaessa.

Ehdolliset kentät

Yleisin kuvio on kenttien näyttäminen tai piilottaminen toisen kentän arvon perusteella. Näin muokkain pysyy selkeänä ja näyttää vain olennaiset vaihtoehdot.

Asetusten näyttäminen valinnalla

CTA-lohko, jossa lisäasetukset tulevat näkyviin, kun käyttäjä ottaa painikkeen käyttöön:

JSON
{
  "name": "my-theme/cta",
  "title": "Call to Action",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "Ready to get started?" },
      { "id": "description", "type": "textarea", "label": "Description" },
      { "id": "showButton", "type": "toggle", "label": "Show Button", "default": true },
      {
        "id": "buttonText",
        "type": "text",
        "label": "Button Text",
        "default": "Get Started",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      },
      {
        "id": "buttonUrl",
        "type": "link",
        "label": "Button Link",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      }
    ]
  }
}

Painikkeen teksti- ja linkkikentät näkyvät vain, kun valinta on käytössä. Tarkista valinta mallipohjassa ennen renderöintiä:

PHP
<div useBlockProps>
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <?php if ( $a['description'] ) : ?>
    <p><?php echo esc_html( $a['description'] ); ?></p>
  <?php endif; ?>
  <?php if ( $a['showButton'] && $a['buttonUrl'] ) : ?>
    <a href="<?php echo esc_url( $a['buttonUrl']['url'] ); ?>">
      <?php echo esc_html( $a['buttonText'] ); ?>
    </a>
  <?php endif; ?>
</div>

Valinnalla kenttäjoukkojen vaihtaminen

Hero-lohko, jossa taustatyyppi määrittää näytettävät kentät:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      {
        "id": "bgType",
        "type": "select",
        "label": "Background Type",
        "default": "color",
        "options": [
          { "value": "color", "label": "Solid Color" },
          { "value": "gradient", "label": "Gradient" },
          { "value": "image", "label": "Image" },
          { "value": "video", "label": "Video" }
        ]
      },
      {
        "id": "bgColor",
        "type": "color",
        "label": "Background Color",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "color" }]]
      },
      {
        "id": "bgGradient",
        "type": "gradient",
        "label": "Background Gradient",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "gradient" }]]
      },
      {
        "id": "bgImage",
        "type": "files",
        "label": "Background Image",
        "multiple": false,
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "image" }]]
      },
      {
        "id": "bgVideo",
        "type": "files",
        "label": "Background Video",
        "multiple": false,
        "allowedTypes": ["video"],
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "video" }]]
      },
      {
        "id": "overlay",
        "type": "range",
        "label": "Overlay Opacity",
        "default": 50,
        "min": 0,
        "max": 100,
        "conditions": [[{ "id": "bgType", "operator": "!=", "value": "color" }]]
      }
    ]
  }
}

Peittävyyden kenttä käyttää arvoa !=, jotta se näkyy kaikilla taustatyypeillä paitsi tasaisella värillä. Kullakin hetkellä näkyy vain yksi taustakenttä. color-kenttä palauttaa taulukon, joka sisältää värin value-, name– ja slug-arvot, joten mallipohjassa käytetään merkintää ['value']:

PHP
<?php
$bg_style = match ( $a['bgType'] ) {
	'color'    => $a['bgColor'] ? "background-color: {$a['bgColor']['value']}" : '',
	'gradient' => $a['bgGradient'] ? "background: {$a['bgGradient']}" : '',
	'image'    => $a['bgImage'] ? "background-image: url({$a['bgImage']['url']})" : '',
	default    => '',
};
?>
<div useBlockProps style="<?php echo esc_attr( $bg_style ); ?>">
  <?php if ( $a['bgType'] === 'video' && $a['bgVideo'] ) : ?>
    <video autoplay muted loop playsinline>
      <source src="<?php echo esc_url( $a['bgVideo']['url'] ); ?>" />
    </video>
  <?php endif; ?>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</div>

OR-ehdot

Näytä kenttä, kun mikä tahansa useista ehdoista täyttyy. Jokainen sisempi taulukko on AND-ryhmä; uloin taulukko yhdistää ne OR-operaatiolla:

JSON
{
  "id": "caption",
  "type": "text",
  "label": "Caption",
  "conditions": [
    [{ "id": "bgType", "operator": "==", "value": "image" }],
    [{ "id": "bgType", "operator": "==", "value": "video" }]
  ]
}

Tämä näyttää kuvatekstikentän, kun bgType on “image” TAI “video”.

Ketjutetut ehdot

Saman sisemmän taulukon useat ehdot käyttävät AND-logiikkaa:

JSON
{
  "id": "altText",
  "type": "text",
  "label": "Alt Text",
  "conditions": [[
    { "id": "bgType", "operator": "==", "value": "image" },
    { "id": "bgImage", "operator": "!empty" }
  ]]
}

Vaihtoehtoisen tekstin kenttä näkyy vain, kun bgType on “image” JA kuva on valittu.

Yleiset ehdot

Näytä kentät artikkelityypin, artikkelin tunnuksen tai käyttäjäroolin perusteella muiden kenttien arvojen sijaan:

JSON
{
  "id": "seoTitle",
  "type": "text",
  "label": "SEO Title",
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

Käytettävissä olevat yleiset ehtotyypit: postType, postId, userRole, userId.

Järjestetyt asetukset

Lohkojen monimutkaistuessa kenttien järjestäminen loogisiin ryhmiin pitää tarkastelupaneelin hallittavana.

Ryhmät visuaaliseen järjestämiseen

Ryhmät luovat tarkastelupaneeliin kutistettavia osioita. Nimetön ryhmä (jolta puuttuu id) on vain visuaalinen; sen kenttiin viitataan pelkillä tunnuksilla:

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "title": "Content",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "description", "type": "textarea", "label": "Description" },
          { "id": "image", "type": "files", "label": "Image", "multiple": false }
        ]
      },
      {
        "type": "group",
        "title": "Link",
        "attributes": [
          { "id": "url", "type": "link", "label": "URL" },
          { "id": "openInNewTab", "type": "toggle", "label": "Open in New Tab" }
        ]
      },
      {
        "type": "group",
        "title": "Appearance",
        "attributes": [
          {
            "id": "style",
            "type": "select",
            "label": "Style",
            "default": "elevated",
            "options": [
              { "value": "elevated", "label": "Elevated" },
              { "value": "outlined", "label": "Outlined" },
              { "value": "flat", "label": "Flat" }
            ]
          },
          { "id": "accentColor", "type": "color", "label": "Accent Color" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps>
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['description'] ); ?></p>
</div>

Kenttiin viitataan suoraan: $a['title'], $a['style'], $a['accentColor']. Ryhmät vaikuttavat vain tarkastelupaneelin asetteluun.

Nimetyt ryhmät ja bs_get_group

Kun ryhmällä on id, sen alikenttien tunnuksiin lisätään etuliite. Poista etuliite käyttämällä bs_get_group():

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "avatar", "type": "files", "label": "Avatar", "multiple": false }
  ]
}

Ilman apufunktiota kenttiin viitataan näin: $a['author_name'], $a['author_role'], $a['author_avatar']. Apufunktion avulla:

PHP
<?php $author = bs_get_group( $a, 'author' ); ?>
<div class="author">
  <?php if ( $author['avatar'] ) : ?>
    <img src="<?php echo esc_url( $author['avatar']['url'] ); ?>" alt="" />
  <?php endif; ?>
  <p><?php echo esc_html( $author['name'] ); ?></p>
  <p><?php echo esc_html( $author['role'] ); ?></p>
</div>

Nimetyt ryhmät ovat hyödyllisiä, kun samoja kenttien nimiä esiintyy useissa ryhmissä (e.g, author_name ja company_name) tai kun haluat välittää ryhmän kokonaisuutena osittaiseen mallipohjaan.

Ruudukkoasettelu ryhmissä

Järjestä ryhmän alikentät vierekkäin style-ominaisuudella:

JSON
{
  "type": "group",
  "title": "Dimensions",
  "style": {
    "display": "grid",
    "grid-template-columns": "1fr 1fr",
    "grid-gap": "16px"
  },
  "attributes": [
    { "id": "width", "type": "unit", "label": "Width", "default": "100%", "switch": false },
    { "id": "height", "type": "unit", "label": "Height", "default": "auto", "switch": false }
  ]
}

Kaksi yksikkökenttää näkyvät tarkastelupaneelissa vierekkäin peräkkäin asettamisen sijaan. Tämä sopii hyvin mittapareille, marginaali- ja täytearvoille sekä muille kahden käsitteellisesti yhteen kuuluvan kentän pareille.

Välilehdet pääosioille

Kun lohkossa on paljon asetuksia, välilehdet järjestävät ne selkeämmin kuin pitkä ryhmäluettelo:

JSON
{
  "type": "tabs",
  "tabs": [
    {
      "title": "Content",
      "attributes": [
        { "id": "title", "type": "text", "label": "Title" },
        { "id": "body", "type": "wysiwyg", "label": "Body" }
      ]
    },
    {
      "title": "Media",
      "attributes": [
        { "id": "image", "type": "files", "label": "Image", "multiple": false },
        { "id": "video", "type": "files", "label": "Video", "multiple": false, "allowedTypes": ["video"] }
      ]
    },
    {
      "title": "Settings",
      "attributes": [
        { "id": "layout", "type": "select", "label": "Layout", "options": [
          { "value": "left", "label": "Media Left" },
          { "value": "right", "label": "Media Right" }
        ]},
        { "id": "fullWidth", "type": "toggle", "label": "Full Width" }
      ]
    }
  ]
}

Kunkin välilehden kenttiä käytetään kuten ylätason kenttiä: $a['title'], $a['image'], $a['layout']. Välilehdet ovat pelkkiä UI-säiliöitä.

Toistinkuvioita

Toistimilla käyttäjät voivat lisätä useita kenttärivejä. Ne ovat välttämättömiä luetteloissa, ruudukoissa, aikajanoissa ja kaikissa komponenteissa, joissa kohteiden määrä vaihtelee.

Perustoistin rajoituksilla

Ominaisuusluettelo, jossa on 1–6 kohdetta:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 6,
  "textButton": "Add Feature",
  "attributes": [
    { "id": "icon", "type": "icon", "label": "Icon" },
    { "id": "title", "type": "text", "label": "Title", "default": "Feature" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-8">
  <?php foreach ( $a['features'] as $feature ) : ?>
    <div>
      <?php if ( $feature['icon'] ) : ?>
        <?php bs_render_icon( $feature['icon'] ); ?>
      <?php endif; ?>
      <h3><?php echo esc_html( $feature['title'] ); ?></h3>
      <p><?php echo esc_html( $feature['description'] ); ?></p>
    </div>
  <?php endforeach; ?>
</div>

Mukautetut rivien otsikot

Pienennetyissä toistimen riveissä näkyy oletuksena yleinen otsikko. Näytä sen sijaan kentän arvo käyttämällä textMinimized-asetusta:

JSON
{
  "id": "team",
  "type": "repeater",
  "label": "Team Members",
  "textMinimized": { "id": "name", "fallback": "Team Member" },
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "photo", "type": "files", "label": "Photo", "multiple": false }
  ]
}

Kun rivi on kutistettu, siinä näkyy henkilön nimi “Row 1” -tekstin sijaan. fallback-arvoa käytetään, jos nimikenttä on tyhjä. Voit lisätä myös merkkijonot prefix ja suffix.

Ehdot toistimissa

Toistimen sisäiset kentät voivat viitata saman rivin muihin kenttiin käyttämällä niiden pelkkiä id-tunnuksia (etuliitettä ei tarvita):

JSON
{
  "id": "links",
  "type": "repeater",
  "label": "Links",
  "attributes": [
    { "id": "label", "type": "text", "label": "Label" },
    { "id": "url", "type": "link", "label": "URL" },
    {
      "id": "isExternal",
      "type": "toggle",
      "label": "External Link"
    },
    {
      "id": "externalNote",
      "type": "message",
      "label": "Note",
      "description": "External links open in a new tab with rel=\"noopener\".",
      "conditions": [[{ "id": "isExternal", "operator": "==", "value": true }]]
    }
  ]
}

Ulompien kenttien viittaaminen toistimen sisältä

Kun toistimen sisäisen ehdon täytyy tarkistaa toistimen ulkopuolinen kenttä, lisää "context": "main":

JSON
{
  "id": "showDescriptions",
  "type": "toggle",
  "label": "Show Descriptions",
  "default": true
},
{
  "id": "items",
  "type": "repeater",
  "label": "Items",
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    {
      "id": "description",
      "type": "textarea",
      "label": "Description",
      "conditions": [[{
        "id": "showDescriptions",
        "operator": "==",
        "value": true,
        "context": "main"
      }]]
    }
  ]
}

Ilman "context": "main"-merkintää ehto etsisi showDescriptions-kenttää toistimen sisältä. Sen kanssa ehto tarkistaa ylimmän tason valintaa.

Välilehdet toistimien sisällä

Välilehtiä ei voi käyttää toistimien sisällä: toistinrivin tabs-kenttä näyttää editorissa ilmoituksen kenttien sijaan, ja PHPStan-laajennus ilmoittaa siitä. Pidä rivin kentät sen sijaan samalla tasolla. Pitkissä riveissä mukautettu rivinimi (textMinimized) helpottaa tiivistettyjen rivien lukemista, ja rivin sisäisillä ehdoilla voi piilottaa kentät, joita tarvitaan vain joillakin riveillä, kuten yllä olevissa malleissa näytetään.

Aseta toistimelle "minimized": true, jotta olemassa olevat rivit ovat aluksi tiivistettyinä. Uudet rivit avautuvat heti. Avatut poikkeusrivit muistetaan tässä selaimessa editorin uudelleenlatausten välillä. Kyse on muokkausasetuksesta, ei tallennetusta artikkelisisällöstä. Toistimet, joilla ei ole asetusta minimized, säilyttävät nykyisen toimintansa, jossa rivit ovat oletusarvoisesti avattuina.

Mediakuviot

Yksittäinen kuva varakuvalla

JSON
{
  "id": "image",
  "type": "files",
  "label": "Image",
  "multiple": false
}
PHP
<?php if ( $a['image'] ) : ?>
  <img
    src="<?php echo esc_url( $a['image']['url'] ); ?>"
    alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
    <?php if ( isset( $a['image']['sizes']['full-width'], $a['image']['sizes']['full-height'] ) ) : ?>
      width="<?php echo esc_attr( $a['image']['sizes']['full-width'] ); ?>"
      height="<?php echo esc_attr( $a['image']['sizes']['full-height'] ); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

Oletusarvoinen returnFormat on "object", joka tarjoaa ID, title, alt, caption, description, href, url ja sizes. sizes sisältää kaikkien rekisteröityjen kuvakokojen URL-tiedot (sizes['large']) mittoineen (sizes['large-width'], sizes['large-height']). Katso täydellinen luettelo kohdasta Renderöintimääritteet.

JSON
{
  "id": "gallery",
  "type": "files",
  "label": "Gallery",
  "multiple": true,
  "max": 6,
  "allowedTypes": ["image"]
}
PHP
<?php if ( $a['gallery'] ) : ?>
  <div class="grid grid-cols-3 gap-4">
    <?php foreach ( $a['gallery'] as $image ) : ?>
      <img
        src="<?php echo esc_url( $image['url'] ); ?>"
        alt="<?php echo esc_attr( $image['alt'] ); ?>" />
    <?php endforeach; ?>
  </div>
<?php endif; ?>

Käytöstä poistettava kuva valitsimella

switch-ominaisuus lisää silmäkuvakkeen, jolla käyttäjä voi poistaa kentän käytöstä arvoa poistamatta:

JSON
{
  "id": "logo",
  "type": "files",
  "label": "Logo",
  "multiple": false,
  "switch": true
}
PHP
<?php
$is_disabled = ! empty( $a['_disabled'] ) && in_array( 'logo', $a['_disabled'], true );
if ( $a['logo'] && ! $is_disabled ) : ?>
  <img src="<?php echo esc_url( $a['logo']['url'] ); ?>" alt="" />
<?php endif; ?>

Käyttäjä voi kytkeä logon pois päältä poistamatta ladattua tiedostoa. Kun logo otetaan uudelleen käyttöön, sama tiedosto tulee takaisin.

Palautusmuodon vaihtoehdot

Määritä, mitä tiedostokenttä palauttaa:

JSON
// Full object (default)
{ "id": "photo", "type": "files", "returnFormat": "object", "multiple": false }
// $a['photo']['url'], $a['photo']['alt'], $a['photo']['sizes']['full-width'], etc.

// Just the ID
{ "id": "photo", "type": "files", "returnFormat": "id", "multiple": false }
// $a['photo'] = 42

// Just the URL
{ "id": "photo", "type": "files", "returnFormat": "url", "multiple": false }
// $a['photo'] = "https://example.com/photo.jpg"

Käytä "id"-asetusta, kun haluat kutsua itse wp_get_attachment_image()-funktiota. Käytä "url"-asetusta yksinkertaisille taustakuville. Käytä "object"-asetusta (oletus) kaikissa muissa tapauksissa.

Kun "returnFormat": "id" on käytössä, tuotu merkkijonoviite, kuten "buckshair-home", välitetään muuttumattomana. Editorissa näkyy varakortti ilman pikkukuvaa myös toistinriveillä. Sivun avaaminen tai tallentaminen ei muuta yksittäistä viitettä taulukoksi. Myös liitetunnusten ja merkkijonoviitteiden yhdistelmälistat toimivat. Vain positiivisia liitetunnuksia haetaan mediakirjastosta.

Blockstudio ei yhdistä mukautettuja merkkijonoviitteitä liitteisiin. Ratkaise ne itse renderöintisuodattimessa tai mallissa, kun käytät sivustojen välillä siirrettäviä nimiä. Kun valitset korvaavan tiedoston mediakirjastosta, sen liitetunnus tallennetaan tavalliseen tapaan.

Dynaamiset vaihtoehdot

Täytä artikkeleista

Valintakenttä, jossa luetellaan kaikki julkaistut sivut:

JSON
{
  "id": "linkedPage",
  "type": "select",
  "label": "Linked Page",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "page",
      "post_status": "publish",
      "posts_per_page": -1
    }
  }
}

Kenttä täyttyy automaattisesti sivujen otsikoista valintateksteinä ja artikkelien tunnuksista arvoina. Mukauta määritysten yhdistämistä käyttämällä täyttöasetuksessa returnFormat-kohtaa:

JSON
"populate": {
  "type": "query",
  "query": "posts",
  "arguments": { "post_type": "page" },
  "returnFormat": { "value": "ID", "label": "post_title" }
}

Täytä taksonomian termeistä

JSON
{
  "id": "category",
  "type": "select",
  "label": "Category",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "terms",
    "arguments": {
      "taxonomy": "category",
      "hide_empty": true
    }
  }
}

Täytä PHP-funktiosta

JSON
{
  "id": "postType",
  "type": "select",
  "label": "Post Type",
  "populate": {
    "type": "function",
    "function": "get_post_types",
    "arguments": { "public": true }
  }
}

Staattiset vaihtoehdot ja täydennykset

Yhdistä kovakoodatut vaihtoehdot dynaamisiin. Määritä täytettyjen vaihtoehtojen sijainti position-asetuksella:

JSON
{
  "id": "source",
  "type": "select",
  "label": "Source",
  "options": [
    { "value": "manual", "label": "Manual Entry" },
    { "value": "latest", "label": "Latest Posts" }
  ],
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": { "post_type": "page" },
    "position": "after"
  }
}

Staattiset vaihtoehdot näkyvät ensin, ja niitä seuraavat dynaamisesti täytetyt sivut.

Tietojen tallentaminen kyselyjä varten

Kenttien arvot tallentuvat oletuksena lohkon määritteisiin kohteessa post_content. Niitä ei voi hakea WP_Query-toiminnolla. Käytä tallennusta, kun haluat suodattaa tai lajitella artikkeleita kentän arvon perusteella.

Artikkelien metatiedot kyseltäville kentille

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
},
{
  "id": "priority",
  "type": "number",
  "label": "Priority",
  "default": 0,
  "min": 0,
  "max": 100,
  "storage": {
    "type": "postMeta",
    "postMetaKey": "priority_score"
  }
}

Nyt voit hakea esittelyyn nostettuja artikkeleita:

PHP
$featured = new WP_Query( array(
    'meta_query' => array(
        array(
            'key'   => 'is_featured',
            'value' => '1',
        ),
    ),
    'orderby'  => 'meta_value_num',
    'meta_key' => 'priority_score',
    'order'    => 'DESC',
) );

Meta-avaimet rekisteröidään automaattisesti show_in_rest-toiminnolla, joten ne ovat käytettävissä myös kohdassa REST API.

Kaksoistallennus

Tallenna sekä lohkon määritteisiin että artikkelin metatietoihin. Lohkon määrite pitää arvon käytettävissä mallipohjissa merkinnällä $a, ja artikkelin metatiedon ansiosta sitä voi käyttää kyselyissä:

JSON
{
  "id": "eventDate",
  "type": "date",
  "label": "Event Date",
  "storage": {
    "type": ["block", "postMeta"],
    "postMetaKey": "event_date"
  }
}

Asetustallennus yleisille arvoille

Koko sivuston asetuksille, joiden pitää olla samat kaikkialla, käytä asetustallennusta:

JSON
{
  "id": "companyName",
  "type": "text",
  "label": "Company Name",
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

Arvo tallentuu kohteeseen wp_options ja on käytettävissä kaikkialla merkinnällä get_option('site_company_name'). Kun käyttäjä muokkaa tätä kenttää missä tahansa lohkon esiintymässä, arvo päivittyy kaikkialla.

Uudelleenkäytettävät kenttämäärittelyt

Kun useat lohkot jakavat saman kenttärakenteen, määritä se kerran mukautettuna kenttänä ja viittaa siihen kaikkialla.

Mukautetun kentän luominen

Luo field.json teeman blockstudio/fields/-hakemistoon:

Koodi
theme/
└── blockstudio/
    └── fields/
        └── cta/
            └── field.json
JSON
{
  "name": "cta",
  "title": "Call to Action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button Label", "default": "Learn More" },
    { "id": "url", "type": "link", "label": "Button URL" },
    { "id": "style", "type": "select", "label": "Button Style", "default": "primary", "options": [
      { "value": "primary", "label": "Primary" },
      { "value": "secondary", "label": "Secondary" },
      { "value": "outline", "label": "Outline" }
    ]}
  ]
}

Mukautetun kentän käyttäminen

Viittaa siihen missä tahansa lohkossa merkinnällä "type": "custom/cta":

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "type": "custom/cta" }
    ]
  }
}

CTA-kentät sisällytetään lohkoon. Käytä niitä suoraan: $a['label'], $a['url'], $a['style'].

Etuliitteelliset mukautetut kentät idStructure-asetuksella

Kun käytät samaa mukautettua kenttää useita kertoja, lisää idStructure tunnusten etuliitteeksi:

JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/cta", "idStructure": "primary_{id}" },
      { "type": "custom/cta", "idStructure": "secondary_{id}" }
    ]
  }
}

Ensimmäisen CTA:n kenttien tunnuksiksi tulee primary_label, primary_url, primary_style. Toisen tunnuksiksi tulee secondary_label jne.

Oletusarvojen ohittaminen

Mukauta tiettyjä kenttiä, kun viittaat mukautettuun kenttään:

JSON
{
  "type": "custom/cta",
  "idStructure": "hero_{id}",
  "overrides": {
    "label": { "default": "Get Started", "label": "CTA Label" },
    "style": { "default": "primary" }
  }
}

Ohitukset yhdistetään alkuperäiseen määritykseen. Voit muuttaa oletusarvoja, nimiöitä, ehtoja ja mitä tahansa muita ominaisuuksia.

Renderöintikuviot

Tyhjien arvojen tarkistaminen

Useimmat kenttätyypit palauttavat tyhjänä arvon false. Tarkista aina arvo ennen renderöintiä:

PHP
<?php if ( $a['title'] ) : ?>
  <h2><?php echo esc_html( $a['title'] ); ?></h2>
<?php endif; ?>

Luvuilla 0 on kelvollinen arvo. Käytä tiukkaa vertailua, jos haluat erottaa “tyhjän” ja “nollan”:

PHP
<?php if ( $a['count'] !== 0 || $a['count'] !== false ) : ?>
  <span><?php echo esc_html( $a['count'] ); ?></span>
<?php endif; ?>

Valinta returnFormat: both

Kun tarvitset sekä arvon (logiikkaa varten) että nimen (näyttämistä varten):

JSON
{
  "id": "status",
  "type": "select",
  "label": "Status",
  "returnFormat": "both",
  "options": [
    { "value": "active", "label": "Active" },
    { "value": "paused", "label": "On Hold" },
    { "value": "closed", "label": "Closed" }
  ]
}
PHP
<?php if ( $a['status'] ) : ?>
  <span class="badge badge--<?php echo esc_attr( $a['status']['value'] ); ?>">
    <?php echo esc_html( $a['status']['label'] ); ?>
  </span>
<?php endif; ?>

Data-määritteet määritekentästä

attributes-kenttätyypin avulla käyttäjät voivat lisätä mukautettuja data-määritteitä:

JSON
{
  "id": "dataAttrs",
  "type": "attributes",
  "label": "Data Attributes",
  "link": true,
  "media": true
}
PHP
<div useBlockProps <?php bs_render_data_attributes( $a['dataAttrs'] ); ?>>
  Content here.
</div>

CSS-muuttujat kenttien arvoista

Luo CSS-mukautettuja ominaisuuksia valituista kentistä:

JSON
{
  "id": "textColor", "type": "color", "label": "Text Color"
},
{
  "id": "fontSize", "type": "unit", "label": "Font Size", "default": "1rem"
}
PHP
<div useBlockProps style="<?php bs_render_variables( $a, array( 'textColor', 'fontSize' ) ); ?>">
  <p>Styled content.</p>
</div>

Tämä tuottaa tulokseksi style="--text-color: #333; --font-size: 1rem;" (kenttätunnukset muunnetaan kebab-case-muotoon). Käytä muuttujia kohteessa CSS:

CSS
p {
  color: var(--text-color);
  font-size: var(--font-size);
}

Seuraavat vaiheet