Ugrás a tartalomhoz

Szigetek

A blokkszigetek a normál Blockstudio renderelési folyamatot használják, miközben a kérésfüggő kimenetet kiveszik a kezdeti HTML válaszból.

Ez akkor hasznos, ha egy oldalt intenzíven szeretne gyorsítótárazni, de egy blokk továbbra is függ az aktuális látogatótól, munkamenettől, kosártól, jogosultságoktól vagy más élő kéréskontextustól.

A Blockstudio blokkok továbbra is dinamikus WordPress blokkok. A szigetek nem alakítják őket előre lefordított statikus HTML-vé. Ehelyett a Blockstudio módosítja, mi jelenik meg az első kéréskor:

  • a hidratált szigetek a szokásos, gyorsítótár-biztos HTML elemet jelenítik meg, és mount eseményt kapnak
  • a dinamikus szigetek először gyorsítótár-biztos helyőrzőt jelenítenek meg, majd a látogató böngészőjéből lekérik a valódi részletet

Módok

Hidratált szigetek

Használjon hidratált szigetet, ha a szerver kimenete biztonságosan gyorsítótárazható, és a blokknak csak egy frontend mount jelzésre van szüksége.

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

A teljes blokk HTML jelen van a kezdeti válaszban. A sziget futtatókörnyezete nem indít hozzá REST kérést. A jelölőn blockstudio:island:hydrate eseményt küld, hogy a frontend kód viselkedést társíthasson hozzá.

Dinamikus szigetek

Használjon dinamikus szigetet, ha a blokk valódi kimenetét a látogató kérési kontextusában kell renderelni.

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

A kezdeti válasz csak egy helyőrzőt tartalmaz. A böngésző az összes betöltésre kész dinamikus szigetet egyetlen kérésbe gyűjti ide:

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

A végpont csak azokat a regisztrált Blockstudio blokkokat rendereli, amelyek dinamikusak, és blockstudio.island.mode értéke dynamic.

Konfiguráció

A island értéke lehet rövid forma vagy objektum.

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

A true és a "hydrate" egyaránt hidratált módot jelent. A "dynamic" dinamikus módot jelent.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Tulajdonság Típus Alapértelmezett Leírás
mode "hydrate" vagy "dynamic" "hydrate" Szigetmód.
tag string "div" Jelölő burkolócímkéje.
attributes string[] az összes blokk attribútuma A dinamikus töredékek kéréseinek elküldött attribútumok engedélyezési listája.
placeholder string automatikusan észlelve Relatív helyőrzősablon-útvonal.
loading "eager" vagy "visible" "eager" Mikor kérjen le a futtatókörnyezet egy dinamikus szigetet.
event string nincs beállítva Az az ablakesemény neve, amely frissít egy dinamikus szigetet.
context boolean false A lekérdezett oldal bejegyzésazonosítójának és bejegyzéstípusának aláírása és visszaállítása dinamikus töredékekhez.
cache boolean vagy object false Opcionális töredékgyorsítótárazási szabályzat.

Oldalkörnyezet

A dinamikus töredékek általában az oldal keretétől függetlenül renderelődnek. Kapcsolja be az oldalazonosítást, ha a blokk oldalspecifikus beállításokat vagy kapcsolódó tartalmat olvas:

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

A jelölő a lekérdezett oldal postId és postType értékét tartalmazza az data-bs-island-context mezőben. Mindkét értéket a blokk nevével és az engedélyezett attribútumokkal együtt az oldalt kiszolgáló webhely titkos kulcsa írja alá. Módosításuk vagy kéréshez való hozzáadásuk érvényteleníti az aláírást. A futtatókörnyezet a már meglévő, kötegelt töredékkéréssel együtt küldi el őket, a láthatóság által és az események által kiváltott frissítéseknél is. Ez az bs_render_block(), az bs_block() és a blokkcímkék esetében is működik.

A töredék renderelésekor a $block['postId'], a $block['postType'], a get_the_ID() és a get_queried_object_id() erre az oldalra hivatkozik. A WordPress lekérdezési és bejegyzéshez kapcsolódó globális változók ezt követően visszaállnak, renderelési kivétel esetén is. Ez a lekérdezett oldal, nem pedig egy lekérdezési cikluson belüli elem. Nem játssza vissza a tetszőleges URL paramétereket, és nem állítja vissza az eredeti kérés URL értékét. Ha a HTML oldal kanonikus URL értékére van szüksége, használja a get_permalink($block['postId']) elemet. Az archívumok és a lekérdezett bejegyzés nélküli renderelések nem küldenek oldalazonosítót.

A végpont ellenőrzi, hogy az oldal még létezik-e, a bejegyzéstípus megegyezik-e az aláírttal, és az aktuális látogató elolvashatja-e, mielőtt a töredékgyorsítótárhoz fordulna. Az érvényes aláírás nem kerüli meg a privát bejegyzésekre vagy jelszavas védelemre, a sziget jogosultságára, az attribútumok engedélyezési listáira, illetve a blokk saját jogosultság-ellenőrzéseire vonatkozó szabályokat. Ha van oldalazonosító, az mindig része a töredékgyorsítótár kulcsának, ezért a különböző oldalakon található azonos blokkok és attribútumok soha nem osztanak meg töredéket. Használja a per: "user" elemet, vagy ne gyorsítótárazza a töredéket, ha a kimenet a látogatótól is függ.

Ha a context nincs megadva, vagy false értékű, a meglévő jelölők és a környezetfüggetlen működés változatlan marad. Ne helyezzen bizalmas adatokat a nyilvános jelölőbe.

Dinamikus helyőrzők

A dinamikus szigeteknek olyan helyőrzőt kell megjeleníteniük, amely biztonságos közös teljesoldalas gyorsítótárban. Ne tegyen látogatóspecifikus adatot a helyőrző ágába.

A Blockstudio a következő sorrendben keresi a helyőrzőket:

  1. a megadott island.placeholder útvonal
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. a normál sablon helyőrzőjelzőkkel
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Ha nincs helyőrzőfájl, használja a normál sablon sablonjelzőit:

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

Ugyanezek az értékek a PHP, Twig és Blade sablonokban is elérhetők:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

A islandPhase értéke "normal", "hydrate", "placeholder" vagy "fragment".

Futtatókörnyezeti viselkedés

A Blockstudio csak akkor illeszti be a sziget futtatókörnyezetét, ha a renderelt oldal tartalmaz szigetjelölőt. A szigeteket nem tartalmazó oldalakhoz nem kerül extra sziget-JavaScript.

Dinamikus szigetek esetén a futtatókörnyezet:

  1. összegyűjti az összes betöltésre kész jelölőt
  2. összevonja az azonos blokknévvel, attribútumokkal és aláíráspárral rendelkezőket
  3. egy összevont REST kérést küld
  4. minden helyőrzőt lecserél a visszakapott részletre
  5. elküldi a blockstudio:island:rendered eseményt
  6. elküldi a blockstudio:island:hydrate eseményt

A loading: "eager" szigetek a futtatókörnyezet indulásakor azonnal megjelennek. A loading: "visible" szigetek a IntersectionObserver eseményre várnak. Ha egyszerre több látható sziget kerül a nézetbe, egyetlen kérésben gyűjtődnek össze.

A event frissíti a szigetet, amikor a megnevezett ablakesemény bekövetkezik:

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

Hiba esetén a helyőrző a helyén marad, és elküldi a következő eseményt: blockstudio:island:error.

Részletvégpont

A sziget végpontja nyilvános, de nem általános blokkmegjelenítő API.

Minden jelölő a következőket tartalmazza:

  • a blokk neve
  • az engedélyezési listán szereplő attribútumok
  • egy szerver által generált aláírás

A végpont csak akkor renderel, ha:

  • a blokk regisztrálva van
  • a blokk dinamikus WordPress blokk
  • a blokk dinamikus Blockstudio szigetként van megjelölve
  • a bejövő attribútumok megfelelnek a blokk sémájának és a sziget engedélyezési listájának
  • az aláírás egyezik a normalizált blokknévvel és attribútumokkal

Az aláírások a kiszolgáló WordPress webhelyén, rendereléskor jönnek létre a webhely sóival és a szigetadatokkal. Nem exportálódnak és nem kerülnek beépítésre a témába.

A végpont válaszai gyorsítótárazásra nem alkalmasként vannak megjelölve. Ha részlet-gyorsítótárazásra van szüksége, használja ezt: island.cache.

Részlet-gyorsítótárazás

A dinamikus részletek alapértelmezés szerint nincsenek gyorsítótárazva.

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

A true rövid ideig érvényes globális gyorsítótárat használ. Kifejezett vezérléshez használja az objektumformát:

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

per: "global" ugyanazt a gyorsítótárazott töredéket osztja meg azonos blokk, attribútumok és engedélyezett oldalkontextus esetén. per: "user" az aktuális WordPress felhasználói azonosító alapján változtatja a gyorsítótárat.

Programozott renderelés

A szigetek minden olyan helyen működnek, ahol Blockstudio blokkok renderelődnek:

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

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

Blokkcímkéken keresztül is működnek:

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

A kezdeti kimenet továbbra is a szigetjelölő és a helyőrző, a futtatókörnyezet pedig akkor kerül beillesztésre, ha a renderelt válasz tartalmazza ezt a jelölőt.

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

A marker() ellenőrzi a blokk metaadatait. Dinamikus jelölők csak regisztrált dinamikus Blockstudio blokkokhoz készülnek, amelyeknél a island.mode értéke dynamic.

Hookok

Észlelés és jelölés:

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

Végpont és renderelés:

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

A blockstudio/islands/max_per_request módosítja az egy összevont végpontkérésben elfogadott dinamikus szigetek maximális számát. Az alapértelmezett érték 50.

Futtatókörnyezeti konfiguráció:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Aláírások:

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

Életciklus-műveletek:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Mikor ne használjon szigeteket

Ne használjon dinamikus szigetet olyan tartalomhoz, amelynél fontos a SEO. A dinamikus szigetrészletek nincsenek jelen a kezdeti HTML-ban, és nem indexelésre készültek.

Használjon normál renderelést vagy hidratált szigetet, ha a tartalom gyorsítótár-biztos, és a feltérképező robotok számára láthatónak kell lennie. Dinamikus szigetet csak olyan tartalomhoz használjon, amely az oldalváz betöltése után is megérkezhet, például fiók-UI, kosárállapot, személyre szabott ajánlások vagy jogosultsághoz kötött vezérlők esetén.