Gå til indhold

Personlige fragmenter på cachelagrede sider

En side, der leveres fra en statisk cache, er ens for alle. Det er hele pointen med caching, men det skaber også et problem: sidehovedet skal sige “Hej, Ada” til en indlogget kunde, og kurveikonet skal vise tre varer. Hvis skabelonen varierer efter den aktuelle bruger, gemmer cachen enten én besøgendes hilsen til alle eller må helt undlade at cache siden.

Blockstudios dynamiske øer adskiller de to hensyn. Den cachelagrede HTML indeholder en pladsholder, der er sikker at cache. Når siden er indlæst, beder en lille runtime WordPress om det personlige fragment i den besøgendes egen forespørgsel og indsætter det. Siden kan stadig caches, og kun fragmentet er dynamisk.

Denne guide bygger to øer, en hilsen og et antal varer i kurven, og gennemgår, hvad den cachelagrede side indeholder, hvordan fragmentforespørgslen ser ud, og hvordan endepunktet afgør, hvem den besøgende er. Den supplerer Serving WordPress as Static HTML.

Sådan fungerer en dynamisk ø

  1. Blokken gengiver sin pladsholder inde i et markørelement. Markøren indeholder bloknavnet, de tilladte attributter og en serverskabt signatur.
  2. Når den gengivne side indeholder en markør, indsætter Blockstudio øens runtime. Sider uden øer indeholder ingen ø-JavaScript.
  3. Runtimen indsamler klar-markører og sender én samlet POST til /wp-json/blockstudio/v1/island/render.
  4. Endepunktet verificerer hver signatur, gengiver blokken i konteksten for den besøgendes forespørgsel og returnerer fragmenterne.
  5. Runtimen erstatter hver pladsholder og udsender hændelser.

I blokeditoren gengives blokken normalt uden en pladsholder.

Trin 1: Hilsenblokken

Opret blokken med tre filer:

Kode
blocks/
└── greeting/
    ├── block.json
    ├── placeholder.php
    └── index.php
JSON
{
  "apiVersion": 3,
  "name": "acme/greeting",
  "title": "Greeting",
  "category": "widgets",
  "icon": "admin-users",
  "description": "Account link that greets signed-in visitors.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "span",
      "attributes": ["guestLabel"],
      "cache": {
        "ttl": 300,
        "per": "user"
      }
    },
    "attributes": [
      { "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
    ]
  }
}

mode: "dynamic" gør den til en ø med en fragmentforespørgsel. tag angiver markørelementet, så øen kan stå inline i en navigationslinje. attributes er listen over tilladte blokattributter, der sendes med fragmentforespørgslen; alt, der ikke er på listen, hverken sendes eller signeres. cache gennemgås længere nede.

Pladsholderen er det, den cachelagrede side indeholder. Den skal være sikker at vise til alle besøgende, så den må ikke indeholde brugerdata. Et “Konto”-link fungerer for alle:

PHP
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>

Hovedskabelonen gengiver det rigtige fragment:

PHP
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
  <a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
    <?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
  </a>
<?php else : ?>
  <a href="<?php echo esc_url( wp_login_url() ); ?>">
    <?php echo esc_html( $a['guestLabel'] ); ?>
  </a>
<?php endif; ?>

Det er fint at vælge en gren ud fra den aktuelle bruger her: denne skabelon køres kun for fragmentforespørgslen, aldrig for den cachelagrede side.

Placér den dér, hvor sidehovedet gengives:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Bloktags virker også: <bs:acme-greeting /> eller <block name="acme/greeting" />.

Trin 2: Hvad den cachelagrede side indeholder

Når blokken gengives på serveren, producerer den kun markøren og pladsholderen:

HTML
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{&quot;guestLabel&quot;:&quot;Sign in&quot;}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>

Gengiv den én gang som anonym besøgende og én gang som indlogget bruger, så er de to strenge identiske byte for byte. Det er netop den egenskab, som en statisk forhåndsgengivelse med serveLoggedIn aktiveret kræver: uanset hvem der udløser gengivelsen, er det gemte dokument det samme, og ingen personlige oplysninger kan havne i det.

Trin 3: Fragmentforespørgslen

Runtimen sender alle klar-øer i én forespørgsel:

JSON
{
    "islands": [
        {
            "clientId": "a1",
            "name": "acme/greeting",
            "attributes": {
                "guestLabel": "Sign in"
            },
            "signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
        }
    ]
}

Svaret er knyttet til clientId. For en indlogget besøgende:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/account/\">\n    Hi, Ada  </a>\n"
}

En post, der ikke består verificeringen, returneres som en fejlkode i stedet for HTML, uden at resten af gruppen fejler. Her blev guestLabel i den anden post ændret uden en tilsvarende signatur, og den tredje angav en blok, der ikke er en dynamisk ø:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/wp-login.php\">\n    Sign in  </a>\n",
    "a2": {
        "error": "blockstudio_island_invalid_signature"
    },
    "a3": {
        "error": "blockstudio_island_not_allowed"
    }
}

Hvert svar indeholder Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache og X-Robots-Tag: noindex. Endepunktet ligger under /wp-json, som den statiske forhåndsgengivelse altid omgår, så hverken oprindelsescachen eller en CDN, der følger oprindelsens headere, gemmer et fragment.

Hvem er den besøgende

Runtimen sender forespørgslen med credentials: 'same-origin', så browseren inkluderer login-cookien WordPress. WordPress REST API ignorerer normalt cookiegodkendelse uden en nonce, og en nonce kan ikke ligge på en cachelagret side. Øens endepunkt håndterer dette selv: ved en browserforespørgsel fra samme oprindelse validerer det cookien logged_in og gendanner brugeren, før blokken gengives.

Om forespørgslen kommer fra samme oprindelse, afgøres ud fra headeren Sec-Fetch-Site og, hvis den findes, headeren Origin sammenlignet med home_url(). En forespørgsel fra en anden oprindelse, der tilfældigvis indeholder cookien, gengives som anonym, så en forespørgsel fra et andet websted aldrig gengiver en besøgendes personlige fragment. I praksis:

Forespørgsel Gengives som
Forespørgsel fra samme oprindelse med gyldig logincookie den indloggede bruger
Forespørgsel fra en anden oprindelse med samme cookie anonym
Ingen cookie anonym

Hvilken side er det?

Tilføj "context": true til blockstudio.island, når fragmentet har brug for sidens identitet. Markøren signerer derefter ID’et og indlægstypen for den forespurgte side sammen med attributterne. I fragmentet henviser $block['postId'], $block['postType'], get_the_ID() og get_queried_object_id() til den pågældende side. Inde i en Query Loop betyder det stadig den ydre forespurgte side og ikke loop-elementet.

Sidekontekst er tilvalgsbaseret og indgår også i fragmentcache-nøglen. Endepunktet kontrollerer adgangen igen, selv for cachede fragmenter, så en signeret markør ikke viser en side, der siden er blevet privat eller adgangskodebeskyttet. Se Sidekontekst for konfigurationen og sikkerhedsoplysningerne. Vilkårlige URL eller forespørgselsparametre genafspilles ikke.

Trin 4: Et antal varer i kurven, der opdateres automatisk

Den anden ø viser den anden pladsholderstil og to runtimeindstillinger. I stedet for en separat pladsholderfil kontrollerer skabelonen $isIslandPlaceholder:

JSON
{
  "apiVersion": 3,
  "name": "acme/cart-count",
  "title": "Cart Count",
  "category": "widgets",
  "icon": "cart",
  "description": "Number of items in the visitor's cart.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "loading": "visible",
      "event": "acme:cart-updated"
    },
    "attributes": []
  }
}
PHP
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
  <a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
  <a href="/cart/" class="cart-count">
    Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
  </a>
<?php endif; ?>

De samme flag findes i alle skabelonsprog: isIsland, isIslandPlaceholder, isIslandFragment og islandPhase ("normal", "hydrate", "placeholder" eller "fragment"). Her kommer antallet fra et acme/cart_count-filter, som din handelskode udfylder; når det returnerer 3, svarer endepunktet:

JSON
{"c1":"<!--blockstudio/acme/cart-count-->  <a href=\"/cart/\" class=\"cart-count\">\n    Cart <span class=\"cart-count__badge\">3</span>\n  </a>\n"}

loading: "visible" udsætter forespørgslen, indtil markøren kommer ind i visningsområdet, ved hjælp af IntersectionObserver. Synlige øer, der vises samtidig, samles stadig i én forespørgsel. event angiver en vinduesevent, der henter øen igen, så efter et kald til at lægge en vare i kurven behøver dit script kun at udsende den:

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

Reager i frontendkode

Hændelser bobler op fra markøren, så én lytter på document dækker alle øer. event.detail.name indeholder bloknavnet:

JavaScript
document.addEventListener('blockstudio:island:rendered', (event) => {
  if (event.detail.name !== 'acme/cart-count') return;
  event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});

document.addEventListener('blockstudio:island:error', (event) => {
  console.warn('Island failed', event.detail.name, event.detail.error);
});

Efter et skift sender runtime blockstudio:island:rendered og derefter blockstudio:island:hydrate. Ved fejl bliver pladsholderen stående, og blockstudio:island:error udløses. Hydrerede øer ("island": "hydrate") springer helt over anmodningen: deres fulde HTML findes på siden, og de modtager kun hændelsen hydrate, hvilket egner sig til cachevenlige interaktive blokke som faner.

Fragmentcache

Fragmenter gengives som standard ved hver anmodning. Hilsenen ovenfor bruger en kort cache:

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

per: "user" varierer det cachelagrede fragment efter brugerens WordPress, og anonyme anmodninger caches aldrig på denne måde, så to anonyme besøgende ikke kan dele en post, der er tiltænkt en bruger. per: "global" deler ét fragment for samme blok og attributter, hvilket egner sig til indhold, der er aktuelt, men ikke personligt, såsom et lagerniveau. ttl er som standard 60 sekunder, og cache: true er en global cache på 60 sekunder.

Sikkerhedsmodellen

Endpointet er offentligt, men det er ikke en generel blokrenderer. Det gengiver kun en post, når alle følgende betingelser er opfyldt:

  • blokken er registreret, dynamisk og har island.mode sat til dynamic
  • signaturen matcher bloknavnet og de attributter, der overlever filteret: kun nøgler, som findes både i blokskemaet og øens tilladelsesliste

Signaturen er en HMAC-SHA256 over det normaliserede bloknavn og attributterne, nøglebeskyttet med den serverende sides auth-salt. Signaturer oprettes på siden ved gengivelse og indlejres aldrig i et tema. Det har to konsekvenser. Et dokument, der gengives på staging, indeholder staging-signaturer, så gengiv dokumenter på den side, der serverer dem. Og hvis WordPress-saltværdierne roteres, bliver alle signaturer i gemte dokumenter ugyldige, så ryd den statiske forhåndsgengivelse efter en saltrulering.

En anmodning accepterer op til 50 øer; flere udløser HTTP 413. Skift grænsen med blockstudio/islands/max_per_request. Signaturhooks (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) findes til værter, der har brug for en anden ordning.

Hvornår du ikke skal bruge en ø

Fragmenter er ikke med i den indledende HTML, så crawlere kan ikke se dem. Behold SEO-relevant indhold i den normale gengivelse. Brug dynamiske øer til det, der kan komme efter sideskallen: kontolinks, kurvstatus, anbefalinger og adgangsbegrænsede kontroller. Når hele siden er personlig, f.eks. et kontodashboard, skal du i stedet angive dens sti i dynamicPaths og gengive den direkte.

Næste trin