agenticSystem/docs/04-pages-and-records.md

Páginas y Registros

Este documento explica cómo Acai modela las páginas del sitio: toda fila con campo enlace es una página, y según el campo controlador puede ser Builder (modular, contenido por módulos) o Standard (contenido directo en los campos del registro). Cubre los tipos de tabla por menuType (category, multi, single, separador), las particularidades de la tabla apartados, los campos de visibilidad (visible_en_el_menu vs visible), las reglas inviolables sobre enlace y controlador, y el patrón canónico para implementar el detalle de un registro vía sección general custom-{tableName}. Léelo antes de crear, modificar o eliminar cualquier registro de tabla con enlace.

Tipos de página

Todo registro con campo enlace es una página pública. El campo controlador decide cómo se renderiza.

Builder (modular)

• controlador = cms/lib/plugins/builder_saas/controlador.php
• El contenido se construye con módulos (drag & drop)
• El campo builder contiene un array JSON de instancias de módulos
• Tools: add_module_to_record, set_module_config_vars, list_page_modules, reorder_module, toggle_module_visibility
• La página renderiza los módulos en orden

Standard (campos directos)

• controlador = cms/lib/plugins/builder_saas/controlador_tabla.php
• El contenido vive en los campos del registro (content, titulo_alternativo, etc.)
• El campo content es HTML (wysiwyg)
• Tool: create_or_update_record para editar el contenido directamente
• No se usan módulos del builder

Cómo detectar el tipo

Siempre comprueba el campo controlador del registro:

• Contiene controlador.php (sin _tabla) → Builder
• Contiene controlador_tabla.php → Standard

Tipos de tabla con páginas (sections)

Las tablas con páginas se llaman secciones. El campo menuType del schema define el tipo:

menuType = "category"

• Jerárquico — páginas con relaciones padre/hijo
• Campos especiales: parentNum, depth, globalOrder, lineage, siblingOrder, breadcrumb
• Ejemplo: apartados (páginas principales del sitio)
• Visibilidad: campo visible_en_el_menu (1 visible, 0 oculto)
• Orden: globalOrder

menuType = "multi"

• Lista plana — sin jerarquía
• Orden: dragSortOrder
• Ejemplos: blog, noticias, productos, vacantes, travesias
• Visibilidad: campo visible (1 visible, 0 oculto)

menuType = "single"

• Página única (un solo registro)
• Ejemplos: home, about us
• No requiere campos de orden

menuType = "separador"

• Separador visual en el menú del admin (no es una tabla con datos)

La tabla apartados

La tabla principal de páginas en la mayoría de sitios Acai. Características:

Campo	Descripción
num	Primary key
name	Nombre de la página (campo título)
enlace	URL pública (ya con barras: /servicios/)
controlador	Define Builder vs Standard
menuType	"category" (jerárquico)
parentNum	num del padre (0 = raíz)
depth	Nivel de anidamiento (0 raíz, 1 hijo, 2 nieto)
globalOrder	Orden global en el árbol
visible_en_el_menu	1 visible, 0 oculto
breadcrumb	Auto-generado
builder	JSON con instancias de módulos (si es Builder)
content	HTML del contenido (si es Standard)

Cada registro de apartados puede ser Builder o Standard — comprueba controlador por registro.

Reglas críticas para páginas

NUNCA cambies el campo enlace

A menos que el usuario te lo pida explícitamente, nunca modifiques enlace. Cambiarlo:

• Rompe enlaces externos (SEO, marcadores, otros sitios)
• Rompe enlaces internos del propio sitio
• Genera 404 hasta que se regeneren los aliases

Si el usuario sí pide cambiarlo, considera usar la tool regenerate_enlaces con generateAlias=true para mantener los enlaces antiguos como redirects.

NUNCA cambies el campo controlador

controlador define si la página es Builder o Standard. Cambiarlo a posteriori rompe el render. Solo se setea durante la creación.

Campos de visibilidad

Comprueba siempre qué campo tiene la tabla antes de cambiar visibilidad:

• apartados y otras categorías → visible_en_el_menu
• blog, travesias, noticias y otras multi → visible

Campos de título

• Algunas tablas usan name (e.g. apartados)
• Otras usan title (e.g. blog, travesias)
• Consulta el schema (get_table_schema) antes de asumir.

Trabajar con páginas Builder

Añadir contenido a una página Builder nueva

1. Listar módulos disponibles con acai-glob (template/estandar/modulos/*/builder.json).
2. add_module_to_record (uno cada vez, en orden). Devuelve sectionId.
3. set_module_config_vars con el sectionId para rellenar variables. Devuelve uploadFields.
4. Imágenes: upload_record_image o generate_image usando los recordNum y fieldName de uploadFields.
5. navigate_browser para que el usuario vea el resultado.

Editar una página Builder existente

1. list_page_modules — ver el layout actual (sectionIds, posiciones, visibilidades).
2. get_module_config_vars — leer las variables actuales del módulo a modificar.
3. set_module_config_vars — actualizar valores.
4. O editar el template del módulo: acai-view + acai-line-replace sobre index-base.tpl (compila automáticamente).
5. reorder_module para mover módulos, toggle_module_visibility para ocultar/mostrar.

Trabajar con páginas Standard

Usa create_or_update_record. Campos típicos:

Campo	Descripción
content	HTML del contenido (wysiwyg)
titulo_alternativo	Título mostrado en la página
titulo_de_pagina	<title> del navegador (SEO)
metatag_descripcion	Meta description (SEO)

create_or_update_record:
  tableName: "apartados"
  recordId: "87"
  fields:
    content: "<h2>Nuestros Servicios</h2><p>Ofrecemos…</p>"
    titulo_de_pagina: "Servicios | Mi Sitio"
    metatag_descripcion: "Descubre nuestros servicios…"

Patrón canónico — Detalle de registro

Para cualquier tabla con campo enlace (productos, noticias, vacantes, servicios), el detalle se resuelve por convención vía sección general custom-{tableName}. Ver 03-modules-and-sections.md para detalles.

Reglas duras:

• NO crees una página por registro en apartados.
• NO uses ni configures _detailPage — no existe.
• NO uses query params (?id=5) en URLs.
• NO uses hooks para cargar el registro — thisrecord ya existe.
• El nombre del módulo es literalmente custom- + tableName.

Flujo para una funcionalidad tipo "vacantes":

1. create_table con enlace=true
2. create_field para los campos necesarios
3. Crear template/estandar/modulos/custom-vacantes/index-base.tpl que use thisrecord.*
4. (Opcional) Módulo de listado vacantes_listado que consulte y enlace
5. (Opcional) Página índice /vacantes/ en apartados con el módulo de listado

Campos típicos en tablas "publicables"

Cuando creas una tabla con enlace (noticias, vacantes, blog), añade por defecto:

Campo	Tipo	Uso
fecha_publicacion	date	Ordenar y filtrar
fecha_expiracion	date (opcional)	Oculta el registro automáticamente cuando caduca
visible	checkbox	Control manual

NO añadas un campo "estado" calculado si ya tienes visible + fechas.

Reglas críticas

1. Toda tabla con enlace produce páginas públicas. Comprueba el controlador para saber si son Builder o Standard.
2. NUNCA modifiques enlace salvo petición explícita del usuario.
3. NUNCA modifiques controlador de un registro existente.
4. PK siempre es num, nunca id. Foreign keys con sufijo _num.
5. Visibilidad: visible_en_el_menu para category, visible para multi. Comprueba el schema.
6. Detalle de registro = custom-{tableName}, nunca página duplicada.
7. Tablas sin prefijo cms_ en todas las llamadas a tools.
8. Para formularios estándar usa c-form, no construyas POST/hook custom.