Siirry sisältöön

Saarekkeet

Lohkosaarekkeiden avulla lohko voi käyttää tavallista Blockstudio-renderöintiputkea ja siirtää pyyntökohtaisen tulosteen pois alkuperäisestä HTML-vastauksesta.

Tästä on hyötyä, kun sivu halutaan tallentaa tehokkaasti välimuistiin, mutta jokin lohko riippuu edelleen nykyisestä kävijästä, istunnosta, ostoskorista, käyttöoikeuksista tai muusta ajantasaisesta pyyntökontekstista.

Blockstudio-lohkot ovat yhä dynaamisia WordPress-lohkoja. Saarekkeet eivät muuta niitä valmiiksi käännetyiksi staattisiksi HTML-lohkoiksi. Sen sijaan Blockstudio muuttaa sitä, mitä ensimmäisellä pyynnöllä renderöidään:

  • Hydratut saarekkeet renderöivät tavallisen välimuistiystävällisen HTML-sisältönsä ja saavat käynnistystapahtuman
  • Dynaamiset saarekkeet renderöivät ensin välimuistiystävällisen paikkamerkin ja hakevat sitten todellisen osan kävijän selaimesta

Tilat

Hydratut saarekkeet

Käytä hydrattua saareketta, kun palvelimen tuloste voidaan tallentaa turvallisesti välimuistiin ja lohko tarvitsee vain käyttöliittymän käynnistyssignaalin.

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

Koko lohkon HTML on mukana alkuperäisessä vastauksessa. Saarekeajonaikainen ympäristö ei tee siitä REST-pyyntöä. Se lähettää tapahtuman blockstudio:island:hydrate merkkiin, jotta käyttöliittymän koodi voi liittää siihen toiminnan.

Dynaamiset saarekkeet

Käytä dynaamista saareketta, kun todellinen lohkotuloste on renderöitävä kävijän pyyntökontekstissa.

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

Alkuperäinen vastaus sisältää vain paikkamerkin. Selain kokoaa kaikki valmiit dynaamiset saarekkeet yhdeksi pyynnöksi osoitteeseen:

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

Päätepiste renderöi vain rekisteröidyt Blockstudio-lohkot, jotka ovat dynaamisia ja joille blockstudio.island.mode on asetettu arvoon dynamic.

Määritykset

island-arvo voi olla lyhyt muoto tai objekti.

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

true ja "hydrate" tarkoittavat molemmat hydrattua tilaa. "dynamic" tarkoittaa dynaamista tilaa.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Ominaisuus Tyyppi Oletusarvo Kuvaus
mode "hydrate" tai "dynamic" "hydrate" Saaritila.
tag string "div" Merkkikääreen tunniste.
attributes string[] kaikki lohkon attribuutit Attribuuttien sallittujen arvojen luettelo dynaamisiin fragmenttipyyntöihin.
placeholder string tunnistetaan automaattisesti Suhteellinen paikkamerkkimallin polku.
loading "eager" tai "visible" "eager" Milloin ajonaikaisen ympäristön pitäisi hakea dynaaminen saari.
event string ei asetettu Ikkunatapahtuman nimi, joka päivittää dynaamisen saaren.
context boolean false Allekirjoita kyselyn kohteena olevan sivun artikkelin tunnus ja tyyppi ja palauta ne dynaamisille fragmenteille.
cache boolean tai object false Valinnainen fragmentin välimuistikäytäntö.

Sivun konteksti

Dynaamiset fragmentit renderöidään tavallisesti sivun kuoresta riippumatta. Ota sivun identiteetti käyttöön, jos lohkosi lukee sivukohtaisia asetuksia tai niihin liittyvää sisältöä:

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

Merkki sisältää kyselyn kohteena olevan sivun postId ja postType arvot kohdassa data-bs-island-context. Molemmat arvot allekirjoitetaan lohkon nimellä ja sallituilla attribuuteilla sivuston salaisuutta käyttäen. Niitä ei voi muuttaa tai lisätä pyyntöön allekirjoitusta mitätöimättä. Ajonaikainen ympäristö lähettää ne olemassa olevan erämuotoisen fragmenttipyynnön mukana myös näkyvyyden ja tapahtumien käynnistämissä päivityksissä. Tämä toimii myös kohteiden bs_render_block() ja bs_block() sekä lohkotunnisteiden kanssa.

Fragmenttia renderöitäessä $block['postId'], $block['postType'], get_the_ID() ja get_queried_object_id() viittaavat kyseiseen sivuun. WordPress-kysely ja artikkelien globaalit palautetaan renderöinnin jälkeen, myös silloin, kun renderöinti aiheuttaa poikkeuksen. Tämä on kyselyn kohteena oleva sivu, ei kyselysilmukan sisäinen kohde. Mielivaltaisia URL-parametreja ei toisteta eikä alkuperäistä pyyntöä URL palauteta. Käytä get_permalink($block['postId'])-kohdetta, kun tarvitset HTML-sivun kanonisen arvon URL. Arkistoissa ja renderöinneissä, joissa ei ole kyselyn kohteena olevaa artikkelia, sivun identiteettiä ei lähetetä.

Päätepiste tarkistaa, että sivu on edelleen olemassa, sen artikkelityyppi vastaa allekirjoitettua tyyppiä ja nykyinen kävijä voi lukea sen, ennen fragmentin välimuistin tarkistamista. Kelvollinen allekirjoitus ei ohita yksityisen artikkelin tai salasanan suojausta, saaren kelpoisuutta, attribuuttien sallittujen arvojen luetteloita eikä lohkosi omia käyttöoikeustarkistuksia. Sivun identiteetti kuuluu aina fragmentin välimuistiavaimeen, jos se on määritetty, joten sama lohko samoilla attribuuteilla ei koskaan jaa fragmenttia eri sivujen välillä. Käytä per: "user"-arvoa tai poista fragmentin välimuisti käytöstä, jos tuloste riippuu myös kävijästä.

Jos context jätetään pois tai käytössä on false, olemassa olevat merkit ja toiminta ilman kontekstia pysyvät ennallaan. Älä lisää julkiseen merkkiin luottamuksellisia tietoja.

Dynaamiset paikkamerkit

Dynaamisten saarekkeiden tulisi renderöidä paikkamerkki, joka voidaan turvallisesti tallentaa jaettuun koko sivun välimuistiin. Älä sisällytä kävijäkohtaisia tietoja paikkamerkkihaaraan.

Blockstudio etsii paikkamerkkejä seuraavassa järjestyksessä:

  1. nimenomainen island.placeholder-polku
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. tavallinen malli, jossa on paikkamerkkiliput
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Jos paikkamerkkitiedostoa ei ole, käytä tavallisen mallin mallilippuja:

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

Samat arvot ovat käytettävissä malleissa PHP, Twig ja Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase on "normal", "hydrate", "placeholder" tai "fragment".

Ajonaikainen toiminta

Blockstudio lisää saarekkeiden ajonaikaisen ympäristön vain, jos renderöity sivu sisältää saarekemerkin. Sivut, joilla ei ole saarekkeita, eivät sisällä ylimääräistä saareke-JavaScript-tiedostoa.

Dynaamisten saarekkeiden ajonaikainen ympäristö:

  1. kerää kaikki valmiit merkit
  2. poistaa kaksoiskappaleet saman lohkon nimen, attribuuttien ja allekirjoitusparien osalta
  3. lähettää yhden erämuotoisen REST-pyynnön
  4. korvaa kunkin paikkamerkin palautetulla osalla
  5. lähettää tapahtuman blockstudio:island:rendered
  6. lähettää tapahtuman blockstudio:island:hydrate

loading: "eager"-saarekkeet renderöidään heti ajonaikaisen ympäristön käynnistyessä. loading: "visible"-saarekkeet odottavat arvoa IntersectionObserver. Jos useita näkyviä saarekkeita tulee näkymään yhtä aikaa, ne kootaan yhdeksi pyynnöksi.

event päivittää saarekkeen, kun nimetty ikkunatapahtuma käynnistyy:

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

Virhetilanteissa paikkamerkki jää paikalleen ja lähetetään tapahtuma blockstudio:island:error.

Osan päätepiste

Saarekkeen päätepiste on julkinen, mutta se ei ole yleiskäyttöinen lohkojen renderöinnin API.

Kukin merkki sisältää:

  • lohkon nimen
  • sallittujen attribuuttien luettelon
  • palvelimella luodun allekirjoituksen

Päätepiste renderöi vain, jos:

  • lohko on rekisteröity
  • lohko on dynaaminen WordPress-lohko
  • lohko on merkitty dynaamiseksi Blockstudio-saarekkeeksi
  • saapuvat attribuutit läpäisevät lohkon skeeman ja saarekkeen sallittujen attribuuttien luettelon
  • allekirjoitus vastaa normalisoitua lohkon nimeä ja attribuutteja

Allekirjoitukset luodaan renderöinnin yhteydessä sivua palvelevalla WordPress-sivustolla kyseisen sivuston suoloista ja saarekkeen hyötykuormasta. Niitä ei viedä eikä sisällytetä teemaan.

Päätepisteen vastaukset merkitään välimuistiin tallentamattomiksi. Jos haluat osien välimuistitallennuksen, käytä island.cache-ominaisuutta.

Osien välimuistitallennus

Dynaamisia osia ei tallenneta oletuksena välimuistiin.

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

true käyttää lyhytaikaista yleistä välimuistia. Käytä objektimuotoa, jos haluat määrittää asetukset tarkasti:

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

per: "global" jakaa saman välimuistissa olevan katkelman, kun lohko, määritteet ja sivun valinnainen konteksti ovat samat. per: "user" muuttaa välimuistia nykyisen käyttäjän WordPress ID:n mukaan.

Ohjelmallinen renderöinti

Saarekkeet toimivat kaikkialla, missä Blockstudio-lohkot renderöidään:

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

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

Ne toimivat myös lohkomerkintöjen kautta:

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

Alkuperäinen tuloste sisältää edelleen saarekemerkin ja paikkamerkin, ja ajonaikainen ympäristö lisätään, kun renderöity vastaus sisältää kyseisen merkin.

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() tarkistaa lohkon metatiedot. Dynaamiset merkit luodaan vain rekisteröidyille dynaamisille Blockstudio-lohkoille, joiden island.mode-arvoksi on asetettu dynamic.

Hookit

Tunnistus ja merkintä:

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

Päätepiste ja renderöinti:

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

blockstudio/islands/max_per_request muuttaa dynaamisten saarekkeiden enimmäismäärää, jonka yksi erämuotoinen päätepistepyyntö hyväksyy. Oletusarvo on 50.

Ajonaikaisen ympäristön määritys:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Allekirjoitukset:

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

Elinkaaren toiminnot:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Milloin saarekkeita ei kannata käyttää

Älä käytä dynaamista saareketta sisällölle, joka on kriittistä SEO-näkyvyyden kannalta. Dynaamiset saarekeosat eivät sisälly alkuperäiseen HTML-vastaukseen, eikä niitä ole tarkoitettu indeksoitaviksi.

Käytä tavallista renderöintiä tai hydrattua saareketta, kun sisältö voidaan tallentaa välimuistiin ja sen tulee näkyä indeksointiroboteille. Käytä dynaamista saareketta vain sisällölle, joka voi latautua sivurungon jälkeen, kuten tilin UI-tiedoille, ostoskorin tilalle, personoiduille suosituksille tai käyttöoikeuksien rajaamille ohjaimille.