Treci la conținut

Ghid practic pentru tipare de câmpuri

Sistemul de câmpuri Blockstudio este simplu în sine: adăugați un câmp la blockstudio.attributes și accesați-l prin $a în șablon. Însă blocurile reale rareori au un singur câmp. Ele conțin grupuri de setări asociate, câmpuri afișate sau ascunse în funcție de alte câmpuri, repetări cu structuri complexe de rânduri și date care trebuie să poată fi interogate în afara editorului de blocuri.

Acest ghid reunește rețete practice pentru tipare uzuale de câmpuri. Fiecare rețetă prezintă configurația block.json și codul corespunzător pentru șablon. Copiați-le direct în blocurile dumneavoastră și adaptați-le după nevoie.

Câmpuri condiționale

Cel mai frecvent tipar: afișarea sau ascunderea câmpurilor în funcție de valoarea altui câmp. Astfel, editorul rămâne ordonat și afișează doar opțiunile relevante.

Comutator pentru afișarea opțiunilor

Un bloc CTA în care apar setări suplimentare când utilizatorul activează un buton:

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

Câmpurile pentru textul butonului și link apar doar când comutatorul este activat. În șablon, verificați comutatorul înainte de randare:

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>

Selector pentru schimbarea seturilor de câmpuri

Un bloc hero în care tipul de fundal determină ce câmpuri sunt afișate:

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

Câmpul pentru opacitatea suprapunerii folosește != pentru a apărea la toate tipurile de fundal, cu excepția culorii uniforme. La un moment dat este afișat un singur câmp pentru fundal. Un câmp color returnează un tablou cu value, name și slug culorii, așa că șablonul citește ['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>

Condiții OR

Afișați un câmp când este adevărată oricare dintre mai multe condiții. Fiecare tablou interior reprezintă un grup AND, iar tabloul exterior le combină cu OR:

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

Astfel, câmpul pentru legendă este afișat când bgType este “image” SAU “video”.

Condiții în lanț

Mai multe condiții în același tablou interior folosesc logica AND:

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

Câmpul pentru textul alternativ apare doar când bgType este “image” ȘI a fost selectată o imagine.

Condiții globale

Afișați câmpuri în funcție de tipul articolului, ID-ul articolului sau rolul utilizatorului, în locul valorilor altor câmpuri:

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

Tipuri de condiții globale disponibile: postType, postId, userRole, userId.

Setări organizate

Pe măsură ce blocurile devin complexe, organizarea câmpurilor în grupuri logice menține panoul de inspectare ușor de gestionat.

Grupuri pentru organizare vizuală

Grupurile creează secțiuni pliabile în panoul de inspectare. Un grup fără nume (fără id) este doar vizual; câmpurile sale sunt accesate folosind ID-urile simple:

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>

Câmpurile sunt accesate direct: $a['title'], $a['style'], $a['accentColor']. Grupurile afectează doar aspectul panoului de inspectare.

Grupuri cu nume folosind bs_get_group

Când un grup are un id, ID-urile câmpurilor copil primesc acest prefix. Folosiți bs_get_group() pentru a elimina prefixul:

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

Fără funcția auxiliară, câmpurile sunt accesate astfel: $a['author_name'], $a['author_role'], $a['author_avatar']. Cu funcția auxiliară:

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>

Grupurile cu nume sunt utile când aceleași nume de câmp apar în mai multe grupuri (e.g., author_name și company_name) sau când doriți să transmiteți grupul ca unitate unui șablon parțial.

Aspect grilă în grupuri

Folosiți proprietatea style pentru a aranja câmpurile copil ale grupului unul lângă altul:

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

Cele două câmpuri pentru unități sunt afișate unul lângă altul în panoul de inspectare, nu unul sub altul. Această soluție funcționează bine pentru perechi de dimensiuni, valori de margine sau spațiere internă și orice două câmpuri asociate conceptual.

File pentru secțiuni importante

Când un bloc are multe setări, filele oferă o organizare mai clară decât o listă lungă de grupuri:

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

Câmpurile fiecărei file sunt accesate ca și cum ar fi câmpuri de nivel superior: $a['title'], $a['image'], $a['layout']. Filele sunt doar un container UI.

Tipare pentru repetări

Repetările le permit utilizatorilor să adauge mai multe rânduri de câmpuri. Sunt esențiale pentru liste, grile, cronologii și orice componentă cu un număr variabil de elemente.

Repetare de bază cu limite

O listă de caracteristici cu 1 până la 6 elemente:

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>

Etichete personalizate pentru rânduri

În mod implicit, rândurile minimizate ale unei repetări afișează o etichetă generică. Folosiți textMinimized pentru a afișa în schimb valoarea unui câmp:

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

Când un rând este restrâns, afișează numele persoanei în loc de “Row 1”. fallback este folosit când câmpul pentru nume este gol. Puteți adăuga și șirurile prefix și suffix.

Condiții în repetări

Câmpurile dintr-o repetare pot face referire la alte câmpuri din același rând folosind id simplu (nu este nevoie de prefix):

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

Referirea la câmpuri exterioare dintr-o repetare

Când o condiție dintr-o repetare trebuie să verifice un câmp din afara acesteia, adăugați "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"
      }]]
    }
  ]
}

Fără "context": "main", condiția ar căuta un câmp showDescriptions în rândul repetării. Cu acesta, condiția verifică comutatorul de la nivelul rădăcinii.

File în interiorul repetitoarelor

Filele nu sunt disponibile în interiorul repetitoarelor: un câmp tabs dintr-un rând al unui repetitor afișează o notificare în editor în locul câmpurilor sale, iar extensia PHPStan raportează acest lucru. Păstrați câmpurile unui rând la același nivel. Pentru rândurile lungi, o etichetă personalizată (textMinimized) menține lizibilitatea rândurilor restrânse, iar condițiile din rând pot ascunde câmpurile necesare doar pentru unele rânduri, așa cum se arată în exemplele de mai sus.

Setați "minimized": true pe un repetitor pentru ca rândurile existente să fie restrânse inițial. Rândurile nou adăugate se deschid imediat. Excepțiile extinse sunt reținute în acest browser între reîncărcările editorului; aceasta este o preferință de editare, nu conținut salvat al postării. Repetitoarele fără minimized păstrează comportamentul existent, în care rândurile sunt extinse implicit.

Tipare media

Imagine unică cu rezervă

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

returnFormat implicit este "object", care oferă ID, title, alt, caption, description, href, url și sizes. sizes conține URL pentru fiecare dimensiune de imagine înregistrată (sizes['large']), împreună cu dimensiunile acesteia (sizes['large-width'], sizes['large-height']). Consultați Atributele de randare pentru lista completă.

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

Imagine dezactivabilă cu comutator

Proprietatea switch adaugă o pictogramă cu ochi, care le permite utilizatorilor să dezactiveze câmpul fără a-i șterge valoarea:

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

Utilizatorul poate dezactiva sigla fără să elimine fișierul încărcat. Reactivarea readuce același fișier.

Variante ale formatului returnat

Controlați ce returnează câmpul pentru fișiere:

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"

Folosiți "id" când trebuie să apelați personal wp_get_attachment_image(). Folosiți "url" pentru imagini simple de fundal. Pentru restul, folosiți "object" (valoarea implicită).

Cu "returnFormat": "id", o referință de șir importată, precum "buckshair-home", este transmisă neschimbată. Editorul afișează un card alternativ fără miniatură, inclusiv în rândurile repetitoarelor. Deschiderea sau salvarea paginii nu convertește o referință scalară într-un tablou. Funcționează și listele mixte cu ID-uri de atașamente și referințe de șir; doar ID-urile pozitive ale atașamentelor sunt căutate în biblioteca media.

Blockstudio nu rezolvă referințele personalizate de tip șir la atașamente. Rezolvați-le în propriul filtru de randare sau șablon când folosiți nume portabile între site-uri. Alegerea unui înlocuitor din biblioteca media stochează ID-ul atașamentului, ca de obicei.

Opțiuni dinamice

Preluare din articole

Un câmp selector care listează toate paginile publicate:

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

Câmpul se completează automat cu titlurile paginilor ca etichete și ID-urile articolelor ca valori. Folosiți returnFormat în configurația de populare pentru a personaliza corespondența:

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

Preluare din termenii unei taxonomii

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

Preluare dintr-o funcție PHP

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

Opțiuni statice cu elemente suplimentare preluate dinamic

Combinați opțiuni definite direct în cod cu opțiuni dinamice. Folosiți position pentru a controla unde apar opțiunile preluate:

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

Opțiunile statice apar primele, urmate de paginile preluate dinamic.

Stocarea datelor pentru interogări

În mod implicit, valorile câmpurilor sunt stocate în atributele blocurilor din post_content. Ele nu pot fi interogate cu WP_Query. Când trebuie să filtrați sau să sortați articolele după valoarea unui câmp, folosiți stocarea.

Meta articol pentru câmpuri interogabile

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

Acum puteți interoga articolele recomandate:

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',
) );

Cheile meta sunt înregistrate automat cu show_in_rest, deci sunt disponibile și în REST API.

Stocare dublă

Stocați datele atât în atributele blocului, cât și în meta articol. Atributul blocului păstrează valoarea disponibilă în șabloane prin $a, iar meta articol permite interogarea acesteia:

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

Stocarea opțiunilor pentru valori globale

Pentru setări valabile la nivelul întregului site și identice peste tot, folosiți stocarea în opțiuni:

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

Valoarea este stocată în wp_options și poate fi accesată oriunde cu get_option('site_company_name'). Când utilizatorul editează acest câmp într-o instanță a unui bloc, valoarea se actualizează global.

Definiții reutilizabile de câmpuri

Când mai multe blocuri au aceeași structură de câmpuri, definiți-o o singură dată ca un câmp personalizat și faceți referire la el peste tot.

Crearea unui câmp personalizat

Creați un field.json în directorul blockstudio/fields/ al temei:

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

Folosirea câmpului personalizat

Faceți referire la el în orice bloc folosind "type": "custom/cta":

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

Câmpurile CTA sunt incluse direct în bloc. Accesați-le direct: $a['label'], $a['url'], $a['style'].

Câmpuri personalizate cu prefix folosind idStructure

Când folosiți același câmp personalizat de mai multe ori, adăugați idStructure pentru a pune prefixe ID-urilor:

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

Câmpurile primului CTA devin primary_label, primary_url, primary_style. Cele ale celui de-al doilea devin secondary_label etc.

Suprascrierea valorilor implicite

Personalizați anumite câmpuri când faceți referire la un câmp personalizat:

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

Suprascrierile se aplică peste definiția originală. Puteți modifica valorile implicite, etichetele, condițiile sau orice altă proprietate.

Tipare de randare

Verificarea valorilor goale

Majoritatea tipurilor de câmp returnează false când sunt goale. Verificați întotdeauna înainte de randare:

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

Pentru numere, 0 este o valoare validă. Folosiți o comparație strictă dacă trebuie să distingeți între “gol” și “zero”:

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

Selector cu returnFormat: both

Când aveți nevoie atât de valoare (pentru logică), cât și de etichetă (pentru afișare):

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

Atribute de date din câmpul de atribute

Tipul de câmp attributes le permite utilizatorilor să adauge atribute de date personalizate:

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>

Variabile CSS din valorile câmpurilor

Generați proprietăți personalizate CSS din câmpurile selectate:

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>

Acesta generează style="--text-color: #333; --font-size: 1rem;" (ID-urile câmpurilor sunt convertite în kebab-case). Folosiți variabilele în CSS:

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

Pașii următori