Preskočiť na obsah

Kuchárska kniha vzorov polí

Systém polí Blockstudio je sám osebe jednoduchý: pridáte pole do blockstudio.attributes a v šablóne k nemu pristupujete cez $a. Skutočné bloky však zriedka obsahujú iba jedno pole. Majú skupiny súvisiacich nastavení, polia, ktoré sa zobrazujú alebo skrývajú podľa hodnôt iných polí, opakovače so zložitou štruktúrou riadkov a údaje, ktoré treba vedieť vyhľadávať aj mimo editora blokov.

Táto príručka zhromažďuje praktické postupy pre bežné vzory polí. Každý postup ukazuje konfiguráciu block.json a zodpovedajúci kód šablóny. Skopírujte ich priamo do svojich blokov a podľa potreby upravte.

Podmienené polia

Najbežnejší vzor: zobrazovanie alebo skrývanie polí podľa hodnoty iného poľa. Editor tak zostáva prehľadný, pretože zobrazuje iba relevantné možnosti.

Zobrazenie možností prepínačom

Blok CTA, v ktorom sa po zapnutí tlačidla zobrazia ďalšie nastavenia:

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

Polia pre text tlačidla a odkaz sa zobrazia iba vtedy, keď je prepínač zapnutý. V šablóne pred vykreslením skontrolujte stav prepínača:

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>

Výberom prepínajte sady polí

Blok úvodnej sekcie, v ktorom typ pozadia určuje zobrazené polia:

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

Pole priehľadnosti prekrytia používa !=, aby sa zobrazovalo pri všetkých typoch pozadia okrem plnej farby. Naraz sa zobrazuje iba jedno pole pozadia. Pole typu color vracia pole obsahujúce value farby, name a slug, preto šablóna číta ['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>

Podmienky OR

Pole zobrazte, keď platí ktorákoľvek z viacerých podmienok. Každé vnútorné pole je skupina podmienok spojených pomocou AND; vonkajšie pole ich kombinuje pomocou OR:

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

Tým sa pole titulku zobrazí, keď je bgType „image“ ALEBO „video“.

Reťazené podmienky

Viaceré podmienky v tom istom vnútornom poli používajú logiku AND:

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

Pole alternatívneho textu sa zobrazí iba vtedy, keď je bgType „image“ A zároveň je vybratý obrázok.

Globálne podmienky

Zobrazujte polia podľa typu príspevku, ID príspevku alebo roly používateľa namiesto hodnôt iných polí:

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

Dostupné typy globálnych podmienok: postType, postId, userRole, userId.

Usporiadané nastavenia

Keď sa bloky skomplikujú, rozdelenie polí do logických skupín pomáha udržať panel inšpektora prehľadný.

Skupiny na vizuálne usporiadanie

Skupiny vytvárajú v paneli inšpektora rozbaľovacie sekcie. Nepomenovaná skupina (bez id) slúži iba na vizuálne usporiadanie; k jej poliam pristupujete pomocou samotných ID:

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>

K poliam sa pristupuje priamo: $a['title'], $a['style'], $a['accentColor']. Skupiny ovplyvňujú iba rozloženie v paneli inšpektora.

Pomenované skupiny s bs_get_group

Keď má skupina id, ID jej podriadených polí dostanú tento prefix. Na jeho odstránenie použite 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 }
  ]
}

Bez pomocnej funkcie sa k poliam pristupuje ako k $a['author_name'], $a['author_role'], $a['author_avatar']. S pomocnou funkciou:

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>

Pomenované skupiny sa hodia, keď sa rovnaké názvy polí objavujú vo viacerých skupinách (e.g, author_name a company_name), alebo keď chcete skupinu odovzdať ako celok čiastkovej šablóne.

Rozloženie skupín do mriežky

Pomocou vlastnosti style usporiadajte podriadené prvky skupiny vedľa seba:

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 polia jednotiek sa v paneli inšpektora zobrazia vedľa seba namiesto pod sebou. Hodí sa to pre dvojice rozmerov, hodnoty okrajov a vnútorných odsadení alebo ľubovoľné dve koncepčne súvisiace polia.

Karty pre hlavné sekcie

Keď má blok veľa nastavení, karty zabezpečia prehľadnejšie usporiadanie než dlhý zoznam skupín:

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

K poliam každej karty sa pristupuje ako k poliam najvyššej úrovne: $a['title'], $a['image'], $a['layout']. Karty slúžia výhradne ako kontajner UI.

Vzory opakovačov

Opakovače umožňujú používateľom pridávať viacero riadkov polí. Sú nevyhnutné pre zoznamy, mriežky, časové osi a všetky komponenty s premenlivým počtom položiek.

Základný opakovač s obmedzeniami

Zoznam funkcií s 1 až 6 položkami:

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>

Vlastné označenia riadkov

Predvolene sa v zbalených riadkoch opakovača zobrazuje všeobecné označenie. Pomocou textMinimized namiesto neho zobrazte hodnotu poľa:

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

Po zbalení riadka sa namiesto „Riadok 1“ zobrazí meno osoby. Ak je pole mena prázdne, použije sa fallback. Môžete tiež pridať reťazce prefix a suffix.

Podmienky v opakovačoch

Polia v opakovači môžu odkazovať na iné polia v tom istom riadku pomocou samotného id (prefix netreba):

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

Odkazovanie na vonkajšie polia z opakovača

Ak podmienka v opakovači potrebuje skontrolovať pole mimo neho, pridajte "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"
      }]]
    }
  ]
}

Bez "context": "main" by podmienka hľadala pole showDescriptions v riadku opakovača. S ním kontroluje prepínač na koreňovej úrovni.

Karty v opakovačoch

Karty nie sú v opakovačoch dostupné: pole tabs v riadku opakovača zobrazí v editore upozornenie namiesto svojich polí a rozšírenie PHPStan to nahlási. Polia v riadku ponechajte na jednej úrovni. Pri dlhých riadkoch pomôže vlastný názov riadka (textMinimized) zachovať prehľadnosť zbalených riadkov. Podmienky v riadku môžu skryť polia potrebné iba v niektorých riadkoch, ako ukazujú vyššie uvedené vzory.

Nastavením "minimized": true v opakovači sa existujúce riadky predvolene zbalia. Novopridané riadky sa hneď otvoria. Výnimky, ktoré zostanú rozbalené, sa v tomto prehliadači uchovajú aj po opätovnom načítaní editora; ide o predvoľbu úprav, nie o uložený obsah príspevku. Opakovače bez minimized si zachovajú doterajšie správanie, pri ktorom sú predvolene rozbalené.

Vzory médií

Jeden obrázok so záložným obrázkom

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

Predvolená hodnota returnFormat je "object", ktorá poskytuje ID, title, alt, caption, description, href, url a sizes. sizes obsahuje URL každej registrovanej veľkosti obrázka (sizes['large']) spolu s jej rozmermi (sizes['large-width'], sizes['large-height']). Úplný zoznam nájdete v časti Atribúty vykresľovania.

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

Vypínateľný obrázok s prepínačom

Vlastnosť switch pridá ikonu oka, ktorá používateľom umožňuje vypnúť pole bez odstránenia jeho hodnoty:

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

Používateľ môže logo vypnúť bez odstránenia nahraného súboru. Po opätovnom zapnutí sa zobrazí ten istý súbor.

Varianty formátu návratovej hodnoty

Nastavte, čo vracia pole súborov:

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"

Použite "id", keď potrebujete sami zavolať wp_get_attachment_image(). Pre jednoduché obrázky na pozadí použite "url". Na všetko ostatné použite "object" (predvolené nastavenie).

Pri použití "returnFormat": "id" sa importovaný reťazcový odkaz, napríklad "buckshair-home", odovzdá bez zmeny. Editor zobrazí náhradnú kartu bez miniatúry, a to aj v riadkoch opakovača. Otvorením ani uložením stránky sa skalárny odkaz nezmení na pole. Fungujú aj zmiešané zoznamy ID príloh a reťazcových odkazov; v knižnici médií sa vyhľadávajú iba kladné ID príloh.

Blockstudio nerozpoznáva vlastné reťazcové odkazy ako prílohy. Ak na rôznych weboch používate prenositeľné názvy, rozpoznajte ich vo vlastnom filtri vykresľovania alebo šablóne. Výberom náhrady v knižnici médií sa ako zvyčajne uloží jej ID prílohy.

Dynamické možnosti

Naplnenie príspevkami

Pole výberu so zoznamom všetkých publikovaných stránok:

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

Pole sa automaticky naplní názvami stránok ako označeniami a ID príspevkov ako hodnotami. Mapovanie upravíte pomocou returnFormat v konfigurácii naplnenia:

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

Naplnenie výrazmi taxonómie

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

Naplnenie z funkcie PHP

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

Statické možnosti s doplnenými položkami

Skombinujte napevno zadané možnosti s dynamickými. Pomocou position určte, kde sa majú zobraziť dynamicky doplnené 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"
  }
}

Najprv sa zobrazia statické možnosti a za nimi dynamicky doplnené stránky.

Ukladanie údajov pre dopyty

Predvolene sa hodnoty polí ukladajú v atribútoch bloku v rámci post_content. Pomocou WP_Query ich nemožno vyhľadávať. Ak potrebujete filtrovať alebo triediť príspevky podľa hodnoty poľa, použite úložisko.

Metadáta príspevku pre polia dostupné v dopytoch

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

Teraz môžete vyhľadávať odporúčané príspevky:

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 kľúče sa automaticky registrujú pomocou show_in_rest, takže sú dostupné aj v REST API.

Dvojité úložisko

Ukladajte údaje do atribútov bloku aj do metadát príspevku. Atribút bloku sprístupňuje hodnotu v šablónach cez $a, zatiaľ čo metadáta príspevku umožňujú vyhľadávanie:

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

Ukladanie globálnych hodnôt do možností

Pre nastavenia platné na celom webe, ktoré majú byť všade rovnaké, použite úložisko možností:

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

Hodnota sa uloží v wp_options a kdekoľvek k nej možno pristupovať pomocou get_option('site_company_name'). Keď používateľ upraví toto pole v ktorejkoľvek inštancii bloku, hodnota sa aktualizuje globálne.

Opakovane použiteľné definície polí

Keď viacero blokov používa rovnakú štruktúru polí, definujte ju raz ako vlastné pole a odkazujte naň všade.

Vytvorenie vlastného poľa

Vytvorte field.json v adresári blockstudio/fields/ svojej témy:

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

Použitie vlastného poľa

Odkážte naň v ľubovoľnom bloku pomocou "type": "custom/cta":

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

Polia CTA sa vložia priamo do bloku. Pristupujte k nim priamo: $a['label'], $a['url'], $a['style'].

Vlastné polia s prefixom pomocou idStructure

Pri opakovanom použití toho istého vlastného poľa pridajte idStructure, aby sa k ID pridali prefixy:

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

Polia prvého CTA budú mať názvy primary_label, primary_url, primary_style. Druhé bude mať secondary_label atď.

Prepísanie predvolených hodnôt

Pri odkazovaní na vlastné pole môžete upraviť konkrétne polia:

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

Úpravy sa zlúčia s pôvodnou definíciou a prepíšu ju. Môžete zmeniť predvolené hodnoty, označenia, podmienky alebo ľubovoľnú inú vlastnosť.

Vzory vykresľovania

Kontrola prázdnych hodnôt

Väčšina typov polí vracia prázdnu hodnotu false. Pred vykreslením to vždy skontrolujte:

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

Pri číslach je 0 platná hodnota. Ak potrebujete rozlíšiť medzi „prázdne“ a „nula“, použite striktné porovnanie:

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

Výber s returnFormat: both

Keď potrebujete hodnotu (pre logiku) aj označenie (pre zobrazenie):

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

Dátové atribúty z poľa attributes

Typ poľa attributes umožňuje používateľom pridávať vlastné dátové atribúty:

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>

Premenné CSS z hodnôt polí

Vytvorte vlastné vlastnosti CSS z vybraných polí:

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>

Výsledkom je style="--text-color: #333; --font-size: 1rem;" (ID polí sa prevedú na formát kebab-case). Premenné použite vo svojom CSS:

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

Ďalšie kroky

  • Registrácia atribútov: vlastnosti id, type, label, default, help, position a conditions.
  • Prehľad typov polí: automaticky generovaný prehľad všetkých vlastností každého typu poľa.
  • Podmienená logika: operátory, globálne podmienky, vlastné filtre podmienok a kontext opakovača.
  • Naplnenie možností: režimy dopytov, funkcií, vlastných hodnôt a načítania pre dynamické polia možností.
  • Vlastné polia: field.json, cesty vyhľadávania, filter blockstudio/fields a pokročilé vzory idStructure.
  • Vykresľovanie: $a, $b, $c, prázdne hodnoty a pomocné funkcie.