pages.json

O arquivo pages.json contém as definições de todas as páginas do site dentro da pasta Pages, na raíz do projeto.
Nela é possível configurar o tipo de página, o arquivo .html dentro de Pages e qual o arquivo .graphql dentro de Queries a ser utilizado, além de customizações.

Estrutura base

A estrutura base é a seguinte:

{
    "type": "search",
    "path": "search.html",
    "query": "search.graphql"
}

Propriedade customs (array)

Existe a possibilidade de customizar a página a ser renderizada de acordo com regras específicas. Basta nomear um array customs e inserir as seguintes regras:

Para o tipo hotsite

Para páginas do tipo hotsite é possível inserir um objeto contendo as propriedades:

Propriedades opcionais

• path
• query

Caso sejam informados, serão os arquivos .html e .graphql a serem renderizados, respectivamente. Caso não sejam informados, serão renderizados os arquivos especificados nas propriedades path e query principais.

Exemplo:

{
    "type": "hotsite",
    "path": "hotsite.html",
    "query": "hotsite.graphql",
    "customs": [
        {
            "urlMatch": "",
            "path": "home.html",
            "query": "home.graphql"
        },
        {
            "urlMatch": "listadedesejos",
            "path": "custom/wishlist.html"
        },
        {
            "urlMatch": "*",
            "subtype": "brand",
            "path": "custom/brands.html",
            "priority": 10
        },
        {
            "urlMatch": "*vans*",
            "path": "custom/vans.html",
            "priority": 20
        },
        {
            "urlMatch": "outlet*|black-friday",
            "path": "custom/promo.html"
        },
        {
            "urlMatch": "mycategory",
            "subtype": "category",
            "path": "category.html"
        }
    ]
}

Para o tipo product

Para páginas do tipo product é possível inserir um objeto semelhante ao de hotsite, mas sem a propriedade subtype, pois é exclusiva de páginas desse tipo.
Existem propriedades extras exclusivas para o tipo product:

• productIds: um array de IDs de produtos que serão utilizados para dar match e utilizar a regra especificada.
• categoryIds: um array de IDs de categorias que segue o mesmo intuito de productIds, mas para categorias.

As propriedades opcionaispath e query também são válidas e seguem as mesmas regras do tipo hotsite.

Exemplo:

{
    "type": "product",
    "path": "product.html",
    "query": "product.graphql",
    "customs": [
        {
            "urlMatch": "kit-pratico*",
            "path": "custom/custom_product.html",
            "priority": 1
        },
        {
            "productIds": [9, 222],
            "path": "custom/custom_product.html",
            "priority": 2
        },
        {
            "categoryIds": [473],
            "path": "custom/custom_product.html",
            "priority": 10
        }
    ]
}

Pages no Storefront 2.0

Com o lançamento do Storefront 2.0, em que o checkout também é altamente customizável, foi incluído outros tipos de páginas dentro do pages.json as quais podem ser consultadas por meio desta documentação.

Desing Studio (CMS)

Nesta primeira versão, em páginas do tipo hotsite, a propriedade content_for_page deve ser adicionada no item de customs responsável pela home. Essa propriedade define quais blocos podem ser usados no CMS daquela página.

No contrato atual, cada item de content_for_pageaceita:

• type: identificador do bloco aceito na página.

Esse valor deve corresponder ao:

• type declarado no arquivo Blocks/<type>.schema.json
• nome base do arquivo Blocks/<type>.html
• nome base do arquivo Blocks/<type>.schema.json

Exemplo:

No exemplo abaixo, a home da loja aceita cinco tipos de blocos no CMS:

{
  "type": "hotsite",
  "path": "hotsite.html",
  "query": "hotsite_with_cursor.graphql",
  "customs": [
    {
      "urlMatch": "",
      "path": "home.html",
      "query": "home.graphql",
      "content_for_page": [
        { "type": "banner_button" },
        { "type": "product_carousel" },
        { "type": "banner_carousel" },
        { "type": "button_carousel" },
        { "type": "image_showcase" }
      ]
    }
  ]
}

Como interpretar

• content_for_page não cria o bloco por si só. Ele apenas informa quais tipos de bloco a página aceita.
• Cada type listado deve existir na pasta Blocks.
• Nesta primeira versão, o content_for_page deve ficar no customda home, isto é, no item com urlMatch: "".
• Se um bloco for listado em content_for_page, mas o schema correspondente não existir ou estiver inválido, o salvamento do CMS será rejeitado.

Escopo: em quais customs o content_for_page pode ser declarado

O content_for_page pode ser declarado em qualquer item de customs de uma página do tipo hotsite — não apenas no custom da home.

Isso vale tanto para um custom que atende uma única URL quanto para um custom cujo urlMatch atende várias URLs ao mesmo tempo:

{
  "type": "hotsite",
  "path": "hotsite.html",
  "query": "hotsite.graphql",
  "customs": [
    {
      "urlMatch": "",
      "path": "home.html",
      "query": "home.graphql",
      "content_for_page": [
        { "type": "banner_carousel" },
        { "type": "product_carousel" }
      ]
    },
    {
      "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" }
      ]
    }
  ]
}

No exemplo acima, /calca, /camiseta, /blazer e /saias são atendidas pelo mesmo custom — portanto pelo mesmo template (custom/roupas.html) — e todas oferecem no Design Studio os mesmos três tipos de bloco.

O urlMatch define o universo de URLs do template

O layout de CMS é salvo por template, e o urlMatch é o que determina quais URLs reais da loja caem naquele template. Por consequência:

• um urlMatch que casa com muitas URLs cria um template que atende muitas URLs, e o layout salvo nele vale para todas elas;
• a lista de URLs que o lojista vê no Design Studio para aquele template é montada a partir dos hotsites cadastrados na loja cuja URL casa com esse urlMatch (respeitando também subtype e priority);
• uma URL cadastrada depois de o layout ter sido salvo passa a herdar o layout do template automaticamente, sem nenhuma ação adicional.

Layout exclusivo por URL

A partir da entrega de layout exclusivo por URL, o lojista pode desvincular uma URL específica do template e dar a ela um layout próprio, sem que isso afete as demais URLs do mesmo urlMatch.

Do lado do tema não há nada a configurar para habilitar isso: basta que o custom tenha content_for_page e que a página renderize wake_content_for_page. A escolha entre "editar o template" e "editar só esta página" é feita pelo lojista no Design Studio.

O que muda é a ordem de resolução do layout na renderização:

1. layout exclusivo daquela URL, se existir e estiver vigente;
2. layout do template (vale para todas as URLs do urlMatch);
3. os fallbacks já existentes.

Especificidade vence recência: se /camiseta tem layout exclusivo, uma publicação nova no template não sobrescreve /camiseta. Ela continua com o layout exclusivo até que alguém a revincule ao template pelo Design Studio.

Detalhes completos do comportamento, do fluxo de desvincular/revincular e dos impactos em histórico e agendamento estão em Design Studio — Layout exclusivo por URL.

Como usar na página

Além de configurar o content_for_page no pages.json, a página precisa prever o ponto onde os blocos CMS serão renderizados.

O padrão recomendado é:

• usar wake_has_content_for_page para verificar se existem blocos CMS salvos para aquela renderização

• usar wake_content_for_page para renderizar os blocos na ordem em que foram salvos.

  O content_for_page pode ser declarado em dois níveis:

  • No item de customs — vale para as URLs atendidas por aquele custom.
  • No nível da página (ex.: no objeto hotsite) — vale para as URLs atendidas pelo template base da página; também é usado como fallback quando o custom correspondente não declara content_for_page próprio.

• manter um fallback com o conteúdo estático original da página, quando isso fizer sentido para o template

Exemplo prático com Pages/home.html

{{ if wake_has_content_for_page }}
    {{ wake_content_for_page }}
{{ else }}
    {{ banners_carousel id: "banners_top" banners: data.hotsite.banners position: "Topo" }}
    {{ spot_carousel products: data.lancamentos.products.nodes class:"new-release" title:"Lançamentos" }}
    {{ spot_carousel products: data.mais_vendidos.products.nodes class:"best-sellers" title:"Mais Vendidos" }}
    {{ newsletter information_groups: data.newsletter_information_group_fields }}
    {{ brands_carousel brands: data.brands.nodes }}
{{ end }}

O que esse exemplo faz:

• Se existirem blocos CMS carregados na página, wake_content_for_page renderiza esses blocos.
• Se não existirem blocos CMS, a página continua exibindo os componentes padrão do template.
• Esse formato é útil para páginas como a home, em que o template já possui uma composição padrão e a agência quer migrar gradualmente para blocos CMS.

Significado das variáveis

• wake_has_content_for_page: fica true quando a página possui pelo menos um bloco.
• wake_content_for_page: percorre os blocos salvos e renderiza o arquivo Blocks/<type>.html correspondente a cada item.

Quando usar fallback
Use o else com conteúdo estático quando:

• a página já possui uma estrutura legada que deve continuar funcionando sem configuração CMS
• a agência quer liberar o CMS sem perder a composição atual da página
• o template precisa funcionar corretamente mesmo antes do primeiro bloco ser cadastrado

Atenção em templates que atendem várias URLs

Quando o mesmo custom atende várias URLs, o wake_content_for_page é resolvido por URL na renderização: cada URL recebe o seu layout exclusivo, se tiver um, ou o layout do template, se não tiver.

Duas consequências práticas para o template:

• O fallback do else continua sendo importante. URLs sem layout exclusivo e sem layout de template caem no fallback estático. Em um custom que atende dezenas de URLs, é normal que a maior parte delas fique nessa situação por um bom tempo.
• O que está fora do bloco wake_content_for_page não é afetado. O override por URL age apenas na região de blocos do CMS. SEO, banners vindos da query do hotsite e qualquer markup fixo do template continuam sendo resolvidos como sempre foram — o SEO, inclusive, já é por URL, porque vem do cadastro do hotsite.