Preskoči na vsebino

Kuharica vzorcev polj

Sistem polj v Blockstudio je sam po sebi preprost: polje dodate v blockstudio.attributes, v predlogi pa do njega dostopate prek $a. Toda pravi bloki imajo le redko samo eno polje. Vsebujejo skupine povezanih nastavitev, polja, ki se prikažejo ali skrijejo glede na druga polja, ponavljajoča se polja z zapleteno strukturo vrstic in podatke, po katerih je treba poizvedovati zunaj urejevalnika blokov.

Ta vodnik vsebuje praktične recepte za pogoste vzorce polj. Vsak recept prikazuje konfiguracijo block.json in ustrezno kodo predloge. Kopirajte jih neposredno v svoje bloke in jih po potrebi prilagodite.

Pogojna polja

Najpogostejši vzorec: prikazovanje ali skrivanje polj glede na vrednost drugega polja. Tako urejevalnik ostane pregleden, saj prikazuje le ustrezne možnosti.

Preklop za prikaz možnosti

Blok CTA, v katerem se dodatne nastavitve prikažejo, ko uporabnik omogoči gumb:

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

Polji za besedilo gumba in povezavo se prikažeta samo, ko je preklop vklopljen. V predlogi pred izrisom preverite stanje preklopa:

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>

Izbirnik za preklapljanje med nabori polj

Blok z veliko uvodno pasico, kjer vrsta ozadja določa, katera polja se prikažejo:

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

Polje za prosojnost prekrivne plasti uporablja !=, da se prikaže pri vseh vrstah ozadja razen pri enobarvnem. Hkrati je prikazano samo eno polje za ozadje. Polje color vrne matriko z value, name in slug barve, zato predloga prebere ['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>

Pogoji ALI

Polje prikažite, ko velja kateri koli od več pogojev. Vsaka notranja matrika je skupina IN, zunanja matrika pa jih poveže z ALI:

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

To prikaže polje za napis, ko je bgType »image« ALI »video«.

Povezani pogoji

Več pogojev v isti notranji matriki uporablja logiko IN:

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

Polje za nadomestno besedilo se prikaže le, ko je bgType »image« IN je izbrana slika.

Globalni pogoji

Polja prikažite glede na vrsto objave, ID objave ali uporabniško vlogo namesto glede na vrednosti drugih polj:

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

Na voljo so te vrste globalnih pogojev: postType, postId, userRole, userId.

Urejene nastavitve

Ko postanejo bloki zapleteni, urejanje polj v logične skupine olajša uporabo pregledovalnika.

Skupine za vizualno razporeditev

Skupine v pregledovalniku ustvarijo zložljive razdelke. Neimenovana skupina (brez id) je zgolj vizualna; do njenih polj dostopate z njihovimi samostojnimi ID-ji:

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>

Do polj dostopate neposredno: $a['title'], $a['style'], $a['accentColor']. Skupine vplivajo samo na razporeditev pregledovalnika.

Poimenovane skupine z bs_get_group

Ko ima skupina id, se pred ID-je njenih podrejenih polj doda predpona. Za njeno odstranitev uporabite 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 }
  ]
}

Brez pomožne funkcije do polj dostopate kot do $a['author_name'], $a['author_role'], $a['author_avatar']. Z njo pa:

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>

Poimenovane skupine so uporabne, kadar se ista imena polj pojavijo v več skupinah (e.g., author_name in company_name) ali kadar želite skupino kot celoto posredovati delni predlogi.

Mrežna postavitev v skupinah

Z lastnostjo style razporedite podrejena polja skupine drugo ob drugem:

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

Dve polji za enote se v pregledovalniku izrišeta drugo ob drugem namesto eno pod drugim. To je primerno za pare mer, vrednosti robov in notranjih odmikov ali kateri koli dve pojmovno povezani polji.

Zavihki za glavne razdelke

Ko ima blok veliko nastavitev, zavihki zagotovijo preglednejšo organizacijo kot dolg seznam skupin:

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

Do polj vsakega zavihka dostopate kot do polj na najvišji ravni: $a['title'], $a['image'], $a['layout']. Zavihki so zgolj UI vsebnik.

Vzorci ponavljajočih se polj

Ponavljajoča se polja uporabnikom omogočajo dodajanje več vrstic polj. Nujna so za sezname, mreže, časovnice in vse komponente s spremenljivim številom elementov.

Osnovno ponavljajoče se polje z omejitvami

Seznam funkcij z 1 do 6 elementi:

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>

Oznake vrstic po meri

Strnjene vrstice ponavljajočega se polja imajo privzeto splošno oznako. Z textMinimized lahko namesto nje prikažete vrednost polja:

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

Ko je vrstica strnjena, je namesto »Vrstica 1« prikazano ime osebe. Če je polje za ime prazno, se uporabi fallback. Dodate lahko tudi niza prefix in suffix.

Pogojna polja znotraj ponavljajočih se polj

Polja znotraj ponavljajočega se polja se lahko sklicujejo na druga polja v isti vrstici z uporabo njihovih samostojnih id (predpona ni potrebna):

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

Sklicevanje na zunanja polja znotraj ponavljajočega se polja

Kadar mora pogoj znotraj ponavljajočega se polja preveriti polje zunaj njega, dodajte "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"
      }]]
    }
  ]
}

Brez "context": "main" bi pogoj iskal polje showDescriptions znotraj vrstice ponavljajočega se polja. Z njim pogoj preveri preklop na korenski ravni.

Zavihki znotraj ponavljalnikov

Zavihki znotraj ponavljalnikov niso na voljo: polje tabs znotraj vrstice ponavljalnika v urejevalniku prikaže obvestilo namesto svojih polj, razširitev PHPStan pa to javi. Polja v vrstici pustite na isti ravni. Pri dolgih vrsticah oznaka po meri (textMinimized) poskrbi, da so strnjene vrstice berljive, pogoji znotraj vrstice pa lahko skrijejo polja, ki jih potrebujejo le nekatere vrstice, kot je prikazano v zgornjih vzorcih.

Na ponavljalniku nastavite "minimized": true, da se obstoječe vrstice privzeto strnejo. Novo dodane vrstice se odprejo takoj. Razširjene izjeme si ta brskalnik zapomni tudi po ponovnem nalaganju urejevalnika; to je nastavitev urejanja, ne shranjena vsebina objave. Ponavljalniki brez minimized ohranijo obstoječe privzeto vedenje, pri katerem so vrstice razširjene.

Vzorci za predstavnost

Ena slika z nadomestno možnostjo

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; ?>

Privzeti returnFormat je "object", ki zagotavlja ID, title, alt, caption, description, href, url in sizes. sizes vsebuje URL vseh registriranih velikosti slik (sizes['large']) z njihovimi dimenzijami (sizes['large-width'], sizes['large-height']). Celoten seznam najdete v razdelku Atributi za izris.

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; ?>

Sliko je mogoče onemogočiti s preklopom

Lastnost switch doda ikono očesa, s katero lahko uporabniki onemogočijo polje, ne da bi izbrisali njegovo vrednost:

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; ?>

Uporabnik lahko izklopi logotip, ne da bi odstranil naloženo datoteko. Ko ga znova omogoči, se prikaže ista datoteka.

Različne oblike vrnjene vrednosti

Nastavite, kaj vrne polje datotek:

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"

Uporabite "id", kadar želite sami poklicati wp_get_attachment_image(). Za preproste slike ozadja uporabite "url". Za vse drugo uporabite "object" (privzeto).

Pri "returnFormat": "id" se uvoženi sklic na niz, na primer "buckshair-home", posreduje nespremenjen. Urejevalnik prikaže nadomestno kartico brez sličice, tudi v vrsticah ponavljalnika. Če stran odprete ali shranite, se skalarni sklic ne pretvori v polje. Delujejo tudi mešani seznami ID-jev prilog in sklicev na nize; v medijski knjižnici se poiščejo samo pozitivni ID-ji prilog.

Blockstudio ne razreši sklicev na nize po meri v priloge. Če na različnih spletnih mestih uporabljate prenosljiva imena, jih razrešite v lastnem filtru za izris ali predlogi. Če v medijski knjižnici izberete zamenjavo, se kot običajno shrani ID priloge.

Dinamične možnosti

Polnjenje iz objav

Izbirno polje s seznamom vseh objavljenih strani:

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

Polje se samodejno napolni z naslovi strani kot oznakami in ID-ji objav kot vrednostmi. Za prilagoditev preslikave v konfiguraciji populate uporabite returnFormat:

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

Polnjenje z izrazi taksonomije

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

Polnjenje s funkcijo PHP

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

Statične možnosti z dodatnimi napolnjenimi možnostmi

Združite trdo kodirane in dinamične možnosti. Z position določite, kje se prikažejo napolnjene možnosti:

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

Najprej se prikažejo statične možnosti, nato dinamično napolnjene strani.

Shranjevanje podatkov za poizvedbe

Vrednosti polj so privzeto shranjene v atributih bloka znotraj post_content. Z WP_Query po njih ni mogoče poizvedovati. Če morate objave filtrirati ali razvrščati glede na vrednost polja, uporabite shrambo.

Meta podatki objave za polja, po katerih je mogoče poizvedovati

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

Zdaj lahko poizvedujete po izpostavljenih objavah:

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 ključi se samodejno registrirajo z show_in_rest, zato so na voljo tudi v REST API.

Dvojna shramba

Shranjujte v atributih bloka in meta podatkih objave. Atribut bloka ohrani vrednost, ki je v predlogah na voljo prek $a, meta podatki objave pa omogočajo poizvedovanje po njej:

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

Shramba možnosti za globalne vrednosti

Za nastavitve, ki naj bodo enake na celotnem spletnem mestu, uporabite shrambo možnosti:

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

Vrednost je shranjena v wp_options in je kjer koli dostopna prek get_option('site_company_name'). Ko uporabnik uredi to polje v kateri koli instanci bloka, se vrednost posodobi globalno.

Ponovno uporabne definicije polj

Ko ima več blokov enako strukturo polj, jo določite enkrat kot polje po meri in se nanjo sklicujte povsod.

Ustvarjanje polja po meri

V imeniku blockstudio/fields/ svoje teme ustvarite field.json:

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

Uporaba polja po meri

V poljubnem bloku se nanj sklicujte z "type": "custom/cta":

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

Polja CTA so vstavljena neposredno v blok. Dostopajte do njih neposredno: $a['label'], $a['url'], $a['style'].

Polja po meri s predpono z idStructure

Kadar isto polje po meri uporabite večkrat, dodajte idStructure, da ID-jem dodate predpono:

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

Polja prvega CTA-ja postanejo primary_label, primary_url, primary_style. Polja drugega postanejo secondary_label itd.

Preglasitev privzetih vrednosti

Ob sklicevanju na polje po meri prilagodite posamezna polja:

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

Preglasitve se združijo z izvirno definicijo. Spremenite lahko privzete vrednosti, oznake, pogoje ali katero koli drugo lastnost.

Vzorci izrisa

Preverjanje praznih vrednosti

Večina vrst polj vrne false, ko je prazna. Pred izrisom vedno preverite vrednost:

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

Pri številih je 0 veljavna vrednost. Če morate razlikovati med »prazno« in »nič«, uporabite strogo primerjavo:

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

Izbirno polje z returnFormat: both

Kadar potrebujete tako vrednost (za logiko) kot oznako (za prikaz):

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; ?>

Podatkovni atributi iz polja attributes

Vrsta polja attributes uporabnikom omogoča dodajanje podatkovnih atributov po meri:

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>

Spremenljivke CSS iz vrednosti polj

Iz izbranih polj ustvarite lastnosti CSS po meri:

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>

To ustvari style="--text-color: #333; --font-size: 1rem;" (ID-ji polj se pretvorijo v zapis kebab-case). Spremenljivke uporabite v svojem CSS:

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

Naslednji koraki

  • Registracija atributov: lastnosti id, type, label, default, help, position in conditions.
  • Referenca vrst polj: samodejno ustvarjena referenca z vsako lastnostjo za vsako vrsto polja.
  • Pogojna logika: operatorji, globalni pogoji, filtri pogojev po meri in kontekst ponavljajočih se polj.
  • Polnjenje možnosti: načini poizvedbe, funkcije, po meri in pridobivanja za dinamična izbirna polja.
  • Polja po meri: field.json, poti iskanja, filter blockstudio/fields in napredni vzorci idStructure.
  • Izris: $a, $b, $c, prazne vrednosti in pomožne funkcije.