ajustes
This commit is contained in:
Jordan Diaz
186
docs/04-pages-and-records.md
Normal file
186
docs/04-pages-and-records.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user