Layout exclusivo por URL

O Design Studio resolve o layout de uma página em dois níveis: template e URL. Esta página explica como esse modelo funciona, o que a agência precisa (e o que não precisa) configurar no tema, e como o comportamento se reflete em publicação, agendamento e histórico.

Pré-requisitos de leitura: Design Studio - Visão Geral, pages.json e Blocks.

O problema que essa funcionalidade resolve

Um template de hotsite pode atender várias URLs ao mesmo tempo. É o caso clássico de um hotsite de categoria: um custom com urlMatch: "calca|camiseta|blazer|saias" faz com que quatro URLs diferentes sejam renderizadas pelo mesmo arquivo .html.

Até então, o layout de CMS era salvo apenas por template. Consequência: adicionar um banner no template "roupas" colocava o mesmo banner em /calca, /camiseta, /blazer e /saias. Não havia como dar a /camiseta um banner próprio sem criar um template separado só para ela.

Com o layout exclusivo por URL, o lojista pode desvincular uma URL específica do template e editar apenas ela — mantendo todas as outras URLs herdando o template normalmente.

O modelo: template x URL

Cada layout salvo no Design Studio tem um escopo:

Os dois escopos coexistem e são versionados de forma independente. Criar um layout exclusivo para /camiseta não altera, não desativa e não substitui o layout do template — ele apenas passa a ter precedência para aquela URL.

Ordem de resolução

Na renderização de uma página, o Storefront resolve o layout nesta ordem:

1. Layout exclusivo da URL, se existir e estiver vigente;
2. Layout do template (o layout "de todas as páginas");
3. Os fallbacks já existentes da plataforma (branch / global).

"Vigente" significa: layout ativo e dentro da janela de agendamento (data de início e fim). Havendo mais de um candidato no mesmo nível, vence o mais recente.

Regra crítica: especificidade vence recência

Se uma URL tem layout exclusivo, publicar uma versão nova no template não afeta essa URL — mesmo que a publicação do template seja muito mais recente.

Isso é intencional: uma personalização feita de propósito para uma página não pode ser silenciosamente apagada por uma publicação de template. A única forma de fazer aquela URL voltar a acompanhar o template é revinculá-la (ver adiante).

URLs novas herdam o template automaticamente

Se uma URL nova passar a casar com o urlMatch do template depois de o layout ter sido publicado (por exemplo, uma subcategoria criada semanas depois), ela já nasce herdando o layout do template. Nenhuma ação é necessária, nem no Admin nem no tema.

O que a agência precisa fazer no tema

Nada além do que já é necessário para habilitar o CMS na página.

Não existe propriedade nova no pages.json, campo novo no schema.json, variável nova no Scriban nem flag para habilitar layout exclusivo. A decisão entre "editar o template" e "editar só esta página" é 100% do lojista, no Admin.

O que precisa estar em pé é o mesmo tripé de sempre:

1. content_for_page no custom que atende as URLs

Declare os blocos permitidos no item de customs responsável pelas URLs em questão. Não precisa ser o custom da home — pode ser qualquer custom de hotsite.

{
  "type": "hotsite",
  "path": "hotsite.html",
  "query": "hotsite.graphql",
  "customs": [
    {
      "urlMatch": "calca|camiseta|blazer|saias",
      "path": "custom/roupas.html",
      "query": "hotsite.graphql",
      "priority": 10,
      "content_for_page": [
        { "type": "banner_button" },
        { "type": "product_carousel" },
        { "type": "image_showcase" }
      ]
    }
  ]
}

2. Os arquivos do bloco em Blocks/

O par Blocks/<type>.html + Blocks/<type>.schema.json de sempre. Os mesmos blocos servem tanto para layouts de template quanto para layouts exclusivos de URL — não há distinção.

3. O ponto de renderização no template

{{ if wake_has_content_for_page }}
    {{ wake_content_for_page }}
{{ else }}
    {{~ # fallback estático do template ~}}
    {{ banners_carousel id: "banners_top" banners: data.hotsite.banners position: "Topo" }}
    {{ spot_carousel products: data.lancamentos.products.nodes title:"Lançamentos" }}
{{ end }}

O wake_content_for_page passa a ser resolvido por URL. Ele renderiza os blocos do layout que venceu a resolução para a URL acessada — exclusivo, se houver; do template, caso contrário.

Mantenha o fallback do else. Em um custom que atende dezenas de URLs, é normal que a maior parte delas fique sem nenhum layout publicado por um bom tempo. Sem fallback, essas páginas renderizam a região de blocos vazia.

O que o override não cobre

O layout exclusivo por URL age apenas na região de blocos do CMS — ou seja, no que é injetado por wake_content_for_page.

Tudo o que está fora dessa região continua sendo resolvido exatamente como antes:

Ou seja: se o objetivo é apenas SEO diferente por URL, isso já funcionava pelo cadastro do hotsite. O layout exclusivo resolve o caso de blocos/banners de CMS diferentes por URL.

A jornada no Admin

Estado inicial: vinculada

Ao abrir o Design Studio em uma URL de um template multi-URL, a página começa vinculada: ela mostra o layout do template e qualquer publicação no template continuará chegando nela.

No painel lateral, o card "Configurações de vínculo" informa o estado atual e oferece a ação disponível.

Desvincular do template

O botão "Desvincular do template" cria um layout exclusivo para aquela URL. A partir daí:

• as edições feitas ali valem somente para aquela URL;
• publicações no template deixam de chegar naquela URL;
• a página passa a exibir o chip "Página desvinculada";
• o seletor de template fica bloqueado para aquela URL, com a mensagem "Esta URL possui layout exclusivo. Para trocar o template, vincule-a novamente."

O diálogo de confirmação lista os efeitos antes de aplicar, e a publicação reforça o impacto: "Esta ação confirmará um layout independente. A página não receberá mais atualizações do template."

Revincular ao template

O botão "Revincular ao template" desfaz a exclusividade: a URL volta a herdar o layout do template.

Comportamento importante:

• Todas as versões vigentes do layout exclusivo daquela URL são desativadas de uma vez — não apenas a última. Sem isso, revincular apenas revelaria a penúltima versão exclusiva em vez de devolver o template.
• A operação é não destrutiva: as versões exclusivas continuam no histórico como rascunho e podem ser reaproveitadas.
• Agendamentos futuros daquela URL não são cancelados. Revincular afeta apenas o que está no ar agora. Se havia uma campanha exclusiva agendada para daqui a duas semanas, ela continua de pé e vai entrar no ar normalmente.

Voltar atrás: restaurar um layout exclusivo antigo

Não existe um botão de "reativar versão". O caminho suportado é o mesmo de qualquer restauração no Design Studio: abrir a versão desejada pelo Histórico e publicá-la de novo. Isso cria uma versão nova, com data nova, que passa a vencer a resolução.

Publicação: quem é afetado

Ao publicar um layout de template, o resumo de publicação informa o alcance real da ação, separando o que vai mudar do que não vai:

As alterações serão aplicadas automaticamente em 12 URLs vinculadas a este template. 3 URLs com layout exclusivo não serão afetadas.

Essa contagem é a tradução direta da regra de especificidade: URLs desvinculadas ficam de fora de qualquer publicação de template, sempre.

Ao publicar um layout exclusivo de URL, o escopo mostrado é a URL única ("Apenas a URL /camiseta").

Agendamento

Agendamentos funcionam nos dois escopos e são independentes entre si.

A detecção de conflito de janela passou a considerar o escopo completo — branch, template e URL:

O último caso é o mais relevante na prática: dá para agendar uma campanha no template inteiro e, simultaneamente, uma campanha diferente só para /camiseta. Quando as duas entrarem no ar, /camiseta exibirá a sua e as demais URLs exibirão a do template.

A tabela de agendamentos ganhou a coluna de escopo — chip "Todas as páginas" ou a URL com o chip "Desvinculada".

O alerta de sempre continua valendo, agora nos dois níveis: ao agendar o término de um layout, garanta que existe outra versão programada para substituí-lo. Caso contrário, a página cai no layout imediatamente anterior — que pode ser antigo.

Histórico e log de atividades

Ambas as telas ganharam a coluna "Páginas Afetadas", que informa o escopo de cada versão:

• chip "Todas as páginas" → versão de template;
• a URL + chip "Desvinculada" → versão exclusiva daquela URL.

O filtro de histórico segue duas semânticas:

• filtrando por uma URL → retorna apenas as versões daquela URL;
• sem filtro de URL → retorna tudo daquele template: as versões de template e as versões exclusivas de todas as URLs. Isso permite auditar o template inteiro em uma tela só.

Referência de contrato

Esta seção é para integrações e diagnóstico. A operação normal é feita pela interface do Design Studio.

Forma canônica da URL

A URL circula em duas formas e a distinção importa:

Regras:

• a normalização é a mesma aplicada no casamento de urlMatch do tema (remoção das barras inicial e final);
• limite de 400 caracteres. Acima disso, a operação é recusada com CMS_URL_EXCEEDS_MAX_LENGTH;
• recomenda-se manter as URLs em minúsculas e consistentes com o cadastro do hotsite;
• uma URL que se reduz a vazio (/ ou string em branco) não é aceita como escopo de override — é recusada com CMS_URL_REQUIRED. Essa é uma proteção deliberada: o layout do template não pode ser despublicado por essa via.

Campos adicionados

Mudança de contrato: o parâmetro previewPage foi removido da consulta de contexto de edição. Ele nunca teve consumidor real e vinha sendo usado indevidamente para definir a URL do preview — papel que agora é do previewUrl na resposta, derivado da url solicitada. Integrações que enviavam previewPage devem parar de enviá-lo.

Cache

A chave de cache de renderização passou a incluir a URL. Um layout exclusivo de uma URL nunca é servido para outra URL nem para o escopo de template.

A invalidação continua acontecendo por branch — publicar ou revincular limpa o cache de todos os templates e URLs daquela branch. Não houve mudança de granularidade aqui.

Ambiente local

O ambiente do Design Studio Local não reproduz layouts exclusivos por URL. Ele lê um único Layouts/<template>.json por template e ignora a URL navegada.

Use o local para validar blocos, schemas e o layout de template. Comportamento de desvincular/revincular, resolução por URL e agendamento por escopo precisam ser validados no Design Studio do Admin.

Checklist de implantação para a agência

• O custom que atende as URLs-alvo tem content_for_page declarado no pages.json.
• Todos os type listados existem como par .html + .schema.json em Blocks/.
• O template renderiza wake_content_for_page com fallback no else.
• O urlMatch do custom cobre exatamente as URLs que devem compartilhar o template — nem mais, nem menos.
• Os hotsites correspondentes estão cadastrados na loja (é o cadastro que popula a lista de URLs no Design Studio).
• Nenhum bloco tem lógica condicional baseada na URL corrente — diferenças por página são resolvidas com layout exclusivo, não com Scriban.
• O lojista foi orientado sobre o efeito de desvincular: aquela URL para de receber publicações do template até ser revinculada.

Perguntas frequentes

Publiquei no template e uma URL não mudou. O que houve?
Essa URL provavelmente está desvinculada. Abra-a no Design Studio: se aparecer o chip "Página desvinculada", ela tem layout exclusivo e não recebe publicações do template. Para voltar a acompanhar, use "Revincular ao template".

Revincular apaga o layout exclusivo que eu tinha feito?
Não. As versões continuam no histórico e podem ser republicadas a qualquer momento.

Preciso criar um template novo para cada URL que quer conteúdo próprio?
Não — e não é recomendado. Esse era justamente o caminho que essa entrega veio substituir. Mantenha um template por padrão de página e use layout exclusivo para as exceções.

Quantas URLs posso desvincular?
Não há limite técnico definido. Mas cada URL desvinculada é uma página que deixa de acompanhar o template — ou seja, mais manutenção manual. Trate exclusividade como exceção, não como regra.

O layout exclusivo muda o SEO da página?
Não. SEO continua vindo do cadastro do hotsite, que já é por URL. O layout exclusivo age apenas na região de blocos do CMS.

Consigo agendar uma campanha só para uma URL?
Sim. Agendamentos de URL e de template são independentes e não conflitam entre si.