Introdução

Gerencie páginas de websites e telas de aplicativos móveis com conteúdo dinâmico.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/pages

---

🎯 O que este módulo faz?

O módulo Pages permite que você recupere e gerencie páginas (para websites) ou telas (para aplicativos móveis) com todo o seu conteúdo - título, conteúdo HTML/texto simples, visibilidade e atributos personalizados. Você cria páginas no painel de administração do OneEntry e as busca dinamicamente em seu aplicativo, de modo que a alteração de conteúdo na administração entra em vigor sem necessidade de reimplantação.

🚀 Início Rápido

Inicialize o módulo a partir de defineOneEntry:

const { Pages } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Recupere uma única página pela sua URL (marcador) e leia seus campos:

// Fetch the "about" page in English.
const page = await Pages.getPageByUrl("about", "en_US");

console.log(page.id, page.localizeInfos.title);
console.log("Visible:", page.isVisible);

// Custom fields you defined live in attributeValues.
console.log(page.attributeValues);

A maioria dos métodos de leitura segue a mesma estrutura: um identificador (url ou id) mais um langCode. Veja a Tabela de Referência Rápida abaixo para o conjunto completo.

✨ Conceitos Chave

O que é uma Página?

Uma página é uma entidade de conteúdo que representa:

• Web: Uma página no seu site (por exemplo, /sobre, /contato)
• Móvel: Uma tela no seu aplicativo (por exemplo, Tela de Perfil, Tela de Configurações)

Cada página contém:

• Conteúdo - título e conteúdo HTML/texto simples via localizeInfos
• URL - pageUrl, o marcador da página usado para roteamento e buscas
• Visibilidade - a flag isVisible
• Atributos personalizados - quaisquer campos adicionais que você definir em attributeValues (meta SEO é modelada como atributos personalizados, não como um campo embutido)
• Localização - conteúdo multilíngue

Tipos de Página

O OneEntry suporta diferentes tipos de página (type), sendo os mais comuns:

Tipo	Valor de type	Uso Exemplo
Página Comum	common_page	Sobre, Contato, Termos
Página de Catálogo	catalog_page	Categorias de catálogo
Página Externa	external_page	Links para URLs externas
Página de Erro	error_page	Página 404 / Não Encontrada

A lista completa de tipos está disponível através do módulo GeneralTypes.

Hierarquia de Páginas

As páginas são organizadas em uma árvore através de parentId (páginas de nível superior têm parentId: null):

📁 Company
  ├─ About Us
  ├─ Team
  └─ Careers

📁 Products
  ├─ Product Category 1
  │   ├─ Product A
  │   └─ Product B
  └─ Product Category 2

Você pode buscar páginas raiz com getRootPages() e descer com getChildPagesByParentUrl().

📋 O que você precisa saber

Duas maneiras de identificar páginas

Método	Quando usar	Exemplo
Por URL	O usuário visita uma página específica	getPageByUrl("sobre")
Por ID	Referências internas	getPageById(123)

Melhor prática: o pageUrl é um marcador estável - não é um caminho de rota do Next.js. Passe o marcador do OneEntry (por exemplo, "sobre"), não /pt/sobre.

Estrutura da Página

Cada página tem esses campos principais:

{
  "id": 9,
  "parentId": 8,
  "pageUrl": "blog1",
  "depth": 1,
  "localizeInfos": {
    "title": "Blog 1",
    "menuTitle": "Blog 1",
    "htmlContent": "",
    "plainContent": ""
  },
  "isVisible": true,
  "blocks": [],
  "type": "common_page",
  "templateIdentifier": null,
  "attributeSetIdentifier": null,
  "attributeValues": {},
  "isSync": false
}

Configurações de Exibição

As páginas de catálogo carregam suas configurações de saída na própria entidade da página, no campo opcional config (Record<string, number>) - por exemplo, rowsPerPage e productsPerRow:

const page = await Pages.getPageByUrl("catalog");

const rows = page.config?.rowsPerPage;
const perRow = page.config?.productsPerRow;

⚠️ Migração: o método separado getConfigPageByUrl() foi removido - a API descartou o endpoint GET /api/content/pages/{url}/config e agora responde com 404. O tipo IPageConfig também foi removido. Leia os mesmos valores de page.config, que cada método de página já retorna.

Localização

As páginas suportam múltiplos idiomas - solicite um langCode diferente para obter a mesma página em outro idioma.

Atributos Personalizados

Adicione quaisquer campos às páginas usando AttributesSets - autor/data/tags de postagens de blog, imagens de herói de landing page, meta SEO, e assim por diante. Leia-os de page.attributeValues. Saiba mais: Módulo AttributesSets.

Visibilidade

Use a flag isVisible para controlar quais páginas são mostradas aos usuários - filtre por isVisible: true em produção.

---

📊 Tabela de Referência Rápida - Métodos Comuns

Método	O que faz	Quando usar
getPages()	Obtém todas as páginas	Construir sitemap, listar todas as páginas
getRootPages()	Obtém todas as páginas de nível superior	Construir navegação de nível superior
getChildPagesByParentUrl()	Obtém páginas filhas por URL pai	Navegar pela subárvore de uma seção
getBlocksByPageUrl()	Obtém objetos PositionBlock para uma página por URL	Renderizar blocos de conteúdo da página
getPageById()	Obtém uma única página por ID	Referências internas
getPageByUrl()	Obtém uma única página por URL	Renderizar uma página em uma rota
searchPage()	Busca rápida por páginas	Buscar páginas por título
getPagesByVectorSearch()	Busca semântica (vetorial) por páginas	Combinar páginas por significado, não por palavras-chave

❓ Perguntas Comuns (FAQ)

Qual é a diferença entre URL e ID?

• pageUrl - o marcador da página usado para roteamento (por exemplo, "sobre"). Visível para o usuário e estável entre ambientes.
• id - o identificador numérico. Usado para referências internas.

---

Como faço para construir a navegação a partir das páginas?

Use getRootPages() para entradas de nível superior e getChildPagesByParentUrl() para descer na árvore, ou use o módulo Menus dedicado para estruturas de navegação gerenciadas.

---

Como faço para adicionar metadados de SEO a uma página?

SEO não é um campo embutido - modele o título/meta descrição/etc. como atributos personalizados em um AttributesSet, e depois leia-os de page.attributeValues.

---

🎓 Melhores Práticas

• Use pageUrl (o marcador) para roteamento - nunca codifique um caminho de rota de framework como a URL.
• Filtre por isVisible: true para produção.
• Armazene em cache as páginas para reduzir chamadas à API; trate 404s (página não encontrada) de forma elegante.
• Leia dados personalizados de attributeValues em vez de assumir campos embutidos.

---

🔗 Documentação Relacionada

• Módulo Products - Gerencie produtos de e-commerce
• Módulo Blocks - Blocos de conteúdo reutilizáveis para páginas
• Módulo AttributesSets - Campos personalizados para páginas
• Módulo Menus - Gerenciamento de menus de navegação
• Módulo GeneralTypes - Tipos de página

---