Pāriet uz saturu

Salas

Bloku salas ļauj blokam saglabāt parasto Blockstudio renderēšanas procesu, vienlaikus pārvietojot konkrētajam pieprasījumam paredzēto izvadi ārpus sākotnējās HTML atbildes.

Tas noder, ja lapa ir intensīvi jākešo, bet viens bloks joprojām ir atkarīgs no pašreizējā apmeklētāja, sesijas, iepirkumu groza, atļaujām vai cita aktuālā pieprasījuma konteksta.

Blockstudio bloki joprojām ir dinamiski WordPress bloki. Salas nepārvērš tos iepriekš kompilētos statiskos HTML. Tā vietā Blockstudio maina to, kas tiek renderēts pirmajā pieprasījumā:

  • hidratētās salas renderē savu parasto, kešatmiņai drošo HTML un saņem montāžas notikumu
  • dinamiskās salas vispirms renderē kešatmiņai drošu vietturi, pēc tam apmeklētāja pārlūkprogrammā iegūst īsto fragmentu

Režīmi

Hidratētās salas

Izmantojiet hidratētu salu, ja servera izvadi var droši kešot un blokam vajadzīgs tikai priekšgala montāžas signāls.

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

Pilns bloka HTML ir iekļauts sākotnējā atbildē. Salas izpildvide neveic tam REST pieprasījumu. Tā nosūta blockstudio:island:hydrate marķierim, lai priekšgala kods varētu piesaistīt darbības.

Dinamiskās salas

Izmantojiet dinamisku salu, ja īstā bloka izvade ir jārenderē apmeklētāja pieprasījuma kontekstā.

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

Sākotnējā atbildē ir tikai vietturis. Pārlūkprogramma apvieno visas gatavās dinamiskās salas vienā pieprasījumā uz:

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

Galapunkts renderē tikai reģistrētus Blockstudio blokus, kas ir dinamiski un kuriem blockstudio.island.mode ir iestatīts uz dynamic.

Konfigurācija

Vērtība island var būt saīsinātā forma vai objekts.

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

Gan true, gan "hydrate" apzīmē hidratētu salu. "dynamic" apzīmē dinamisku salu.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Rekvizīts Tips Noklusējums Apraksts
mode "hydrate" vai "dynamic" "hydrate" Salas režīms.
tag string "div" Marķiera ietvara tags.
attributes string[] visi bloka atribūti Dinamisko fragmentu pieprasījumiem nosūtāmo atribūtu atļaušanas saraksts.
placeholder string automātiski noteikts Relatīvais viettura veidnes ceļš.
loading "eager" vai "visible" "eager" Kad izpildvidei jāielādē dinamisks salas fragments.
event string nav iestatīts Loga notikuma nosaukums, kas atsvaidzina dinamisku salas fragmentu.
context boolean false Parakstīt un atjaunot vaicātās lapas ziņas ID un ziņas tipu dinamiskajiem fragmentiem.
cache boolean vai object false Neobligāta fragmenta kešatmiņas politika.

Lapas konteksts

Dinamiskie fragmenti parasti tiek renderēti neatkarīgi no lapas ietvara. Iespējojiet lapas identitāti, ja bloks nolasa lapai specifiskus iestatījumus vai saistīto saturu:

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

Marķierā ir ietverti vaicātās lapas postId un postType, kas ievietoti data-bs-island-context. Abas vērtības tiek parakstītas kopā ar bloka nosaukumu un atļautajiem atribūtiem, izmantojot vietnes noslēpuma atslēgu. Tās nevar mainīt vai pievienot pieprasījumam, nepadarot parakstu nederīgu. Izpildvide tās nosūta esošajā grupētajā fragmentu pieprasījumā, tostarp redzamības un notikumu izraisītas atsvaidzināšanas laikā. Tas darbojas arī ar bs_render_block(), bs_block() un bloku tagiem.

Fragmenta renderēšanas laikā $block['postId'], $block['postType'], get_the_ID() un get_queried_object_id() attiecas uz šo lapu. Pēc tam tiek atjaunoti WordPress vaicājuma un ziņas globālie mainīgie, arī tad, ja renderēšanas laikā rodas izņēmums. Tā ir vaicātā lapa, nevis vienums vaicājuma ciklā. Netiek atkārtoti patvaļīgi URL parametri un netiek atjaunots sākotnējais pieprasījuma URL. Ja nepieciešams HTML lapas kanoniskais URL, izmantojiet get_permalink($block['postId']). Arhīvi un renderēšanas gadījumi bez vaicātas ziņas nenosūta lapas identitāti.

Pirms fragmenta kešatmiņas izmantošanas galapunkts pārbauda, vai lapa joprojām pastāv, tai ir parakstītais ziņas tips un pašreizējais apmeklētājs to drīkst lasīt. Derīgs paraksts neapiet privātas ziņas vai paroles aizsardzību, salas atbilstības nosacījumus, atribūtu atļaušanas sarakstus vai jūsu bloka atļauju pārbaudes. Ja lapas identitāte ir norādīta, tā vienmēr ir daļa no fragmenta kešatmiņas atslēgas, tāpēc vienam un tam pašam blokam ar vienādiem atribūtiem dažādās lapās nav kopīgu fragmentu. Izmantojiet per: "user" vai izslēdziet fragmentu kešatmiņu, ja izvade ir atkarīga arī no apmeklētāja.

Ja context ir izlaists vai norādīts false, esošie marķieri un no konteksta neatkarīgā darbība paliek nemainīga. Neiekļaujiet konfidenciālus datus publiskajā marķierā.

Dinamiskie vietturi

Dinamiskajām salām jārenderē vietturis, ko var droši izmantot koplietotā visas lapas kešatmiņā. Viettura zarā neiekļaujiet apmeklētājam specifiskus datus.

Blockstudio meklē vietturus šādā secībā:

  1. skaidri norādītais ceļš island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. parastā veidne ar viettura karogiem
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Ja viettura fails nepastāv, izmantojiet karogus parastajā veidnē:

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

Tās pašas vērtības ir pieejamas arī veidnēs PHP, Twig un Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase ir "normal", "hydrate", "placeholder" vai "fragment".

Izpildvides darbība

Blockstudio ievieto salas izpildvides kodu tikai tad, ja renderētajā lapā ir salas marķieris. Lapām bez salām netiek pievienota papildu salas JavaScript.

Dinamiskajām salām izpildvide:

  1. apkopo visus gatavos marķierus
  2. novērš vienādu bloka nosaukuma, atribūtu un paraksta pāru dublēšanos
  3. nosūta vienu apvienotu REST pieprasījumu
  4. aizstāj katru vietturi ar saņemto fragmentu
  5. nosūta blockstudio:island:rendered
  6. nosūta blockstudio:island:hydrate

loading: "eager" salas tiek renderētas, tiklīdz izpildvide sāk darboties. loading: "visible" salas gaida IntersectionObserver. Ja vienlaikus redzamajā apgabalā nonāk vairākas salas, tās tiek apvienotas vienā pieprasījumā.

event atsvaidzina salu, kad tiek izsaukts nosauktais pārlūka loga notikums:

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

Kļūmes atstāj vietturi tā vietā un nosūta blockstudio:island:error.

Fragmenta galapunkts

Salas galapunkts ir publisks, taču tas nav vispārīgs bloku renderēšanas API.

Katram marķierim ir:

  • bloka nosaukums
  • atribūti no atļaušanas saraksta
  • servera ģenerēts paraksts

Galapunkts veic renderēšanu tikai tad, ja:

  • bloks ir reģistrēts
  • bloks ir dinamisks WordPress bloks
  • bloks ir atzīmēts kā dinamiska Blockstudio sala
  • ienākošie atribūti atbilst bloka shēmai un salas atļaušanas sarakstam
  • paraksts atbilst normalizētajam bloka nosaukumam un atribūtiem

Paraksti tiek ģenerēti renderēšanas laikā vietnes serverī WordPress, izmantojot šīs vietnes salt vērtības un salas saturu. Tie netiek eksportēti vai iekļauti motīvā.

Galapunkta atbildes tiek atzīmētas kā nekešojamas. Ja vēlaties kešot fragmentus, izmantojiet island.cache.

Fragmentu kešošana

Pēc noklusējuma dinamiskie fragmenti netiek kešoti.

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

true izmanto īslaicīgu globālu kešatmiņu. Lai skaidri kontrolētu tās darbību, izmantojiet objekta formu:

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

per: "global" izmanto vienu kešotu fragmentu tam pašam blokam, atribūtiem un izvēles lapas kontekstam. per: "user" kešošanas atslēgā iekļauj pašreizējā lietotāja ID — WordPress.

Renderēšana programmatiski

Salas darbojas visur, kur tiek renderēti Blockstudio bloki:

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

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

Tās darbojas arī, izmantojot bloku tagus:

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

Sākotnējā izvade joprojām ir salas marķieris un vietturis, un izpildvide tiek ievietota, ja renderētajā atbildē ir šis marķieris.

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() validē bloka metadatus. Dinamiskie marķieri tiek veidoti tikai reģistrētiem dinamiskiem Blockstudio blokiem, kuriem island.mode ir iestatīts uz dynamic.

Āķi

noteikšana un marķējums:

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

Galapunkts un renderēšana:

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

blockstudio/islands/max_per_request maina maksimālo dinamisko salu skaitu, ko pieņem viens apvienots galapunkta pieprasījums. Noklusējums ir 50.

Izpildvides konfigurācija:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Paraksti:

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

Dzīves cikla darbības:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Kad salas izmantot nevajadzētu

Neizmantojiet dinamisku salu SEO kritiskam saturam. Dinamisko salu fragmentu nav sākotnējā HTML, un tie nav paredzēti indeksēšanai.

Izmantojiet parasto renderēšanu vai hidratētu salu saturam, ko var droši kešot un kam jābūt redzamam tīmekļa rāpuļprogrammām. Izmantojiet dinamisku salu tikai saturam, kas var tikt ielādēts pēc lapas ietvara, piemēram, konta UI, iepirkumu groza stāvoklim, personalizētiem ieteikumiem vai vadīklām, kuru lietošanai nepieciešamas atļaujas.