Przejdź do treści

Zbiór przepisów na wzorce pól

System pól Blockstudio jest prosty w izolacji: dodaj pole do blockstudio.attributes, a w szablonie uzyskaj do niego dostęp przez $a. Jednak rzeczywiste bloki rzadko mają tylko jedno pole. Zawierają grupy powiązanych ustawień, pola wyświetlane lub ukrywane w zależności od innych pól, repeatery o złożonej strukturze wierszy oraz dane, które muszą być dostępne w zapytaniach poza edytorem bloków.

Ten przewodnik zawiera praktyczne przepisy na popularne wzorce pól. Każdy przepis przedstawia konfigurację block.json i odpowiadający jej kod szablonu. Skopiuj je bezpośrednio do swoich bloków i dostosuj w razie potrzeby.

Pola warunkowe

Najpopularniejszy wzorzec: wyświetlanie lub ukrywanie pól zależnie od wartości innego pola. Dzięki temu edytor pozostaje przejrzysty i pokazuje tylko odpowiednie opcje.

Przełącznik ujawniający opcje

Blok CTA, w którym po włączeniu przycisku przez użytkownika pojawiają się dodatkowe ustawienia:

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

Pola tekstu przycisku i odnośnika pojawiają się tylko wtedy, gdy przełącznik jest włączony. W szablonie sprawdź przełącznik przed renderowaniem:

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>

Wybór zestawów pól

Blok hero, w którym typ tła określa wyświetlane pola:

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 przezroczystości nakładki używa !=, aby pojawiać się dla każdego typu tła poza jednolitym kolorem. W danej chwili wyświetlane jest tylko jedno pole tła. Pole color zwraca tablicę zawierającą value, name i slug koloru, więc szablon odczytuje ['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>

Warunki OR

Wyświetl pole, gdy spełniony jest dowolny z kilku warunków. Każda tablica wewnętrzna to grupa AND, a tablica zewnętrzna łączy je operatorem OR:

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

To wyświetla pole podpisu, gdy bgType ma wartość „image” LUB „video”.

Łańcuch warunków

Kilka warunków w tej samej tablicy wewnętrznej łączy logika AND:

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

Pole tekstu alternatywnego pojawia się tylko wtedy, gdy bgType ma wartość „image” ORAZ wybrano obraz.

Warunki globalne

Wyświetlaj pola na podstawie typu wpisu, identyfikatora wpisu lub roli użytkownika zamiast wartości innych pól:

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

Dostępne typy warunków globalnych: postType, postId, userRole, userId.

Uporządkowane ustawienia

W miarę jak bloki stają się bardziej złożone, porządkowanie pól w logiczne grupy ułatwia obsługę panelu inspektora.

Grupy porządkujące wizualnie

Grupy tworzą zwijane sekcje w panelu inspektora. Grupa anonimowa (bez id) służy wyłącznie do organizacji wizualnej; jej pola są dostępne pod własnymi identyfikatorami:

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>

Dostęp do pól uzyskuje się bezpośrednio: $a['title'], $a['style'], $a['accentColor']. Grupy wpływają tylko na układ panelu inspektora.

Nazwane grupy z bs_get_group

Gdy grupa ma id, do identyfikatorów jej pól podrzędnych dodawany jest prefiks. Użyj bs_get_group(), aby go usunąć:

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 pomocnika pola są dostępne jako $a['author_name'], $a['author_role'], $a['author_avatar']. Z pomocnikiem:

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>

Nazwane grupy są przydatne, gdy te same nazwy pól występują w wielu grupach (e.g, author_name i company_name) lub gdy chcesz przekazać grupę jako całość do szablonu partial.

Układ siatki w grupach

Użyj właściwości style, aby ułożyć pola podrzędne grupy obok siebie:

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

Dwa pola jednostek są wyświetlane obok siebie w panelu inspektora zamiast jedno pod drugim. Sprawdza się to przy parach wymiarów, wartościach marginesu i dopełnienia lub dowolnych dwóch polach, które są ze sobą powiązane.

Karty dla głównych sekcji

Gdy blok ma wiele ustawień, karty porządkują je lepiej niż długa lista grup:

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

Pola każdej karty są dostępne jak pola najwyższego poziomu: $a['title'], $a['image'], $a['layout']. Karty służą wyłącznie jako kontener UI.

Wzorce repeaterów

Repeatery pozwalają użytkownikom dodawać wiele wierszy pól. Są niezbędne w przypadku list, siatek, osi czasu i dowolnych komponentów o zmiennej liczbie elementów.

Podstawowy repeater z ograniczeniami

Lista funkcji zawierająca od 1 do 6 elementów:

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>

Własne etykiety wierszy

Domyślnie zminimalizowane wiersze repeatera mają ogólną etykietę. Użyj textMinimized, aby zamiast niej wyświetlić wartość pola:

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 zwinięciu wiersz pokazuje imię i nazwisko osoby zamiast „Wiersz 1”. Gdy pole imienia i nazwiska jest puste, używane jest fallback. Możesz też dodać ciągi prefix i suffix.

Warunki w repeaterach

Pola w repeaterze mogą odwoływać się do innych pól w tym samym wierszu za pomocą własnego id (nie jest potrzebny prefiks):

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

Odwoływanie się do pól zewnętrznych w repeaterze

Gdy warunek w repeaterze musi sprawdzić pole spoza niego, dodaj "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" warunek szukałby pola showDescriptions w wierszu repeatera. Z nim sprawdza przełącznik na poziomie głównym.

Karty wewnątrz repeaterów

Karty nie są dostępne wewnątrz repeaterów: pole tabs wiersza repeatera wyświetla w edytorze komunikat zamiast swoich pól, a rozszerzenie PHPStan to zgłasza. Zamiast tego zachowaj płaską strukturę pól w wierszu. W przypadku długich wierszy własna etykieta wiersza (textMinimized) ułatwia odczytanie zwiniętych wierszy, a warunki wewnątrz wiersza mogą ukrywać pola potrzebne tylko w niektórych wierszach, jak pokazano we wcześniejszych przykładach.

Ustaw "minimized": true w repeaterze, aby istniejące wiersze były początkowo zwinięte. Nowo dodane wiersze otwierają się od razu. Wyjątki pozostawione w stanie rozwiniętym są zapamiętywane w tej przeglądarce po ponownym załadowaniu edytora; to preferencja edycji, a nie zapisana treść wpisu. Repeatery bez minimized zachowują dotychczasowe zachowanie, w którym wiersze są domyślnie rozwinięte.

Wzorce multimedialne

Pojedynczy obraz z wartością zastępczą

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

Domyślny returnFormat to "object", który udostępnia ID, title, alt, caption, description, href, url i sizes. sizes przechowuje URL wszystkich zarejestrowanych rozmiarów obrazów (sizes['large']) wraz z ich wymiarami (sizes['large-width'], sizes['large-height']). Pełną listę znajdziesz w sekcji Atrybuty renderowania.

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

Obraz, który można wyłączyć przełącznikiem

Właściwość switch dodaje ikonę oka, która pozwala użytkownikom wyłączyć pole bez usuwania jego wartości:

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

Użytkownik może wyłączyć logo bez usuwania przesłanego pliku. Po ponownym włączeniu wraca ten sam plik.

Warianty formatu zwracanej wartości

Określ, co zwraca pole plików:

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"

Użyj "id", gdy musisz samodzielnie wywołać wp_get_attachment_image(). Użyj "url" w przypadku prostych obrazów tła. We wszystkich pozostałych przypadkach użyj "object" (wartości domyślnej).

Przy użyciu "returnFormat": "id" zaimportowane odwołanie tekstowe, takie jak "buckshair-home", jest przekazywane bez zmian. Edytor wyświetla zastępczą kartę bez miniatury, również w wierszach repeatera. Otwarcie lub zapisanie strony nie konwertuje skalarnego odwołania na tablicę. Działają też mieszane listy identyfikatorów załączników i odwołań tekstowych; w bibliotece mediów wyszukiwane są tylko dodatnie identyfikatory załączników.

Blockstudio nie zamienia własnych odwołań tekstowych na załączniki. Jeśli używasz przenośnych nazw w różnych witrynach, rozwiązuj je we własnym filtrze renderowania lub szablonie. Wybór zamiennika w bibliotece mediów zapisuje jego identyfikator załącznika jak zwykle.

Opcje dynamiczne

Wypełnianie wpisami

Pole wyboru zawierające wszystkie opublikowane strony:

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 jest automatycznie wypełniane tytułami stron jako etykietami i identyfikatorami wpisów jako wartościami. Użyj returnFormat w konfiguracji wypełniania, aby dostosować mapowanie:

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

Wypełnianie terminami taksonomii

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

Wypełnianie za pomocą funkcji PHP

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

Opcje statyczne z dodatkowymi opcjami dynamicznymi

Połącz opcje wpisane na stałe z dynamicznymi. Użyj position, aby określić miejsce wyświetlania opcji dynamicznych:

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

Najpierw wyświetlane są opcje statyczne, a po nich dynamicznie pobrane strony.

Przechowywanie danych na potrzeby zapytań

Domyślnie wartości pól są przechowywane w atrybutach bloków w post_content. Nie można ich wyszukiwać za pomocą WP_Query. Jeśli chcesz filtrować lub sortować wpisy według wartości pola, użyj przechowywania danych.

Metadane wpisu dla pól dostępnych w zapytaniach

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 możesz wyszukiwać polecane wpisy:

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

Klucze meta są automatycznie rejestrowane za pomocą show_in_rest, więc są też dostępne w REST API.

Podwójne przechowywanie

Przechowuj dane zarówno w atrybutach bloku, jak i w metadanych wpisu. Atrybut bloku udostępnia wartość w szablonach przez $a, a metadane wpisu pozwalają używać jej w zapytaniach:

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

Przechowywanie w opcjach dla wartości globalnych

W przypadku ustawień globalnych, które mają być takie same w całej witrynie, użyj przechowywania w opcjach:

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

Wartość jest przechowywana w wp_options i dostępna w dowolnym miejscu za pomocą get_option('site_company_name'). Gdy użytkownik edytuje to pole w dowolnej instancji bloku, wartość aktualizuje się globalnie.

Definicje pól wielokrotnego użytku

Gdy wiele bloków ma tę samą strukturę pól, zdefiniuj je raz jako pole niestandardowe i używaj go wszędzie.

Tworzenie pola niestandardowego

Utwórz field.json w katalogu blockstudio/fields/ motywu:

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

Korzystanie z pola niestandardowego

Odwołaj się do niego w dowolnym bloku za pomocą "type": "custom/cta":

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

Pola CTA są wstawiane bezpośrednio do bloku. Uzyskaj do nich dostęp bezpośrednio: $a['label'], $a['url'], $a['style'].

Pola niestandardowe z prefiksem za pomocą idStructure

Gdy używasz tego samego pola niestandardowego wielokrotnie, dodaj idStructure, aby dodać prefiks do identyfikatorów:

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

Pola pierwszego CTA otrzymują identyfikatory primary_label, primary_url, primary_style. Drugie otrzymuje secondary_label itd.

Zastępowanie wartości domyślnych

Dostosuj wybrane pola podczas korzystania z pola niestandardowego:

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

Nadpisania są łączone z oryginalną definicją. Możesz zmienić wartości domyślne, etykiety, warunki lub dowolną inną właściwość.

Wzorce renderowania

Sprawdzanie pustej wartości

Większość typów pól zwraca false, gdy jest pusta. Zawsze sprawdź wartość przed renderowaniem:

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

Dla liczb 0 jest prawidłową wartością. Użyj ścisłego porównania, jeśli chcesz odróżnić wartość „pustą” od „zera”:

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

Lista wyboru z returnFormat: both

Gdy potrzebujesz zarówno wartości (do logiki), jak i etykiety (do wyświetlenia):

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

Atrybuty danych z pola attributes

Typ pola attributes pozwala użytkownikom dodawać niestandardowe atrybuty danych:

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>

Zmienne CSS z wartości pól

Generuj niestandardowe właściwości CSS z wybranych pól:

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 generuje style="--text-color: #333; --font-size: 1rem;" (identyfikatory pól są konwertowane na format kebab-case). Użyj tych zmiennych w swoim CSS:

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

Następne kroki