Preskoči na vsebino

Otočki

Otočki blokov ohranijo običajni upodabljalni cevovod Blockstudio, medtem ko izhod, specifičen za zahtevo, premaknejo iz začetnega odgovora HTML.

To je uporabno, kadar mora biti stran intenzivno predpomnjena, vendar je en blok še vedno odvisen od trenutnega obiskovalca, seje, košarice, dovoljenj ali drugega konteksta sprotne zahteve.

Bloki Blockstudio so še vedno dinamični bloki WordPress. Otočki jih ne pretvorijo v vnaprej prevedene statične HTML. Namesto tega Blockstudio spremeni to, kar se izriše ob prvi zahtevi:

  • hidrirani otočki izrišejo običajni izhod HTML, varen za predpomnjenje, in prejmejo dogodek priklopa
  • dinamični otočki najprej izrišejo nadomestni element, varen za predpomnjenje, nato pa iz brskalnika obiskovalca pridobijo pravi fragment

Načini

Hidrirani otočki

Hidrirani otoček uporabite, kadar je strežniški izhod varen za predpomnjenje in blok potrebuje le signal za priklop v sprednjem delu.

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

Celoten blok HTML je prisoten v začetnem odgovoru. Izvajalno okolje otočkov zanj ne pošlje zahteve REST. Na označevalniku sproži blockstudio:island:hydrate, da lahko koda sprednjega dela doda vedenje.

Dinamični otočki

Dinamični otoček uporabite, kadar je treba pravi izhod bloka izrisati v kontekstu zahteve obiskovalca.

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

Začetni odgovor vsebuje samo nadomestni element. Brskalnik združi vse pripravljene dinamične otočke v eno zahtevo na:

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

Končna točka izriše samo registrirane bloke Blockstudio, ki so dinamični in imajo blockstudio.island.mode nastavljeno na dynamic.

Konfiguracija

Vrednost island je lahko okrajšana oblika ali objekt.

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

true in "hydrate" pomenita hidrirano. "dynamic" pomeni dinamično.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Lastnost Vrsta Privzeto Opis
mode "hydrate" ali "dynamic" "hydrate" Način otoka.
tag string "div" Ovojna oznaka označevalnika.
attributes string[] vsi atributi bloka Seznam dovoljenih atributov, poslanih zahtevam za dinamične fragmente.
placeholder string samodejno zaznano Relativna pot do predloge nadomestnega mesta.
loading "eager" ali "visible" "eager" Kdaj naj izvajalno okolje pridobi dinamični otok.
event string ni nastavljeno Ime dogodka okna, ki osveži dinamični otok.
context boolean false Podpiše in obnovi ID objave ter vrsto objave poizvedene strani za dinamične fragmente.
cache boolean ali object false Izbirna politika predpomnjenja fragmentov.

Kontekst strani

Dinamični fragmenti se običajno upodabljajo neodvisno od ogrodja strani. Če vaš blok bere nastavitve, značilne za stran, ali povezano vsebino, omogočite uporabo njene identitete:

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

Označevalnik vključuje postId in postType poizvedene strani v data-bs-island-context. Obe vrednosti sta podpisani z imenom bloka in dovoljenimi atributi s skrivnostjo spletnega mesta, ki streže vsebino. Brez neveljavnosti podpisa ju ni mogoče spremeniti ali dodati zahtevi. Izvajalno okolje ju pošlje skupaj z obstoječo paketno zahtevo za fragmente, tudi pri vidnih osvežitvah in osvežitvah na podlagi dogodkov. To deluje tudi z bs_render_block(), bs_block() in oznakami blokov.

Med upodabljanjem fragmenta se $block['postId'], $block['postType'], get_the_ID() in get_queried_object_id() nanašajo na to stran. Po upodabljanju se obnovijo poizvedba WordPress in globalne spremenljivke objave, tudi če med upodabljanjem pride do izjeme. To je poizvedena stran, ne element znotraj zanke poizvedbe. Ne ponovi poljubnih parametrov URL in ne obnovi izvirnega URL zahteve. Če potrebujete kanonični URL strani HTML, uporabite get_permalink($block['postId']). Arhivi in upodabljanja brez poizvedene objave ne pošljejo identitete strani.

Končna točka preveri, ali stran še obstaja, ali ima podpisano vrsto objave in ali jo trenutni obiskovalec lahko bere, preden preveri predpomnilnik fragmentov. Veljaven podpis ne obide zaščite zasebnih objav ali z geslom zaščitenih objav, upravičenosti otoka, seznamov dovoljenih atributov ali lastnih preverjanj dovoljenj vašega bloka. Ko je identiteta strani na voljo, je vedno del ključa predpomnilnika fragmentov, zato isti blok z enakimi atributi na različnih straneh nikoli ne deli fragmenta. Če je izhod odvisen tudi od obiskovalca, uporabite per: "user" ali onemogočite predpomnjenje fragmentov.

Če je context izpuščen ali je false, obstoječi označevalniki in vedenje brez konteksta ostanejo nespremenjeni. V javni označevalnik ne vstavljajte zaupnih podatkov.

Dinamični nadomestni elementi

Dinamični otočki morajo izrisati nadomestni element, varen za skupni predpomnilnik celotne strani. V vejo za nadomestni element ne vključujte podatkov, specifičnih za obiskovalca.

Blockstudio išče nadomestne elemente v tem vrstnem redu:

  1. izrecno navedena pot island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. običajna predloga z zastavicami za nadomestne elemente
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Če datoteka za nadomestni element ne obstaja, uporabite zastavice predloge v običajni predlogi:

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

Iste vrednosti so na voljo v predlogah PHP, Twig in Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase je "normal", "hydrate", "placeholder" ali "fragment".

Delovanje izvajalnega okolja

Blockstudio vstavi izvajalno okolje otočkov samo, če izrisana stran vsebuje označevalnik otočka. Strani brez otočkov ne vsebujejo dodatne kode JavaScript za otočke.

Za dinamične otočke izvajalno okolje:

  1. zbere vse pripravljene označevalnike
  2. odstrani podvojene pare enakega imena bloka, atributov in podpisa
  3. pošlje eno združeno zahtevo REST
  4. vsak nadomestni element zamenja z vrnjenim fragmentom
  5. sproži blockstudio:island:rendered
  6. sproži blockstudio:island:hydrate

Otočki loading: "eager" se izrišejo takoj, ko se zažene izvajalno okolje. Otočki loading: "visible" čakajo na IntersectionObserver. Če v vidno polje hkrati vstopi več vidnih otočkov, so združeni v eno zahtevo.

event osveži otoček, ko se sproži imenovani dogodek okna:

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

Ob napakah nadomestni element ostane na mestu in sproži se blockstudio:island:error.

Končna točka za fragmente

Končna točka za otočke je javna, vendar ni splošni API za izris blokov.

Vsak označevalnik vsebuje:

  • ime bloka
  • atribute s seznama dovoljenih
  • podpis, ustvarjen na strežniku

Končna točka izriše vsebino samo, kadar:

  • je blok registriran
  • je blok dinamični blok WordPress
  • je blok označen kot dinamični otoček Blockstudio
  • vhodni atributi ustrezajo shemi bloka in seznamu dovoljenih atributov otočka
  • se podpis ujema z normaliziranim imenom bloka in atributi

Podpisi se ustvarijo med izrisom na strežniškem spletnem mestu WordPress na podlagi skrivnih vrednosti tega mesta in vsebine otočka. Niso izvoženi ali vgrajeni v temo.

Odgovori končne točke so označeni kot nepredpomnljivi. Za predpomnjenje fragmentov uporabite island.cache.

Predpomnjenje fragmentov

Dinamični fragmenti privzeto niso predpomnjeni.

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

true uporablja kratek globalni predpomnilnik. Za izrecen nadzor uporabite obliko objekta:

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

per: "global" deli en predpomnjeni fragment za isti blok, atribute in kontekst strani, če je ta možnost omogočena. per: "user" predpomnilnik prilagodi trenutnemu ID-ju uporabnika WordPress.

Programski izris

Otočki delujejo povsod, kjer se izrisujejo bloki Blockstudio:

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

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

Delujejo tudi prek oznak blokov:

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

Začetni izhod še vedno vsebuje označevalnik otočka in nadomestni element, izvajalno okolje pa se vstavi, ko izrisani odgovor vsebuje ta označevalnik.

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() preverja metapodatke bloka. Dinamični označevalniki se ustvarijo samo za registrirane dinamične bloke Blockstudio z island.mode, nastavljenim na dynamic.

Kavlji

Zaznavanje in označevalna koda:

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

Končna točka in izris:

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

blockstudio/islands/max_per_request spremeni največje število dinamičnih otočkov, sprejetih v eni združeni zahtevi končne točke. Privzeta vrednost je 50.

Konfiguracija izvajalnega okolja:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Podpisi:

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

Dejanja življenjskega cikla:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Kdaj ne uporabljati otočkov

Dinamičnega otočka ne uporabljajte za vsebino, ki je ključna za SEO. Fragmenti dinamičnega otočka niso prisotni v začetnem HTML in niso namenjeni indeksiranju.

Uporabite običajni izris ali hidrirani otoček, kadar je vsebina varna za predpomnjenje in mora biti vidna pajkom. Dinamični otoček uporabite samo za vsebino, ki se lahko naloži po ogrodju strani, na primer podatke o računu UI, stanje košarice, prilagojena priporočila ali kontrolnike, omejene z dovoljenji.