Liigu sisu juurde

Väljade mustrite käsiraamat

Blockstudio väljasüsteem on eraldi võetuna lihtne: lisa väli elementi blockstudio.attributes ja kasuta seda mallis $a kaudu. Päris plokkides on aga harva ainult üks väli. Neis on seotud sätete rühmad, väljad, mis ilmuvad või peidetakse teiste väljade alusel, keerukate reastruktuuridega kordajad ning andmed, mida tuleb pärida ka väljaspool plokiredaktorit.

Selles juhendis on praktilised juhised levinud väljamustrite jaoks. Iga juhis näitab block.json konfiguratsiooni ja sellele vastavat mallikoodi. Kopeeri need otse oma plokkidesse ja kohanda vajaduse järgi.

Tingimuslikud väljad

Kõige levinum muster: väljade kuvamine või peitmine teise välja väärtuse alusel. Nii on redaktor selgem, sest näha on ainult asjakohased valikud.

Lüliti abil valikute kuvamine

CTA-plokk, kus lisasätted ilmuvad, kui kasutaja nupu sisse lülitab:

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

Nupu teksti ja lingi väljad ilmuvad ainult siis, kui lüliti on sees. Mallis kontrolli enne kuvamist lüliti olekut:

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>

Valik väljade komplekti vahetamiseks

Kaanepildi plokk, kus taustatüüp määrab kuvatavad väljad:

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

Ülekatte läbipaistmatuse väli kasutab elementi != ja ilmub kõigi taustatüüpide puhul peale ühevärvilise. Korraga kuvatakse ainult üks taustaväli. Väli color tagastab massiivi, mis sisaldab värvi atribuute value, name ja slug, seega kasutab mall väärtust ['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>

VÕI-tingimused

Kuva väli, kui mitu tingimust on täidetud. Iga sisemine massiiv on JA-rühm; välimine massiiv ühendab need VÕI-ga:

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

See kuvab pealdise välja, kui bgType on “image” VÕI “video”.

Aheldatud tingimused

Mitu tingimust samas sisemises massiivis kasutavad JA-loogikat:

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

Alt-teksti väli ilmub ainult siis, kui bgType on “image” JA pilt on valitud.

Üldtingimused

Kuva väljad postituse tüübi, postituse ID või kasutaja rolli alusel, mitte muude väljade väärtuste põhjal:

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

Saadaolevad üldtingimuste tüübid: postType, postId, userRole, userId.

Korrastatud sätted

Plokkide keerukamaks muutudes aitavad väljade rühmitamine loogilistesse jaotistesse inspektori ülevaatlikuna hoida.

Rühmad visuaalseks korrastamiseks

Rühmad loovad inspektoris kokkupandavaid jaotisi. Nimetu rühm (ilma id-ta) on üksnes visuaalne; selle väljadele pääseb ligi nende lihtsate ID-de kaudu:

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>

Väljadele pääseb otse ligi: $a['title'], $a['style'], $a['accentColor']. Rühmad mõjutavad ainult inspektori paigutust.

Nimega rühmad ja bs_get_group

Kui rühmal on id, lisatakse selle alamväljade ID-dele eesliide. Eesliite eemaldamiseks kasuta elementi 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 }
  ]
}

Abifunktsioonita pääseb väljadele ligi nii: $a['author_name'], $a['author_role'], $a['author_avatar']. Abifunktsiooniga:

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>

Nimega rühmad on kasulikud, kui sama nimega väljad esinevad mitmes rühmas (e.g, author_name ja company_name) või kui soovid anda rühma tervikuna osamallile edasi.

Ruudustikpaigutus rühmades

Kasuta atribuuti style, et paigutada rühma alamväljad kõrvuti:

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

Kaks ühikuvälja kuvatakse inspektoris üksteise kõrval, mitte üksteise all. See sobib hästi mõõtmete paaridele, veerise- ja täidiseväärtustele ning kõigile kahele väljale, mis kuuluvad kokku.

Vahelehed suuremate jaotiste jaoks

Kui plokil on palju sätteid, muudavad vahelehed need selgemaks kui pikk loend rühmi:

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

Iga vahekaardi väljadele pääseb ligi nagu ülataseme väljadele: $a['title'], $a['image'], $a['layout']. Vahelehed on pelgalt UI konteiner.

Kordajate mustrid

Kordajad võimaldavad kasutajatel lisada mitu väljade rida. Need on vajalikud loendite, ruudustike, ajajoonte ja kõigi muutuva elementide arvuga komponentide jaoks.

Piirangutega põhikordaja

Omaduste loend, milles on 1 kuni 6 üksust:

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>

Kohandatud reasildid

Vaikimisi kuvatakse minimeeritud kordaja ridadel üldine silt. Selle asemel saad kuvada välja väärtuse atribuudiga textMinimized:

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

Rea kokkupanemisel kuvatakse „1. rea” asemel inimese nimi. Kui nimeväli on tühi, kasutatakse elementi fallback. Samuti saad lisada stringid prefix ja suffix.

Tingimused kordajates

Kordaja sees olevad väljad saavad viidata sama rea muudele väljadele nende lihtsate id-de kaudu (eesliidet pole vaja):

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

Kordaja seest välimistele väljadele viitamine

Kui kordaja sees olev tingimus peab kontrollima kordajast väljaspool asuvat välja, lisa "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"
      }]]
    }
  ]
}

Ilma "context": "main"-ta otsiks tingimus kordaja rea seest välja showDescriptions. Selle abil kontrollib tingimus juurtaseme lülitit.

Vahelehed kordajate sees

Kordajate sees pole vahelehed saadaval: kordaja reas olev väli tabs kuvab redaktoris väljade asemel teavituse ja laiendus PHPStan annab sellest teada. Hoidke rea väljad selle asemel tasapinnalisena. Pikkade ridade puhul muudab kohandatud rea silt (textMinimized) ahendatud read loetavaks. Rea sees olevate tingimustega saab peita välju, mida vajavad vaid mõned read, nagu ülaltoodud näidetes.

Määrake kordajal "minimized": true, et olemasolevad read oleksid alguses ahendatud. Äsja lisatud read avanevad kohe. Laiendatud erandid jäetakse selles brauseris meelde ka redaktori uuesti laadimisel; see on redigeerimiseelistus, mitte salvestatud postituse sisu. Kordajad, millel puudub minimized, säilitavad senise käitumise, mille korral read on vaikimisi laiendatud.

Meediamustrid

Üksik pilt koos varupildiga

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

Vaikimisi returnFormat on "object", mis pakub ID, title, alt, caption, description, href, url ja sizes. sizes sisaldab kõigi registreeritud pildisuuruste (sizes['large']) URL koos mõõtmetega (sizes['large-width'], sizes['large-height']). Täieliku loendi leiate jaotisest Renderdamise atribuudid.

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

Lülitiga väljalülitatav pilt

Atribuut switch lisab silmaikooni, mille abil saavad kasutajad välja väärtust kustutamata keelata:

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

Kasutaja saab logo välja lülitada, faili eemaldamata. Uuesti sisselülitamisel ilmub sama fail tagasi.

Tagastusvormingute variandid

Määra, mida failiväli tagastab:

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"

Kasuta väärtust "id", kui pead ise välja kutsuma funktsiooni wp_get_attachment_image(). Lihtsate taustapiltide jaoks kasuta väärtust "url". Kõige muu jaoks kasuta väärtust "object" (vaikimisi).

Valikuga "returnFormat": "id" edastatakse imporditud stringviide, näiteks "buckshair-home", muutmata kujul. Redaktoris kuvatakse ilma pisipildita varukaart, ka kordaja ridades. Lehe avamine või salvestamine ei teisenda skalaarset viidet massiiviks. Toimivad ka loendid, kus on segamini manuse ID-d ja stringviited; meediakogust otsitakse ainult positiivseid manuse ID-sid.

Blockstudio ei seo kohandatud stringviiteid manustega. Saitide vahel kasutatavate porditavate nimede korral lahendage need ise renderdusfiltris või mallis. Meediakogust asenduse valimisel salvestatakse tavapäraselt selle manuse ID.

Dünaamilised valikud

Postituste põhjal täitmine

Valikväli, kus kuvatakse kõik avaldatud leheküljed:

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

Väli täidetakse automaatselt lehekülgede pealkirjadega siltide ja postituste ID-dega väärtustena. Vastenduse kohandamiseks kasuta täitmise konfiguratsioonis elementi returnFormat:

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

Taksonoomiaterminite põhjal täitmine

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

Funktsiooni PHP põhjal täitmine

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

Staatiliste valikute täiendamine täidetud valikutega

Ühenda kõvakodeeritud valikud dünaamiliste valikutega. Määra atribuudiga position, kus täidetud valikud kuvatakse:

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

Staatilised valikud kuvatakse esimesena ja seejärel dünaamiliselt lisatud leheküljed.

Andmete salvestamine päringute jaoks

Vaikimisi asuvad väljaväärtused plokiatribuutides post_content. Neid ei saa pärida WP_Query abil. Kui pead postitusi väljaväärtuse põhjal filtreerima või sortima, kasuta salvestust.

Päringutega loetavate väljade postituse metaandmed

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

Nüüd saad pärida esiletõstetud postitusi:

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 võtmed registreeritakse automaatselt funktsiooniga show_in_rest, seega on need saadaval ka moodulis API REST.

Kahekordne salvestus

Salvesta nii plokiatribuutidesse kui ka postituse metaandmetesse. Plokiatribuut hoiab väärtuse mallides kättesaadavana funktsiooni $a kaudu, postituse metaandmed aga muudavad selle päringutega loetavaks:

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

Globaalsete väärtuste salvestamine suvanditesse

Saidipõhiste sätete jaoks, mis peaksid igal pool samad olema, kasuta suvandite salvestust:

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

Väärtus salvestatakse asukohta wp_options ja sellele pääseb igalt poolt ligi funktsiooniga get_option('site_company_name'). Kui kasutaja muudab seda välja suvalises ploki eksemplaris, värskendatakse väärtust kõikjal.

Korduvkasutatavad väljadefinitsioonid

Kui mitu plokki kasutavad sama väljastruktuuri, määra see üks kord kohandatud väljana ja viita sellele kõikjal.

Kohandatud välja loomine

Loo teemakausta kataloogis blockstudio/fields/ fail field.json:

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

Kohandatud välja kasutamine

Viita sellele mis tahes plokis elemendiga "type": "custom/cta":

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

CTA väljad lisatakse plokile otse. Pääse neile ligi: $a['label'], $a['url'], $a['style'].

Eesliitega kohandatud väljad ja idStructure

Kui kasutad sama kohandatud välja mitu korda, lisa ID-dele eesliide atribuudiga idStructure:

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

Esimese CTA väljad on nüüd primary_label, primary_url, primary_style. Teise CTA väljad algavad secondary_label-ga jne.

Vaikeväärtuste ülekirjutamine

Kohanda kohandatud välja kasutamisel konkreetseid välju:

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

Ülekirjutused liidetakse algse definitsiooni peale. Saad muuta vaikeväärtusi, silte, tingimusi või muid atribuute.

Renderdamismustrid

Tühjade väärtuste kontrollimine

Enamik väljatüüpe tagastab tühjana false. Kontrolli enne renderdamist alati väärtust:

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

Arvuväljade puhul on 0 kehtiv väärtus. Kui pead eristama tühja väärtust nullist, kasuta ranget võrdlust:

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

Valik ja returnFormat: both

Kui vajad nii väärtust (loogika jaoks) kui ka silti (kuvamiseks):

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

Andmeatribuudid väljatüübi attributes kaudu

Väljatüüp attributes võimaldab kasutajatel lisada kohandatud andmeatribuute:

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 muutujad väljaväärtuste põhjal

Loo valitud väljadest dünaamilised kohandatud omadused CSS:

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>

See väljastab style="--text-color: #333; --font-size: 1rem;" (väljade ID-d teisendatakse sidekriipsudega väiketähtedeks). Kasuta muutujaid oma CSS-is:

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

Järgmised sammud