Treci la conținut

Fragmente personalizate pe pagini memorate în cache

O pagină servită dintr-un cache static este identică pentru toată lumea. Acesta este scopul memorării în cache și totodată problema: antetul trebuie să afișeze „Salut, Ada” pentru un client autentificat, iar pictograma coșului trebuie să arate trei produse. Dacă șablonul afișează conținut diferit în funcție de utilizatorul curent, cache-ul fie stochează salutul unui vizitator pentru toată lumea, fie trebuie să excludă complet pagina.

Insulele dinamice ale Blockstudio separă aceste două preocupări. HTML memorat în cache conține un substituent sigur pentru cache. După încărcarea paginii, un runtime simplu cere WordPress fragmentul personalizat în cererea proprie a vizitatorului și îl inserează. Pagina rămâne eligibilă pentru memorarea în cache, iar doar fragmentul este dinamic.

Acest ghid construiește două insule, un salut și un număr de produse în coș, și explică ce conține pagina memorată în cache, cum arată cererea pentru fragment și cum stabilește endpointul cine este vizitatorul. Ghidul completează Servirea WordPress ca HTML static .

Cum funcționează o insulă dinamică

  1. Blocul își randează substituentul într-un element marcator. Marcatorul conține numele blocului, atributele permise și o semnătură generată de server.
  2. Deoarece pagina randată conține un marcator, Blockstudio inserează runtime-ul insulelor. Paginile fără insule nu includ niciun JavaScript pentru insule.
  3. Runtime-ul colectează marcatorii pregătiți și trimite o singură cerere POST grupată către /wp-json/blockstudio/v1/island/render.
  4. Endpointul verifică fiecare semnătură, randează blocul în contextul cererii vizitatorului și returnează fragmentele.
  5. Runtime-ul înlocuiește fiecare substituent și declanșează evenimente.

În editorul de blocuri, blocul se randează normal, fără substituent.

Pasul 1: Blocul de salut

Creați blocul cu trei fișiere:

Cod
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" este ceea ce transformă acest bloc într-o insulă care face o cerere pentru fragment. tag stabilește elementul marcator, astfel încât insula să poată apărea în linie într-o bară de navigare. attributes este lista atributelor blocului permise, care sunt transmise odată cu cererea pentru fragment; orice element nelistat nu este trimis și nici semnat. cache este descris mai jos.

Substituentul apare pe pagina memorată în cache. Trebuie să poată fi afișat tuturor vizitatorilor, deci nu conține date despre utilizator. O legătură „Cont” este potrivită pentru toată lumea:

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

Șablonul principal randează fragmentul real:

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

Este în regulă să afișați conținut diferit în funcție de utilizatorul curent aici: acest șablon rulează doar pentru cererea fragmentului, niciodată pentru pagina memorată în cache.

Plasați-l oriunde este randat antetul:

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

Etichetele de bloc funcționează și ele: <bs:acme-greeting /> sau <block name="acme/greeting" />.

Pasul 2: Ce conține pagina memorată în cache

Randat pe server, blocul produce doar marcatorul și substituentul:

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>

Randați-l o dată ca vizitator anonim și o dată ca utilizator autentificat, iar cele două șiruri vor fi identice la nivel de octet. Aceasta este exact proprietatea necesară pentru o prerandare statică cu serveLoggedIn activată: indiferent cine declanșează randarea, documentul stocat este același și nicio informație personală nu poate ajunge în el.

Pasul 3: Cererea pentru fragment

Runtime-ul trimite toate insulele pregătite într-o singură cerere:

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

Răspunsul este indexat după clientId. Pentru un vizitator autentificat:

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

O intrare care nu trece verificarea este returnată ca un cod de eroare în loc de HTML, fără a afecta restul grupului. Aici, a doua intrare a modificat guestLabel fără o semnătură corespunzătoare, iar a treia a specificat un bloc care nu este o insulă dinamică:

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"
    }
}

Fiecare răspuns conține Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache și X-Robots-Tag: noindex. Endpointul se află sub /wp-json, pe care prerandarea statică îl ocolește întotdeauna, astfel încât nici cache-ul de origine, nici un CDN care respectă antetele de origine nu va stoca un fragment.

Cine este vizitatorul

Runtime-ul trimite cererea cu credentials: 'same-origin', astfel încât browserul include cookie-ul de autentificare WordPress. În mod normal, WordPress REST API ignoră autentificarea prin cookie fără un nonce, iar un nonce nu poate exista pe o pagină memorată în cache. Endpointul insulei gestionează singur această situație: pentru o cerere de browser de aceeași origine, validează cookie-ul logged_in și restabilește acel utilizator înainte de randare.

Originea identică este stabilită pe baza antetului Sec-Fetch-Site și, dacă este prezent, a antetului Origin, comparat cu home_url(). O cerere dintr-o altă origine care, întâmplător, conține cookie-ul este randată ca anonimă, astfel încât o cerere de pe alt site nu afișează niciodată fragmentul personal al vizitatorului. În practică:

Cerere Randat ca
Cerere fetch de aceeași origine cu un cookie de autentificare valid utilizatorul autentificat
Cerere din altă origine cu același cookie anonim
Fără cookie anonim

Despre ce pagină este vorba?

Adăugați "context": true la blockstudio.island când fragmentul are nevoie de identitatea paginii sale. Marcajul semnează apoi ID-ul postării și tipul postării paginii interogate, alături de atribute. În fragment, $block['postId'], $block['postType'], get_the_ID() și get_queried_object_id() se referă la pagina respectivă. Într-un Query Loop, aceasta înseamnă în continuare pagina exterioară interogată, nu elementul din buclă.

Contextul paginii este opțional și face parte, de asemenea, din cheia cache-ului fragmentului. Endpointul verifică din nou accesul, chiar și pentru fragmentele din cache, astfel încât un marker semnat nu expune o pagină care între timp a devenit privată sau protejată prin parolă. Consultați Contextul paginii pentru detalii despre configurare și securitate. Nu sunt reluate valori URL arbitrare sau parametri de interogare.

Pasul 4: Un număr de produse în coș care se reîmprospătează automat

A doua insulă arată celălalt stil de substituent și două opțiuni de runtime. În locul unui fișier separat pentru substituent, șablonul verifică $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; ?>

Aceleași opțiuni există în fiecare limbaj de șabloane: isIsland, isIslandPlaceholder, isIslandFragment și islandPhase ("normal", "hydrate", "placeholder" sau "fragment"). Aici, numărul provine dintr-un filtru acme/cart_count pe care îl completează codul magazinului; dacă acesta returnează 3, endpointul răspunde:

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" amână cererea până când marcatorul intră în zona vizibilă, folosind IntersectionObserver. Insulele vizibile care apar simultan sunt tot grupate într-o singură cerere. event denumește un eveniment de fereastră care repreia insula, astfel încât după un apel de adăugare în coș, scriptul trebuie doar să îl semnaleze:

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

Reacția în codul frontend

Evenimentele se propagă de la marker, așa că un singur ascultător pe document acoperă fiecare insulă. event.detail.name conține numele blocului:

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

După o înlocuire, mediul de execuție trimite blockstudio:island:rendered, apoi blockstudio:island:hydrate. În caz de eșec, substituentul rămâne pe loc și se declanșează blockstudio:island:error. Insulele hidratate ("island": "hydrate") omit complet solicitarea: întregul lor HTML este în pagină și primesc doar evenimentul hydrate, ceea ce se potrivește blocurilor interactive compatibile cu memoria cache, cum ar fi filele.

Memorarea în cache a fragmentelor

În mod implicit, fragmentele sunt randate la fiecare solicitare. Mesajul de salut de mai sus optează pentru o perioadă scurtă de memorare în cache:

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

per: "user" variază fragmentul memorat în cache în funcție de ID-ul utilizatorului WordPress, iar solicitările anonime nu sunt niciodată memorate în cache pe baza acestuia, astfel încât doi vizitatori anonimi nu pot partaja o intrare destinată unui utilizator. per: "global" partajează un fragment pentru același bloc și aceleași atribute, ceea ce se potrivește conținutului actualizat, dar nepersonal, cum ar fi nivelul stocului. ttl are valoarea implicită de 60 de secunde, iar cache: true este o memorie cache globală de 60 de secunde.

Modelul de securitate

Punctul final este public, dar nu este un serviciu general de randare a blocurilor. Randează o intrare numai dacă sunt îndeplinite toate condițiile următoare:

  • blocul este înregistrat, dinamic și are island.mode setat la dynamic
  • semnătura corespunde numelui blocului și atributelor care trec filtrul: numai cheile prezente atât în schema blocului, cât și în lista permisă pentru insulă

Semnătura este un HMAC-SHA256 calculat pentru numele normalizat al blocului și atribute, cu cheia formată din sarea auth a site-ului care le servește. Semnăturile sunt create la randare pe acel site și nu sunt niciodată încorporate într-o temă. Urmează două consecințe. Un document randat pe mediul de testare conține semnături de testare, așa că randați documentele pe site-ul care le servește. Iar rotirea sărurilor WordPress invalidează fiecare semnătură din documentele stocate, așa că ștergeți prerandarea statică după rotirea unei sări.

O solicitare acceptă până la 50 de insule; pentru mai multe, se returnează HTTP 413. Modificați limita cu blockstudio/islands/max_per_request. Sunt disponibile hookuri pentru semnături (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) pentru gazdele care au nevoie de o schemă diferită.

Când să nu folosiți o insulă

Fragmentele nu sunt incluse în HTML inițial, așa că motoarele de căutare nu le văd. Păstrați conținutul relevant pentru SEO în randarea obișnuită. Folosiți insule dinamice pentru conținutul care poate apărea după structura de bază a paginii: linkuri către cont, starea coșului, recomandări și controale condiționate de permisiuni. Când întreaga pagină este personalizată, cum ar fi un tablou de bord al contului, enumerați calea acesteia în dynamicPaths și randați-o în timp real.

Pașii următori