Liigu sisu juurde

Saared

Plokisaared võimaldavad plokil kasutada tavalist Blockstudio renderdamisvoogu, teisaldades samal ajal päringupõhise väljundi algsest HTML vastusest välja.

See on kasulik, kui lehte tuleks agressiivselt vahemällu salvestada, kuid üks plokk sõltub endiselt praegusest külastajast, sessioonist, ostukorvist, õigustest või muust aktiivse päringu kontekstist.

Blockstudio plokid on endiselt dünaamilised WordPress plokid. Saared ei muuda neid eelkompileeritud staatiliseks HTML-iks. Selle asemel muudab Blockstudio seda, mida renderdatakse esimesel päringul:

  • hüdratiseeritud saared renderdavad oma tavalise vahemällu sobiva HTML-i ja saavad paigaldussündmuse
  • dünaamilised saared renderdavad esmalt vahemällu sobiva kohatäite, seejärel hangivad tegeliku fragmendi külastaja brauserist

Režiimid

Hüdratiseeritud saared

Kasuta hüdratiseeritud saart, kui serveri väljundit on ohutu vahemällu salvestada ja plokk vajab ainult esikülje paigaldussignaali.

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

Kogu ploki HTML sisaldub algses vastuses. Saare käituskeskkond ei tee selle jaoks REST päringut. See käivitab markeril sündmuse blockstudio:island:hydrate, et esikülje kood saaks käitumise lisada.

Dünaamilised saared

Kasuta dünaamilist saart, kui ploki tegelik väljund tuleb renderdada külastaja päringukontekstis.

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

Algne vastus sisaldab ainult kohatäidet. Brauser koondab kõik valmis dünaamilised saared üheks päringuks aadressile:

Text
POST /wp-json/blockstudio/v1/island/render

Lõpp-punkt renderdab ainult registreeritud Blockstudio plokke, mis on dünaamilised ja mille blockstudio.island.mode väärtuseks on määratud dynamic.

Konfiguratsioon

island väärtus võib olla lühivorm või objekt.

JSON
{
  "blockstudio": {
    "island": true
  }
}

true ja "hydrate" tähendavad mõlemad hüdratiseeritud režiimi. "dynamic" tähendab dünaamilist režiimi.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Omadus Tüüp Vaikeväärtus Kirjeldus
mode "hydrate" või "dynamic" "hydrate" Saare režiim.
tag string "div" Markeri ümbrisemärgend.
attributes string[] kõik ploki atribuudid Dünaamiliste fragmendipäringutega saadetavate atribuutide lubatud loend.
placeholder string tuvastatakse automaatselt Suhteline kohatäitja malli tee.
loading "eager" või "visible" "eager" Millal käituskeskkond peaks dünaamilise saare alla laadima.
event string määramata Aknasündmuse nimi, mis värskendab dünaamilist saart.
context boolean false Allkirjasta ja taasta päritud lehe postituse ID ja postituse tüüp dünaamiliste fragmentide jaoks.
cache boolean või object false Valikuline fragmentide vahemälupoliitika.

Lehe kontekst

Dünaamilised fragmendid renderdatakse tavaliselt lehe kestast sõltumatult. Kasuta lehe identiteeti, kui plokk loeb lehepõhiseid seadeid või seotud sisu:

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "context": true,
      "cache": { "ttl": 60, "per": "global" }
    }
  }
}

Marker sisaldab päritud lehe postId ja postType väärtusi asukohas data-bs-island-context. Mõlemad väärtused allkirjastatakse koos ploki nime ja lubatud atribuutidega teenindava saidi saladuse abil. Neid ei saa päringus muuta ega lisada ilma allkirja kehtetuks muutmata. Käituskeskkond saadab need olemasoleva pakitud fragmendipäringuga, sealhulgas nähtavuse ja sündmuste ajendatud värskenduste korral. See toimib ka koos bs_render_block(), bs_block() ja plokisiltidega.

Fragmentide renderdamise ajal viitavad $block['postId'], $block['postType'], get_the_ID() ja get_queried_object_id() sellele lehele. Pärast renderdamist taastatakse WordPress päringu- ja postituse globaalsed muutujad, ka siis, kui renderdamisel tekib erand. See on päritud leht, mitte element päringutsükli sees. See ei taasesita suvalisi URL parameetreid ega taasta algset päringut URL. Kui vajad HTML lehe kanoonilist URL väärtust, kasuta get_permalink($block['postId']). Arhiivide ja päringuga postituseta renderduste puhul lehe identiteeti ei saadeta.

Enne fragmendi vahemälust otsimist kontrollib lõpp-punkt, kas leht on endiselt olemas, selle postituse tüüp vastab allkirjastatule ning praegune külastaja saab lehte lugeda. Kehtiv allkiri ei möödu privaatse postituse ega paroolikaitsest, saare sobivusest, atribuutide lubatud loenditest ega sinu ploki enda õiguskontrollidest. Kui lehe identiteet on olemas, kuulub see alati fragmendi vahemälu võtme hulka, seega ei jaga eri lehtede sama plokk ja atribuudid kunagi ühte fragmenti. Kui väljund sõltub ka külastajast, kasuta per: "user" või ära kasuta fragmendi vahemälu.

Kui context puudub või on false, jäävad olemasolevad markerid ja kontekstivaba käitumine muutumatuks. Ära lisa avalikku markerisse konfidentsiaalseid andmeid.

Dünaamilised kohatäited

Dünaamilised saared peaksid renderdama kohatäite, mida on ohutu jagatud kogu lehe vahemälus kasutada. Ära lisa kohatäiteharusse külastajapõhiseid andmeid.

Blockstudio otsib kohatäiteid järgmises järjekorras:

  1. selgesõnaline island.placeholder tee
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. tavaline mall kohatäite lippudega
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Kui kohatäitefaili pole, kasuta tavalises mallis mallilippe:

PHP
<?php if ( $isIslandPlaceholder ) : ?>
  <div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
  <div class="cart-count">
    <?php echo esc_html( acme_cart_count() ); ?>
  </div>
<?php endif; ?>

Samad väärtused on saadaval mallides PHP, Twig ja Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase on "normal", "hydrate", "placeholder" või "fragment".

Käituskeskkonna käitumine

Blockstudio lisab saare käituskeskkonna ainult siis, kui renderdatud leht sisaldab saare markerit. Saarteta lehtedel ei laadita täiendavat saare JavaScript-i.

Dünaamiliste saarte puhul käituskeskkond:

  1. kogub kõik valmis markerid
  2. eemaldab duplikaadid identsete plokinime, atribuutide ja signatuuride paaride seast
  3. saadab ühe koondatud REST päringu
  4. asendab iga kohatäite tagastatud fragmendiga
  5. käivitab blockstudio:island:rendered
  6. käivitab blockstudio:island:hydrate

loading: "eager" saared renderdatakse kohe, kui käituskeskkond käivitub. loading: "visible" saared ootavad IntersectionObserver-i. Kui mitu nähtavat saart jõuavad korraga vaateaknasse, koondatakse need üheks päringuks.

event värskendab saart, kui käivitub nimetatud aknasündmus:

JavaScript
window.dispatchEvent(new Event('cart:updated'));

Tõrgete korral jääb kohatäide paigale ja käivitatakse blockstudio:island:error.

Fragmendi lõpp-punkt

Saare lõpp-punkt on avalik, kuid see ei ole üldotstarbeline ploki renderdamise API.

Iga marker sisaldab:

  • ploki nime
  • lubatud loendis olevaid atribuute
  • serveris loodud signatuuri

Lõpp-punkt renderdab ainult järgmistel tingimustel:

  • plokk on registreeritud
  • plokk on dünaamiline WordPress plokk
  • plokk on märgitud dünaamiliseks Blockstudio saareks
  • saabuvad atribuudid vastavad ploki skeemile ja saare lubatud loendile
  • signatuur vastab normaliseeritud ploki nimele ja atribuutidele

Signatuurid luuakse renderdamise ajal teenindaval WordPress saidil, kasutades selle saidi sooli ja saare koormust. Neid ei ekspordita ega lisata teemale.

Lõpp-punkti vastused märgitakse vahemällu salvestamiseks sobimatuks. Kui soovid fragmendi vahemällu salvestamist, kasuta island.cache-i.

Fragmentide vahemällu salvestamine

Dünaamilisi fragmente vaikimisi vahemällu ei salvestata.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true kasutab lühiajalist globaalset vahemälu. Täpsemaks juhtimiseks kasuta objektivormi:

JSON
{
  "cache": {
    "ttl": 120,
    "per": "user"
  }
}

per: "global" jagab sama ploki, atribuutide ja lubatud lehekonteksti korral üht vahemällu salvestatud fragmenti. per: "user" muudab vahemälu praeguse WordPress kasutaja ID järgi.

Programmiliselt renderdamine

Saared toimivad kõikjal, kus renderdatakse Blockstudio plokke:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

echo bs_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

Need toimivad ka plokisiltide kaudu:

HTML
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />

Esialgne väljund sisaldab endiselt saare markerit ja kohatäidet ning käituskeskkond lisatakse siis, kui renderdatud vastus sisaldab seda markerit.

PHP API

PHP
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);

marker() valideerib ploki metaandmed. Dünaamilisi markereid luuakse ainult registreeritud dünaamiliste Blockstudio plokkide jaoks, mille island.mode väärtuseks on määratud dynamic.

Hook’id

Tuvastamine ja märgistus:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

Lõpp-punkt ja renderdamine:

PHP
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment

blockstudio/islands/max_per_request muudab dünaamiliste saarte maksimaalset arvu, mida üks koondatud lõpp-punkti päring aktsepteerib. Vaikeväärtus on 50.

Käituskeskkonna seadistus:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Signatuurid:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

Elutsükli toimingud:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Millal saari mitte kasutada

Ära kasuta dünaamilist saart SEO-kriitilise sisu jaoks. Dünaamiliste saarte fragmendid puuduvad algsest HTML-ist ja neid pole mõeldud indekseerimiseks.

Kasuta tavalist renderdamist või hüdratiseeritud saart, kui sisu on vahemällu salvestamiseks sobiv ja peaks olema roomajatele nähtav. Kasuta dünaamilist saart ainult sisu jaoks, mis võib saabuda pärast lehe põhiosa, näiteks konto UI, ostukorvi oleku, isikupärastatud soovituste või õigustega piiratud juhtelementide puhul.