Pereiti prie turinio

Laukų šablonų receptų rinkinys

Blockstudio laukų sistema atskirai yra paprasta: pridėkite lauką prie blockstudio.attributes, o šablone pasiekite jį per $a. Tačiau realūs blokai retai turi tik vieną lauką. Juose būna susijusių nustatymų grupių, laukų, kurie rodomi arba paslepiami pagal kitų laukų reikšmes, kartotuvų su sudėtingomis eilučių struktūromis ir duomenų, kuriuos reikia užklausti ne blokų redaktoriuje.

Šiame vadove pateikiami praktiniai dažnai pasitaikančių laukų šablonų pavyzdžiai. Kiekviename pavyzdyje parodyta block.json konfigūracija ir atitinkamas šablono kodas. Nukopijuokite juos tiesiai į savo blokus ir pritaikykite pagal poreikį.

Sąlyginiai laukai

Dažniausias šablonas: laukų rodymas arba slėpimas pagal kito lauko reikšmę. Taip redaktorius lieka tvarkingas, nes pateikiamos tik aktualios parinktys.

Perjungikliu rodomos parinktys

CTA blokas, kuriame įjungus mygtuką parodomi papildomi nustatymai:

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

Mygtuko teksto ir nuorodos laukai rodomi tik tada, kai perjungiklis įjungtas. Šablone prieš atvaizduodami patikrinkite perjungiklio būseną:

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>

Pasirinkimo sąrašu perjungiami laukų rinkiniai

Hero blokas, kuriame pagal fono tipą nustatoma, kurie laukai rodomi:

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

Permatomumo virš fono laukas naudoja !=, kad būtų rodomas visiems fono tipams, išskyrus vientisą spalvą. Vienu metu rodomas tik vienas fono laukas. color laukas grąžina masyvą su spalvos reikšme value, name ir slug, todėl šablone nuskaitoma ['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>

Sąlygos ARBA

Rodykite lauką, kai teisinga bent viena iš kelių sąlygų. Kiekvienas vidinis masyvas yra sąlygų grupė, sujungta operatoriumi AND; išorinis masyvas jas sujungia operatoriumi OR:

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

Taip antraštės laukas rodomas, kai bgType yra “image” ARBA “video”.

Susietos sąlygos

Kelios sąlygos tame pačiame vidiniame masyve naudoja AND logiką:

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

Alternatyvaus teksto laukas rodomas tik tada, kai bgType yra “image” IR pasirinktas vaizdas.

Bendrosios sąlygos

Rodykite laukus pagal įrašo tipą, įrašo ID arba naudotojo vaidmenį, o ne pagal kitų laukų reikšmes:

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

Galimi bendrųjų sąlygų tipai: postType, postId, userRole, userId.

Tvarkingai suskirstyti nustatymai

Blokams sudėtingėjant, laukų suskirstymas į logines grupes padeda išlaikyti tvarkingą inspektorių.

Grupės vizualiam suskirstymui

Grupės inspektoriuje sukuria sutraukiamas sekcijas. Anoniminė grupė (be id) skirta tik vaizdiniam suskirstymui; jos laukai pasiekiami naudojant paprastus 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>

Laukai pasiekiami tiesiogiai: $a['title'], $a['style'], $a['accentColor']. Grupės turi įtakos tik inspektoriaus išdėstymui.

Pavadintos grupės su bs_get_group

Kai grupė turi id, jos vaikinių laukų ID papildomi prefiksu. Naudokite bs_get_group(), kad pašalintumėte prefiksą:

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

Be pagalbinės funkcijos laukai pasiekiami taip: $a['author_name'], $a['author_role'], $a['author_avatar']. Naudojant pagalbinę funkciją:

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>

Pavadintos grupės naudingos, kai keliuose grupėse yra tų pačių pavadinimų laukų (e.g., author_name ir company_name) arba kai norite perduoti grupę kaip visumą daliniam šablonui.

Tinklelio išdėstymas grupėse

Naudokite savybę style, kad grupės vaikinius elementus išdėstytumėte greta:

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

Du vienetų laukai inspektoriuje rodomi greta, o ne vienas po kitu. Tai tinka matmenų poroms, paraštės ir užpildo reikšmėms ar bet kuriems dviem konceptualiai susijusiems laukams.

Skirtukai pagrindinėms sekcijoms

Kai bloke yra daug nustatymų, skirtukai leidžia juos tvarkingiau suskirstyti nei ilgas grupių sąrašas:

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

Kiekvieno skirtuko laukai pasiekiami kaip aukščiausio lygio laukai: $a['title'], $a['image'], $a['layout']. Skirtukai tėra UI konteineris.

Kartotuvų šablonai

Kartotuvai leidžia naudotojams pridėti kelias laukų eilutes. Jie būtini sąrašams, tinkleliams, laiko juostoms ir bet kuriam komponentui su kintamu elementų skaičiumi.

Paprastas kartotuvas su apribojimais

Savybių sąrašas su 1–6 elementais:

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>

Pasirinktinės eilučių etiketės

Pagal numatytuosius nustatymus sutrauktose kartotuvo eilutėse rodoma bendro pobūdžio etiketė. Naudokite textMinimized, kad vietoj jos būtų rodoma lauko reikšmė:

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

Sutraukus eilutę, vietoj „Eilutė 1“ rodomas asmens vardas. Kai vardo laukas tuščias, naudojama fallback. Taip pat galite pridėti prefix ir suffix eilutes.

Sąlygos kartotuvuose

Kartotuvo laukai gali nurodyti kitus tos pačios eilutės laukus naudodami paprastus jų id (prefikso nereikia):

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

Išorinių laukų nurodymas kartotuvo viduje

Kai kartotuvo viduje esančiai sąlygai reikia patikrinti už kartotuvo ribų esantį lauką, pridėkite "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"
      }]]
    }
  ]
}

Be "context": "main" sąlyga ieškotų showDescriptions lauko kartotuvo eilutėje. Su juo sąlyga tikrina šakninio lygmens perjungiklį.

Skirtukai kartotuvuose

Kartotuvuose skirtukai nepasiekiami: kartotuvo eilutėje esantis tabs laukas redaktoriuje vietoj savo laukų rodo pranešimą, o PHPStan plėtinys apie tai praneša. Vietoj to eilutės laukus išdėstykite viename lygyje. Jei eilutės ilgos, pasirinktinis eilutės pavadinimas (textMinimized) padeda atpažinti sutrauktas eilutes, o eilutės sąlygos gali paslėpti laukus, reikalingus tik kai kurioms eilutėms, kaip parodyta ankstesniuose pavyzdžiuose.

Nustatykite kartotuvo "minimized": true, kad esamos eilutės būtų pradžioje sutrauktos. Naujai pridėtos eilutės iškart išskleidžiamos. Išskleistų eilučių išimtys šiame naršyklės lange įsimenamos net iš naujo įkėlus redaktorių; tai redagavimo nuostata, o ne išsaugomas įrašo turinys. Kartotuvai be minimized išlaiko esamą elgseną, kai eilutės pagal numatytuosius nustatymus yra išskleistos.

Medijos šablonai

Vienas vaizdas su atsarginiu variantu

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

Numatytoji returnFormat yra "object", kuri pateikia ID, title, alt, caption, description, href, url ir sizes. sizes saugo kiekvieno užregistruoto vaizdo dydžio URL (sizes['large']) ir jo matmenis (sizes['large-width'], sizes['large-height']). Visą sąrašą rasite skiltyje Atvaizdavimo atributai.

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

Išjungiamas vaizdas su perjungikliu

Savybė switch prideda akies piktogramą, kuria naudotojai gali išjungti lauką neištrindami jo reikšmės:

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

Naudotojas gali išjungti logotipą nepašalindamas įkelto failo. Vėl įjungus, grąžinamas tas pats failas.

Grąžinamo formato variantai

Nustatykite, ką grąžina failų laukas:

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"

Naudokite "id", kai reikia patiems iškviesti wp_get_attachment_image(). Paprastiems fono vaizdams naudokite "url". Visais kitais atvejais naudokite "object" (numatytoji reikšmė).

Kai naudojamas "returnFormat": "id", importuota eilutės nuoroda, pavyzdžiui, "buckshair-home", perduodama nepakeista. Redaktorius rodo atsarginę kortelę be miniatiūros, taip pat ir kartotuvo eilutėse. Atvėrus ar išsaugojus puslapį, skaliarinė nuoroda nepaverčiama į masyvą. Veikia ir mišrūs priedų ID bei eilučių nuorodų sąrašai; medijos bibliotekoje ieškoma tik teigiamų priedų ID.

Blockstudio nesusieja pasirinktinių eilučių nuorodų su priedais. Jei skirtingose svetainėse naudojate perkeliamus pavadinimus, susiekite jas savo atvaizdavimo filtre arba šablone. Medijos bibliotekoje pasirinkus pakaitinį failą, kaip įprasta, išsaugomas jo priedo ID.

Dinaminės parinktys

Užpildymas iš įrašų

Pasirinkimo laukas, kuriame išvardyti visi paskelbti puslapiai:

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

Laukas automatiškai užpildomas puslapių pavadinimais kaip etiketėmis ir įrašų ID kaip reikšmėmis. Naudokite returnFormat užpildymo konfigūracijoje, kad pritaikytumėte susiejimą:

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

Užpildymas taksonomijos terminais

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

Užpildymas iš PHP funkcijos

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

Statinės parinktys su dinaminiais papildymais

Sujunkite iš anksto aprašytas parinktis su dinaminėmis. Naudokite position, kad nustatytumėte užpildytų parinkčių vietą:

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

Pirmiausia rodomos statinės parinktys, o po jų – dinamiškai užpildyti puslapiai.

Duomenų saugojimas užklausoms

Pagal numatytuosius nustatymus laukų reikšmės saugomos blokų atributuose post_content. Jų negalima užklausti naudojant WP_Query. Kai reikia filtruoti arba rūšiuoti įrašus pagal lauko reikšmę, naudokite saugyklą.

Įrašo metaduomenys užklausiamiems laukams

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

Dabar galite užklausti išskirtinių įrašų:

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 raktai automatiškai užregistruojami naudojant show_in_rest, todėl jie taip pat pasiekiami REST API.

Dviguba saugykla

Saugojimas ir bloko atributuose, ir įrašo metaduomenyse. Bloko atributas užtikrina, kad reikšmė būtų pasiekiama šablonuose per $a, o įrašo metaduomenys leidžia ją užklausti:

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

Parinkčių saugykla bendrosioms reikšmėms

Visai svetainei skirtiems nustatymams, kurie visur turi būti vienodi, naudokite parinkčių saugyklą:

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

Reikšmė saugoma wp_options ir pasiekiama bet kur naudojant get_option('site_company_name'). Kai naudotojas redaguoja šį lauką bet kuriame bloko egzemplioriuje, reikšmė atnaujinama visur.

Pakartotinai naudojami laukų aprašai

Kai keli blokai turi tokią pačią laukų struktūrą, aprašykite ją vieną kartą kaip pasirinktinį lauką ir naudokite visur.

Pasirinktinio lauko kūrimas

Sukurkite field.json savo temos blockstudio/fields/ kataloge:

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

Pasirinktinio lauko naudojimas

Nurodykite jį bet kuriame bloke naudodami "type": "custom/cta":

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

CTA laukai įterpiami į bloką. Juos pasiekite tiesiogiai: $a['label'], $a['url'], $a['style'].

Prefiksuojami pasirinktiniai laukai su idStructure

Kai tą patį pasirinktinį lauką naudojate kelis kartus, pridėkite idStructure, kad ID būtų papildyti prefiksais:

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

Pirmojo CTA laukai tampa primary_label, primary_url, primary_style. Antrojo – secondary_label ir t. t.

Numatytųjų reikšmių keitimas

Tinkinkite konkrečius laukus, kai naudojate pasirinktinį lauką:

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

Pakeitimai pritaikomi virš pradinio aprašo. Galite keisti numatytąsias reikšmes, etiketes, sąlygas ar bet kurią kitą savybę.

Atvaizdavimo šablonai

Tuščios reikšmės tikrinimas

Dauguma laukų tipų, kai yra tušti, grąžina false. Prieš atvaizduodami visada patikrinkite:

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

Skaičiams 0 yra galiojanti reikšmė. Jei reikia atskirti „tuščią“ reikšmę nuo „nulio“, naudokite griežtą palyginimą:

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

Pasirinkimo laukas su returnFormat: both

Kai reikia ir reikšmės (logikai), ir etiketės (rodymui):

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

Duomenų atributai iš attributes lauko

Lauko tipas attributes leidžia naudotojams pridėti pasirinktinius duomenų atributus:

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

CSS kintamieji iš laukų reikšmių

Generuokite CSS pasirinktines savybes iš pasirinktų laukų:

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>

Tai išveda style="--text-color: #333; --font-size: 1rem;" (lauko ID pakeičiami į kebab-case). Naudokite kintamuosius savo CSS:

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

Tolesni žingsniai

  • Atributų registravimas: savybės id, type, label, default, help, position ir conditions.
  • Laukų tipų žinynas: automatiškai sugeneruotas kiekvieno lauko tipo visų savybių žinynas.
  • Sąlyginė logika: operatoriai, bendrosios sąlygos, pasirinktiniai sąlygų filtrai ir kartotuvo kontekstas.
  • Parinkčių užpildymas: užklausa, funkcija, pasirinktiniai ir iškvietimo režimai dinaminių parinkčių laukams.
  • Pasirinktiniai laukai: field.json, paieškos keliai, filtras blockstudio/fields ir išplėstiniai idStructure šablonai.
  • Atvaizdavimas: $a, $b, $c, tuščios reikšmės ir pagalbinės funkcijos.