Saltar al contenido principal

Introducción

Recupera menús de navegación de sitio de múltiples niveles construidos a partir de páginas configuradas en OneEntry.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/menu

🎯 ¿Qué hace este módulo?​

El módulo Menus te permite recuperar estructuras de navegación del sitio - menús de encabezado, menús de pie de página, navegación de barra lateral, menús móviles - construyendo dinámicamente navegación de múltiples niveles a partir de páginas configuradas en OneEntry.

Creas menús en el panel de administración de OneEntry (uniendo páginas) y este módulo recupera el árbol completo del menú, para que puedas renderizar la navegación dinámicamente sin codificar enlaces. El SDK es solo de lectura para menús - los recuperas, no los creas a través del código.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Recupera un menú por su marcador y recorre sus páginas:

// Fetch the "main_menu" structure in English.
const menu = await Menus.getMenusByMarker("main_menu", "en_US");

console.log(menu.identifier, menu.localizeInfos.title);

// Top-level items; nested items live in each item's children[].
menu.pages.forEach((item) => {
  console.log(item.pageUrl, item.localizeInfos.title, item.children);
});

✨ Conceptos Clave​

¿Qué es un Menú?​

Un Menú (IMenusEntity) es una estructura de navegación que vincula páginas:

  • identifier - el marcador del menú (por ejemplo, "main_menu")
  • localizeInfos - el título del menú localizado
  • pages - el array de elementos del menú (cada elemento es una página)

Estructura del Elemento del Menú​

Cada elemento en pages es un objeto IMenusPages:

{
  id: 123,                       // Page ID
  pageUrl: "home",               // Page URL (marker)
  localizeInfos: { title: "Home" },
  attributeValues: {},           // Custom attribute values
  parentId: null,                // null for top-level items
  position: 1,                   // Display order
  children: []                   // Nested menu items
}

Jerarquía del Menú​

Los menús soportan estructuras anidadas. La anidación se expresa a través del array children[] de cada elemento junto con su parentId (los elementos de nivel superior tienen parentId: null). No hay un campo de profundidad separado - determinas la profundidad al recorrer children[].

📂 Header Menu
├─ Home (parentId: null)
├─ About (parentId: null)
│  ├─ Team (parentId: 2)
│  └─ History (parentId: 2)
├─ Products (parentId: null)
│  └─ Electronics (parentId: 4)
│     ├─ Phones (parentId: 5)
│     └─ Laptops (parentId: 5)
└─ Contact (parentId: null)

📋 Lo Que Necesitas Saber​

Los menús se crean en el panel de administración​

No puedes crear menús a través del SDK - se crean en el panel de administración de OneEntry (Menús → Crear Menú → Agregar Páginas → Guardar) o a través de la API de Administración. El SDK es para recuperar estructuras de menú.

Los elementos del menú son páginas​

Cada elemento del menú es una página configurada en OneEntry - no puedes agregar enlaces arbitrarios. Para agregar un enlace externo, crea una página con una URL externa en el módulo de Páginas y agrégala al menú.

Ordenar por posición​

Los elementos llevan un campo position - ordénalos por este para respetar el orden de visualización configurado en el panel de administración.

Multi-idioma​

Los menús se localizan mediante el langCode pasado a getMenusByMarker() (volviendo al idioma configurado en defineOneEntry()). Recupera menús en el idioma preferido del usuario.

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getMenusByMarker()Obtener menú por marcadorRecuperar una estructura de menú específica

❓ Preguntas Comunes (FAQ)​

¿Cómo creo un menú de múltiples niveles (desplegable)?​

Construye el árbol del menú en el panel de administración anidando páginas. La anidación se devuelve a través del array children[] de cada elemento - renderízalo de forma recursiva.

¿Puedo agregar enlaces externos a los menús?​

Los elementos del menú deben ser páginas configuradas en OneEntry. Para agregar un enlace externo, crea una página con una URL externa en el módulo de Páginas, luego agrégala a tu menú.

¿Cómo manejo el estado del elemento activo del menú?​

Compara la URL de la página actual con el pageUrl de cada elemento y aplica una clase activa cuando coincidan.

¿Cómo construyo migas de pan?​

Rastrea desde la página actual a través de las relaciones parentId (Inicio > Categoría > Subcategoría > Página Actual).

¿Puedo tener diferentes menús para diferentes secciones?​

Sí - crea múltiples menús con diferentes marcadores (por ejemplo, header_menu, footer_menu, sidebar_menu) y recupera cada uno con getMenusByMarker().

🎓 Mejores Prácticas​

  • Usa marcadores, no IDs - los marcadores son estables a través de entornos.
  • Renderiza children[] de forma recursiva - así es como se representa la anidación.
  • Ordena por position - respeta el orden de visualización configurado.
  • Cachea los menús - rara vez cambian.
  • Pasa langCode - recupera el menú en el idioma del usuario.
  • Maneja menús faltantes de manera elegante - proporciona una alternativa cuando no se encuentra el marcador.

🔗 Documentación Relacionada​