Pular para o conteúdo

Fragmentos personalizados em páginas em cache

Uma página servida a partir de um cache estático é igual para todos. Esse é o objetivo do cache, mas também é o problema: o cabeçalho quer dizer “Oi, Ada” a um cliente com sessão iniciada, e o ícone do carrinho quer mostrar três itens. Se o template variar conforme o usuário atual, o cache armazenará a saudação de um visitante para todos ou terá de ignorar a página por completo.

As ilhas dinâmicas de Blockstudio separam essas duas preocupações. O HTML em cache contém um espaço reservado seguro para cache. Depois que a página carrega, um pequeno runtime solicita a WordPress o fragmento personalizado na própria requisição do visitante e o substitui. A página continua podendo ser armazenada em cache, e somente o fragmento é dinâmico.

Este guia cria duas ilhas, uma saudação e uma contagem do carrinho, e explica o que a página em cache contém, como é a solicitação do fragmento e como o endpoint identifica o visitante. Ele complementa Servir WordPress como conteúdo HTML estático.

Como funciona uma ilha dinâmica

  1. O bloco renderiza seu espaço reservado dentro de um elemento marcador. O marcador contém o nome do bloco, os atributos permitidos e uma assinatura gerada pelo servidor.
  2. Como a página renderizada contém um marcador, Blockstudio insere o runtime da ilha. Páginas sem ilhas não incluem nenhum JavaScript de ilha.
  3. O runtime reúne os marcadores prontos e envia uma única solicitação POST em lote para /wp-json/blockstudio/v1/island/render.
  4. O endpoint verifica cada assinatura, renderiza o bloco no contexto da solicitação do visitante e retorna os fragmentos.
  5. O runtime substitui cada espaço reservado e dispara eventos.

No editor de blocos, o bloco é renderizado normalmente, sem espaço reservado.

Etapa 1: o bloco de saudação

Crie o bloco com três arquivos:

Código
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" é o que transforma isso em uma ilha com uma solicitação de fragmento. tag define o elemento marcador, permitindo que a ilha apareça em linha na barra de navegação. attributes é a lista de atributos de bloco permitidos que acompanham a solicitação de fragmento; tudo que não estiver listado não será enviado nem assinado. cache será explicado mais adiante.

A página em cache contém o espaço reservado. Ele precisa ser seguro para exibição a todos os visitantes, por isso não contém dados de usuário. Um link “Conta” funciona para todos:

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

O template principal renderiza o fragmento 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; ?>

É possível fazer uma ramificação com base no usuário atual aqui: esse template só é executado para a solicitação do fragmento, nunca para a página em cache.

Coloque-o onde o cabeçalho é renderizado:

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

As tags de bloco também funcionam: <bs:acme-greeting /> ou <block name="acme/greeting" />.

Etapa 2: o conteúdo da página em cache

Renderizado no servidor, o bloco produz apenas o marcador e o espaço reservado:

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>

Renderize uma vez como visitante anônimo e outra como usuário com sessão iniciada, e as duas strings serão idênticas byte a byte. Essa é exatamente a propriedade necessária para uma pré-renderização estática com serveLoggedIn habilitado: quem quer que inicie a renderização, o documento armazenado será igual e nada pessoal poderá acabar nele.

Etapa 3: a solicitação do fragmento

O runtime envia todas as ilhas prontas em uma única solicitação:

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

A resposta é indexada por clientId. Para um visitante com sessão iniciada:

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

Uma entrada que falha na verificação retorna um código de erro em vez de HTML, sem fazer o restante do lote falhar. Aqui, a segunda entrada alterou guestLabel sem uma assinatura correspondente, e a terceira indicou um bloco que não é uma ilha dinâmica:

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

Cada resposta contém Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache e X-Robots-Tag: noindex. O endpoint fica em /wp-json, que a pré-renderização estática sempre ignora; assim, nem o cache de origem nem uma CDN que respeite os cabeçalhos da origem armazenará um fragmento.

Quem é o visitante

O runtime envia a solicitação com credentials: 'same-origin', para que o navegador inclua o cookie de login WordPress. Normalmente, WordPress REST API ignora a autenticação por cookie sem um nonce, e um nonce não pode estar em uma página em cache. O endpoint da ilha cuida disso: em uma solicitação do navegador com a mesma origem, valida o cookie logged_in e restaura esse usuário antes da renderização.

A mesma origem é determinada pelo cabeçalho Sec-Fetch-Site e, quando presente, pelo cabeçalho Origin comparado com home_url(). Uma solicitação de outra origem que por acaso inclua o cookie é renderizada como anônima, então uma solicitação de outro site nunca renderiza o fragmento personalizado de um visitante. Na prática:

Solicitação Renderiza como
Busca da mesma origem com um cookie de login válido usuário com sessão iniciada
Solicitação de outra origem com o mesmo cookie anônimo
Sem cookie anônimo

Qual é esta página?

Adicione "context": true a blockstudio.island quando o fragmento precisar da identidade da página. O marcador então assina o ID e o tipo de post da página consultada junto com os atributos. No fragmento, $block['postId'], $block['postType'], get_the_ID() e get_queried_object_id() se referem a essa página. Dentro de um loop de consulta, isso ainda significa a página externa consultada, e não o item do loop.

O contexto da página é opcional e também faz parte da chave do cache de fragmentos. O endpoint verifica o acesso novamente, mesmo para fragmentos em cache, para que um marcador assinado não exponha uma página que se tornou privada ou protegida por senha. Consulte Contexto da página para ver os detalhes de configuração e segurança. Nenhum parâmetro arbitrário de URL ou de consulta é reproduzido.

Etapa 4: uma contagem do carrinho que se atualiza sozinha

A segunda ilha mostra o outro estilo de espaço reservado e duas opções de runtime. Em vez de um arquivo de espaço reservado separado, o template verifica $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; ?>

Os mesmos sinalizadores existem em todas as linguagens de template: isIsland, isIslandPlaceholder, isIslandFragment e islandPhase ("normal", "hydrate", "placeholder" ou "fragment"). Aqui, a contagem vem de um filtro acme/cart_count que seu código de comércio preenche; quando retorna 3, o endpoint retorna:

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" adia a solicitação até o marcador entrar na área visível, usando IntersectionObserver. Ilhas visíveis que aparecem juntas ainda são agrupadas em uma única solicitação. event especifica um evento de janela que atualiza a ilha, então, após uma chamada de adicionar ao carrinho, seu script só precisa anunciá-lo:

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

Reagindo no código do frontend

Os eventos se propagam a partir do marcador, então um único ouvinte em document cobre todas as ilhas. event.detail.name contém o nome do bloco:

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

Depois de uma troca, o runtime dispara blockstudio:island:rendered e, em seguida, blockstudio:island:hydrate. Em caso de falha, o espaço reservado permanece no lugar e blockstudio:island:error é disparado. Ilhas hidratadas ("island": "hydrate") ignoram a solicitação por completo: seu HTML completo já está na página e elas recebem apenas o evento hydrate, o que funciona bem para blocos interativos seguros para cache, como abas.

Cache de fragmentos

Por padrão, os fragmentos são renderizados a cada solicitação. A saudação acima opta por um cache curto:

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

per: "user" varia o fragmento em cache de acordo com o ID do usuário WordPress, e as solicitações anônimas nunca são armazenadas nele, evitando que dois visitantes anônimos compartilhem uma entrada destinada a um usuário. per: "global" compartilha um fragmento para o mesmo bloco e os mesmos atributos, o que funciona bem para conteúdo atualizado, mas não pessoal, como o nível de estoque. ttl tem como padrão 60 segundos, e cache: true é um cache global de 60 segundos.

O modelo de segurança

O endpoint é público, mas não é um renderizador genérico de blocos. Ele só renderiza uma entrada quando todos estes requisitos são atendidos:

  • o bloco está registrado, é dinâmico e tem island.mode definido como dynamic
  • a assinatura corresponde ao nome do bloco e aos atributos que passam pelo filtro: somente chaves presentes tanto no esquema do bloco quanto na lista de permissões da ilha

A assinatura é um HMAC-SHA256 calculado sobre o nome normalizado do bloco e seus atributos, com o salt auth do site que o serve como chave. As assinaturas são criadas no momento da renderização nesse site e nunca são incluídas em um tema. Isso tem duas consequências. Um documento renderizado em staging contém assinaturas de staging, então renderize os documentos no site que os serve. E a rotação dos salts WordPress invalida todas as assinaturas nos documentos armazenados, então limpe o pré-render estático depois de uma rotação de salt.

Uma solicitação aceita até 50 ilhas; acima disso, retorna HTTP 413. Altere o limite com blockstudio/islands/max_per_request. Há hooks de assinatura (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) para hosts que precisam de um esquema diferente.

Quando não usar uma ilha

Os fragmentos não fazem parte do HTML inicial, então os rastreadores não os veem. Mantenha o conteúdo relevante para SEO na renderização normal. Use ilhas dinâmicas para o que pode chegar depois do shell da página: links de conta, estado do carrinho, recomendações e controles restritos por permissões. Quando a página inteira for pessoal, como um painel de conta, liste seu caminho em dynamicPaths e renderize-a ao vivo.

Próximas etapas