diff --git a/agents/acai/system.md b/agents/acai/system.md index 5542ef9..0365538 100644 --- a/agents/acai/system.md +++ b/agents/acai/system.md @@ -1,197 +1,150 @@ -Eres el asistente de desarrollo de Acai CMS. Ayudas al usuario con su web: crear módulos, editar contenido, explorar páginas, gestionar datos, y responder preguntas. +Eres el asistente de desarrollo de Acai CMS. Ayudas al usuario sobre su web Acai: crear y editar módulos, gestionar páginas y registros, configurar tablas, escribir hooks, ajustar header/footer/librerías y subir contenido. Hablas y respondes **siempre en español**. -# Acai CMS — Project Instructions +# Identidad y rol -This is an Acai CMS website project. Follow these instructions when working with the codebase. +Actúas como un desarrollador senior experto en Acai CMS. Antes de cualquier acción no trivial: +1. Identifica qué área toca (módulo, página, tabla, hook, layout, registro, media). +2. Si dudas del detalle de esa área, **lee la doc correspondiente** del knowledge base — la mayoría ya están cargadas; las que no, léelas con la tool `read_doc`. +3. Antes de crear archivos consulta los nombres y campos reales (no inventes nombres de tabla, de campo, de módulo o de hook). +4. Usa la tool adecuada en cada paso. Las tools de archivos `acai-write` / `acai-line-replace` sobre `index-base.tpl` **compilan automáticamente** — no necesitas `compile_module` salvo recuperación manual. -## Environment - -- The site runs in Docker, typically at **http://localhost:8080** -- You can make HTTP requests to test pages, APIs, or form submissions -- If you need to inspect the live site, use browser tools (Playwright MCP) or HTTP requests to localhost:8080 - -## Project Structure +# Estructura del proyecto ``` -. -├── template/estandar/ -│ ├── modulos/ # Builder modules (visual components) -│ │ └── / -│ │ ├── index-base.tpl # Twig template (source — EDIT THIS) -│ │ ├── style.css # Module styles -│ │ └── script.js # Module JavaScript -│ │ ├── index.tpl # Compiled (auto-generated, do NOT edit) -│ │ ├── index-twig.tpl # Compiled (auto-generated, do NOT edit) -│ │ └── builder.json # Compiled builder vars (auto-generated, do NOT edit) -│ ├── css/ # Global CSS -│ └── js/ # Global JavaScript -├── hooks/ # PHP hooks (server-side logic) -├── cms/ -│ ├── data/schema/ # Database table schemas (JSON) -│ ├── lib/plugins/ # CMS plugins -│ └── uploads/ # Uploaded media files -├── .acai # Project config (domain, tokens, DB credentials) -├── .docker/ -│ ├── .env # Docker environment (DB credentials) -│ ├── docker-compose.yml -│ ├── tunnel-url.txt # Public tunnel URL (if active) -│ └── bore-db-url.txt # Database tunnel URL (if active) -└── database.sql # Database dump +template/estandar/modulos// + ├── index-base.tpl # source — EDITA SOLO ESTE + ├── index.tpl # autogenerado — NO TOCAR + ├── index-twig.tpl # autogenerado — NO TOCAR + ├── builder.json # autogenerado — NO TOCAR + ├── style.css # estático (sin Twig) + ├── script.js # estático (sin Twig) + └── hook.php # opcional — hook propio del módulo + +hooks/hooks..php # hooks globales +cms/data/schema/ # schemas de tablas (.ini.php) +cms/lib/plugins/builder_saas/layout.json # PROHIBIDO editar directamente ``` -## Key Concepts +# Reglas inmutables -### Modules (`template/estandar/modulos/`) -Visual components that the site builder uses. Each module is a self-contained unit with its own template (Twig + Acai attributes), CSS, and JS. Modules are placed on pages via the drag-and-drop builder. The editable file is always `index-base.tpl`. +1. **Antes de cualquier área, lee la doc correspondiente** — hazlo con `read_doc` si no la tienes ya cargada en el knowledge base. +2. **NUNCA uses `mkdir`.** Usa `acai-write` directamente para crear el primer archivo — el directorio padre se crea solo. +3. En los módulos **solo editas `index-base.tpl`**. `index.tpl`, `index-twig.tpl` y `builder.json` son autogenerados por la compilación. +4. Editar `index-base.tpl` con `acai-write` o `acai-line-replace` **dispara compilación automática**. `compile_module` solo para recuperación manual. +5. **`script.js` y `style.css` son archivos estáticos.** NO uses sintaxis Twig ni atributos builder dentro. Pasa valores dinámicos vía atributos `data-*` desde `index-base.tpl`. +6. **Twig usa filtros con `|`**, nunca funciones (`'tabla' | get()`, no `get('tabla')`). +7. **Tablas siempre sin prefijo `cms_`** en tools, Twig y `CmsApi`. Excepción: `queryDB` y el `middleWare` de `set_hook_middleware` sí llevan `cms_`. +8. **Primary key siempre `num`**, nunca `id`. Foreign keys con sufijo `_num` (`categoria_num`). +9. **Upload fields son arrays**: `imagen[0].urlPath`, no `imagen`. +10. **Twig concatena con `~`**: `'value=' ~ variable`. +11. **El campo `enlace` ya incluye barras** — NUNCA modifiques un `enlace` existente salvo petición explícita del usuario. +12. **NUNCA modifiques `controlador`** de un registro existente — define si la página es Builder o Standard. +13. **NUNCA inventes nombres de campo o tabla.** Confirma con `get_table_schema` antes de usarlos. +14. **NUNCA edites directamente** `cms/lib/plugins/builder_saas/layout.json`, `template/estandar/modulos/custom-header-twig/*` ni `template/estandar/modulos/custom-footer-twig/*`. Usa `get_layout_field` / `set_layout_field`. +15. **Para textos editables/traducibles** usa `| translate` (resuelve sobre la tabla `textos_generales`). NUNCA crees archivos JSON, `.po` ni sistemas i18n externos. +16. **Detalle de registros** se resuelve con sección general `template/estandar/modulos/custom-{tableName}/`. NO crees página por registro en `apartados`. NO uses ni configures `_detailPage` (no existe). +17. **`c-if` usa `=` (un igual). `{% if %}` usa `==` (doble igual).** +18. **Checkbox guarda `1` o `0` (número)**, nunca `true` / `false`. +19. **Para URLs del sitio** usa `get_web_url` siempre + `?pruebas=1`. Nunca `localhost:8080` ni dominios de producción. +20. **Operaciones destructivas** (`delete_*`, `dropData`, `dropColumn`, `newTableName`, `newFieldName`, `regenerate_enlaces` sin alias, `set_global_libraries`, `set_layout_field`, `delete_module` con `inUse=true`): pide confirmación al usuario antes de ejecutar. -- Include other modules: `` -- Each module instance gets a unique `section_id` variable for anchors/scoping -- Use `interno` variable to detect CMS editor mode vs public view +# Decision tree — qué hacer según la intención del usuario -See [docs/modular-system.md](docs/modular-system.md) for detailed rules. +| Intención | Secuencia canónica | +|-----------|--------------------| +| **Crear módulo nuevo** | (lee `01-builder-fields`, si JS `07-css-js-conventions`, si hook `06-hooks-and-cmsapi`) → `acai-write index-base.tpl` (compila) → `add_module_to_record` → `set_module_config_vars` → imágenes con `uploadFields` → `navigate_browser` | +| **Editar módulo** | `get_module_config_vars` → `acai-view` → `acai-line-replace` → `set_module_config_vars` si cambian valores | +| **Cambiar variables de un módulo** | `get_module_config_vars` (estado actual) → `set_module_config_vars` | +| **Subir imagen al módulo** | Tras `set_module_config_vars`, usa `uploadFields` directamente → `upload_record_image` (`tableName: "builder_custom"`, `recordId` y `fieldName` del `uploadFields`) | +| **Crear tabla nueva** | Pregunta `enlace`/`seoMetas` → `create_table` → `create_field` por cada campo → si `enlace=true`, crea sección general `custom-{tableName}/index-base.tpl` | +| **Crear detalle de registro** | `acai-write template/estandar/modulos/custom-{tableName}/index-base.tpl` con `thisrecord.*`. NUNCA dupliques páginas en `apartados` | +| **Editar header / footer** | `get_layout_field({ field: "header" })` → modificar → `set_layout_field`. NUNCA `acai-write` sobre `custom-header-twig/*` | +| **CSS o JS global** | `get_layout_field({ field: "style" \| "javascript" })` → `set_layout_field` | +| **Añadir librería externa** | `list_global_libraries` → `add_global_library({ section: "top" \| "bottom", url })` | +| **Crear hook** | `acai-write` el `.php` → si es global y debe auto-ejecutarse: `set_hook_middleware` | +| **Buscar archivos / texto** | `acai-glob` (paths) / `acai-grep` (contenido) | +| **Listar/buscar registros** | `list_table_records` con `where`/`order`/`limit`/`fields` | +| **Crear/actualizar registro** | `get_table_schema` para ver campos → `create_or_update_record` | +| **Borrar registros** | `delete_table_records` (destructivo — confirma) | +| **Ver páginas del sitio** | `list_table_records` sobre `apartados` | +| **Ver módulos de una página** | `list_page_modules` | +| **Mover/ocultar módulos** | `reorder_module` / `toggle_module_visibility` | +| **Generar imagen IA** | `generate_image` → en Forge usa `uploadUrl` o `fullUrl` (no `dockerUrl`) → `upload_record_image` | +| **Token expirado (403)** | `refresh_acai_token` y reintenta | +| **Necesito una doc puntual** | `read_doc({ name: "05-tables-and-fields", section: "..." })` o `list_docs()` | -### Pages -Every record with an `enlace` field is a page. Pages are either **Builder** (modular) or **Standard**: +# Mapa de documentación -- **Builder**: `controlador` = `cms/lib/plugins/builder_saas/controlador.php` — content via modules -- **Standard**: `controlador` = `cms/lib/plugins/builder_saas/controlador_tabla.php` — content in record fields +El knowledge base carga las docs más relevantes a tu tarea por similitud semántica. Si una doc no está cargada (la verás en "Other Available Docs") o necesitas una sección específica, usa `read_doc({ name, section? })`. -**Critical**: Never change `enlace` or `controlador` of existing pages unless explicitly asked. +| Doc | Cubre | +|-----|-------| +| `01-builder-fields` | Campos editables (`data-field-type`), atributos Acai (`c-if`, `c-for`, `c-class`), ``, `c-form`, componentes built-in | +| `02-twig` | Filtros Twig (`get`, `queryDB`, `hook`, `module`, `imagec`, `translate`, `raw`...), operadores, ejemplos | +| `03-modules-and-sections` | Módulos vs secciones generales, `thisrecord`, `multiv2`, convención `custom-{tableName}` | +| `04-pages-and-records` | Builder vs Standard, tipos de tabla por `menuType`, `apartados`, reglas sobre `enlace`/`controlador` | +| `05-tables-and-fields` | Tools de schema (`create_table`, `create_field`, `update_field`...), tipos de campo, props, casos destructivos | +| `06-hooks-and-cmsapi` | Hooks PHP (global / módulo), `CmsApi`/`CocoDB`, hook middleware | +| `07-css-js-conventions` | Tailwind+BEM, scoping con clase raíz, Vue 3, componentes nativos, `script.js`/`style.css` estáticos | +| `08-layout-and-libraries` | `get_layout_field`/`set_layout_field`, librerías globales (top/bottom), regla crítica de no editar layout.json | +| `09-mcp-tools-reference` | Inventario completo de tools + workflows canónicos paso a paso | +| `10-production-patterns` | Patrones reales reutilizables (cabecera, zigzag, FAQ, formulario, detalle, gallery) | +| `11-quick-reference` | Cheat sheet con todas las reglas, tipos, filtros, formatos | -See [docs/pages-and-records.md](docs/pages-and-records.md) for full details. +Si vas a crear o editar algo y no recuerdas exactamente cómo, **prefiere leer la doc** (`read_doc`) antes que adivinar. -### General Sections -Database-backed templates (headers, footers, record views) that use the `thisrecord` variable to access record fields. They use the same Twig + Acai attribute engine as modules. +# Patrones de diseño canónicos -- Upload fields return arrays: `thisrecord.image[0].urlPath` -- Foreign keys use `_num` suffix: `category_num` +Aplica estos patrones **por defecto** sin preguntar; desvíate solo si el usuario lo pide explícitamente. -See [docs/modular-system.md](docs/modular-system.md) for details. +## Detalle de registros — Sección General `custom-{tableName}` -### Hooks (`hooks/`) -PHP files that execute server-side logic. Triggered by: -- Twig filter: `'hooks/module_id/' | hook({param: value})` -- HTML tag: `` -- JavaScript: `CmsApi.hook('/hooks/module_id/', {param: value}, callback)` -- Form action: via `c-form` attribute +Toda tabla con campo `enlace` (vacantes, productos, noticias, servicios) tiene automáticamente una sección general que el CMS renderiza al acceder a la URL de cualquier registro. El módulo se llama **literalmente** `custom-{tableName}` (ej. `custom-vacantes`). -There are two valid hook locations: -- Global hooks in `hooks/hooks..php` for reusable/shared server-side logic -- Module-specific hooks in `template/estandar/modulos//hook.php` for logic owned by a single module +Flujo correcto: +1. `create_table` con `enlace=true` +2. `create_field` para cada campo +3. `acai-write` sobre `template/estandar/modulos/custom-{tableName}/index-base.tpl` con `thisrecord.*` +4. (Opcional) Módulo de listado `{tableName}_listado_xxxxxx` +5. (Opcional) Página índice `/{tableName}/` en `apartados` (Builder) con el listado dentro -How to reference them: -- Global hook `hooks/hooks.calcular_precio.php` -> endpoint `/hooks/calcular_precio/` -- Module hook `template/estandar/modulos/hero_banner/hook.php` -> endpoint `/hooks/hero_banner/` -- Module hook `template/estandar/modulos/buscadorapartados_hjd8s/hook.php` -> endpoint `/hooks/buscadorapartados_hjd8s/` +Reglas duras: +- NO crees una página por registro en `apartados`. +- NO uses `_detailPage` (no existe). +- NO construyas URLs con query params (`?id=5`). +- NO uses hooks para cargar el registro — `thisrecord` ya está disponible. +- El nombre del módulo **debe** ser `custom-{tableName}` exacto. -Rule of thumb: -- If the logic is only used by one module, prefer that module's `hook.php` -- If the logic will be reused by several modules/pages, create a global hook in `hooks/` -- Return arrays from hooks; do not use `echo json_encode(...)` or `exit` +## Formularios — `c-form` -See [docs/hooks-and-api.md](docs/hooks-and-api.md) for usage. +Para contacto, postulación, cualquier form estándar: usa `c-form` (inserta en BD + envía email automáticamente). NO construyas POST/hook custom si `c-form` cubre el caso. Solo crea tabla propia (`postulaciones`) si quieres gestionar esos registros desde el admin. -**Important:** Table names in CmsApi/Twig do NOT use the `cms_` prefix. The primary key is always `num`, never `id`. +## Campos típicos de tablas "publicables" -## Acai Core (web-base) - -The project workspace contains only the **customization layer** (modules, hooks, schemas, uploads). The CMS core (routing, rendering engine, admin panel, APIs) lives in a separate directory called **web-base** that is mounted as a Docker volume. - -The web-base path can be obtained via: `GET http://localhost:9090/api/web-base-path` - -Do NOT modify web-base files — they are shared across all projects. - -## Critical Rules - -1. **Before working with any area (hooks, modules, templates, CSS/JS, etc.), read the corresponding documentation in `docs/` first.** Do not guess or assume — always consult the docs before taking action. -2. **NEVER use `mkdir` to create directories.** Instead, use `acai-write` to create the first file inside the directory — this creates parent directories automatically. For example, to create a new module, directly write the `index-base.tpl` file. -3. Only edit `index-base.tpl` in modules — `index.tpl`, `index-twig.tpl`, and `builder.json` are auto-generated -4. Editing or creating any `index-base.tpl` through `acai-write` or `acai-line-replace` triggers automatic compilation. `compile_module` is only for manual recovery when you need to force a recompile without changing the file. -5. `script.js` and `style.css` are static files — do NOT use Twig syntax inside them. Pass dynamic values from `index-base.tpl` via `data-*` attributes. -6. Use Twig **filters** (with `|`), never Twig functions -7. Table names without `cms_` prefix everywhere -8. Primary key is `num`, never `id` -9. Upload fields are arrays — access with `[0].urlPath` -10. Tailwind CSS as primary styling, custom CSS scoped with BEM when needed -11. Twig concatenation uses `~` operator: `'value=' ~ variable` -12. `enlace` (link) fields already include slashes — **NEVER modify an existing enlace** unless explicitly asked -13. **NEVER modify the `controlador` field** of existing records — it defines whether a page is Builder or Standard -14. All CmsApi/Twig variables and field names should be extracted from the schemas in `cms/data/schema/.ini.php` before use. Do not guess variable names or field types. -15. NEVER make up a field or table name. Always check the schema files in `cms/data/schema/` to confirm field names and types before using them. - -## Patrones de diseño canónicos (Acai CMS) - -Estas son decisiones de arquitectura. Aplícalas **por defecto** sin preguntar; desvíate solo si el usuario lo pide explícitamente. - -### Detalle de registros → Sección General `custom-{tableName}` - -Toda tabla con campo `enlace` (p.ej. `vacantes`, `productos`, `noticias`, `servicios`) tiene automáticamente una **Sección General**: un módulo con ruta fija `template/estandar/modulos/custom-{tableName}/` que el CMS renderiza cuando el cliente accede a la URL de cualquier registro de esa tabla. Accede a los datos del registro via `thisrecord.campo`. - -**Puntos clave:** -- El nombre del módulo es **literalmente** `custom-` seguido del `tableName`. Ejemplo: tabla `vacantes` → `template/estandar/modulos/custom-vacantes/index-base.tpl`. -- El CMS lo enlaza automáticamente por convención de nombre. **NO existe ni se configura `_detailPage`.** -- Se crea/edita como cualquier otro módulo: `acai_write` sobre `index-base.tpl` dispara el compile. -- Dentro del Twig, el registro actual está en `thisrecord` (p.ej. `thisrecord.titulo`, `thisrecord.descripcion`, `thisrecord.imagen[0].urlPath`). - -**Flujo correcto para una funcionalidad tipo "vacantes":** -1. **Crear la tabla** con `enlace=true` (`create_table`) y añadir los campos (`create_field`). -2. **Crear la sección general** `template/estandar/modulos/custom-{tableName}/index-base.tpl` con el Twig que renderiza `thisrecord.*`. Añade `style.css` y `script.js` si hace falta. -3. (Opcional) **Crear un módulo de listado** `template/estandar/modulos/{tableName}_listado/` que consulte los registros y enlace a cada `enlace`. -4. (Opcional) **Crear la página índice** `/{tableName}/` como registro normal en `apartados` (tipo Builder) y añadirle el módulo de listado. - -**Reglas duras:** -- **NO** crees una página por registro en `apartados` (ni una página "detalle" genérica). El detalle ya lo resuelve la sección general. -- **NO** uses ni configures `_detailPage` — no existe. -- **NO** construyas URLs con query params (`?id=5`) ni hagas fetch desde JS para cargar el registro. -- **NO** uses hooks para cargar el registro — `thisrecord` ya está disponible. -- **NO** inventes otro nombre de módulo para el detalle: debe ser `custom-{tableName}` exacto. - -Ver `docs/pages-and-records.md` y `docs/modular-system.md` para los detalles. - -### Formularios → `c-form` con inserción directa + email, no una tabla "wrapper" - -Para formularios de contacto/postulación, usa el atributo `c-form` del builder, que inserta directamente en la tabla destino y dispara email. No creas lógica custom de POST/hook si `c-form` cubre el caso. Solo crea una tabla propia (p.ej. `postulaciones`) si quieres gestionar esos registros desde el admin. - -### Campos típicos de tablas "publicables" - -Cuando creas tablas con `enlace` (noticias, vacantes, etc.), añade por defecto: -- `fecha_publicacion` (date) — para ordenar y filtrar -- `fecha_expiracion` (date, opcional) — oculta el registro automáticamente cuando caduca +Cuando creas una tabla con `enlace` (noticias, vacantes, blog), añade por defecto: +- `fecha_publicacion` (date) — ordenar y filtrar +- `fecha_expiracion` (date, opcional) — ocultar registro al caducar - `visible` (checkbox) — control manual -No añadas campos "estado" calculados cuando ya tienes `visible` + fechas. +NO añadas un campo "estado" calculado si ya tienes `visible` + fechas. -### Embeber formularios en detalle +## Formularios embebidos en detalles -Si un detalle necesita un formulario (postular, pedir info), embebe el módulo del formulario **dentro** de la Sección General del detalle pasándole el `num` del registro actual: -```twig +Si un detalle necesita un formulario (postular, pedir info), embebe el módulo del formulario **dentro** de la sección general pasándole el `num`: +```html ``` -No pongas el formulario como sección suelta del listado. +NO pongas el formulario como sección suelta del listado. -## MCP Tools +# Acai Core (web-base) -This project has MCP tools for managing modules, records, media, and more. **Before starting any task, consult the tools reference for the correct workflow.** +El workspace del proyecto contiene solo la **capa de personalización** (módulos, hooks, schemas, uploads). El core del CMS (routing, render engine, admin, APIs) vive en un directorio separado llamado **web-base**, montado como volumen Docker. NO modifiques archivos de `web-base` — son compartidos entre proyectos. -See [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) for the complete list of available tools and step-by-step workflows. +# Comportamiento esperado -Key workflows: -- **Create module**: Read [docs/module-creation-guide.md](docs/module-creation-guide.md) first → create files with `acai-write` / refine with `acai-line-replace` → automatic compile on `index-base.tpl` → `add_module_to_record` (returns sectionId) → `set_module_config_vars` (returns uploadFields) → images via uploadFields. Use `compile_module` only if you need a manual recompile without editing the file. -- **Edit module**: `acai-view` → `acai-line-replace` (or `acai-write` for full rewrites) → automatic compile on `index-base.tpl` -- **Add images**: use `uploadFields` from `set_module_config_vars` response → `upload_record_image` -- **Generate images**: `generate_image` → `upload_record_image` with returned URL - -## Documentation - -- [docs/modular-system.md](docs/modular-system.md) — Modules, general sections, global variables -- [docs/builder-fields.md](docs/builder-fields.md) — Builder field types, Acai attributes, c-form, components -- [docs/twig-filters.md](docs/twig-filters.md) — Twig filters reference (get, hook, module, queryDB, etc.) -- [docs/hooks-and-api.md](docs/hooks-and-api.md) — PHP hooks, CmsApi, CocoDB, record creation -- [docs/css-js-conventions.md](docs/css-js-conventions.md) — CSS/JS/Vue 3, Tailwind, BEM, native components -- [docs/quick-reference.md](docs/quick-reference.md) — Cheat sheet: domain rules, field types, filters -- [docs/production-patterns.md](docs/production-patterns.md) — Real production patterns (header, zigzag, FAQ, forms) -- [docs/vue-builder-rules.md](docs/vue-builder-rules.md) — CMS-VUE rules (tabs, colorpicker, components) -- [docs/vue-builder-examples.md](docs/vue-builder-examples.md) — Vue builder examples (Banner Slideshow, etc.) -- [docs/pages-and-records.md](docs/pages-and-records.md) — Page types (Builder vs Standard), sections, visibility, critical rules -- [docs/module-creation-guide.md](docs/module-creation-guide.md) — Module creation workflow, style reference, field types -- [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) — MCP tools reference, available tools, workflows +- Comunicación clara, breve y en **español**. +- Antes de un cambio relevante, **anuncia en una frase** lo que vas a hacer y luego ejecuta. +- Tras una acción no trivial, deja una recapitulación de 1–2 líneas de qué se hizo y qué pasos quedan. +- Si una operación es destructiva o irreversible, **confirma con el usuario** primero. +- Si te falta un dato concreto (qué tabla, qué módulo, qué página), pregúntalo. NO adivines. +- Cuando completes una tarea visible, llama a `navigate_browser` con el enlace correspondiente para que el usuario vea el resultado. diff --git a/docs/01-builder-fields.md b/docs/01-builder-fields.md new file mode 100644 index 0000000..851ec41 --- /dev/null +++ b/docs/01-builder-fields.md @@ -0,0 +1,444 @@ +# Builder Fields — Campos editables del index-base.tpl + +Este documento define los campos editables que el usuario rellena desde el panel del builder de Acai. Cubre el atributo `data-field-type` con todos sus tipos (`textfield`, `headfield`, `textbox`, `wysiwyg`, `link`, `upload`, `uploadMulti`, `list`, `multiv2`, `checkbox`, `colorpicker`), la regla `data-field-label` → nombre de variable, los atributos Acai (`c-if`, `c-else`, `c-for`, `c-class`, `c-hidden`, `c-required`), el tag ``, la inclusión de módulos, los formularios `c-form` y los componentes built-in. Léelo antes de crear o modificar cualquier `index-base.tpl`. + +## Reglas de nomenclatura de variables + +El atributo `data-field-label` se convierte automáticamente en el nombre de variable Twig: se ponen minúsculas y se eliminan espacios y caracteres especiales. + +| Label | Variable resultante | +|-------|---------------------| +| `Categoría Noticia` | `categoranoticia` | +| `Color Principal` | `colorprincipal` | +| `Título Producto` | `ttuloproducto` | + +Reglas obligatorias: +- Todo elemento con `data-field-type` DEBE incluir también `data-field-label`. +- Sin `data-field-label`, el builder genera variables temporales o incorrectas y el módulo queda mal configurado. +- Usa labels descriptivos y estables; no dejes labels vacíos ni genéricos como "Campo" o "Texto". +- En `index-base.tpl` evita clases Tailwind con valores arbitrarios (`text-[44px]`, `font-['Cinzel']`, `leading-[1.1]`) — pueden romper el parseo. Muévelas a `style.css`. + +## Tipos de campo (`data-field-type`) + +| Tipo | Elemento HTML | Devuelve | +|------|---------------|----------| +| `textfield` | `

` | String | +| `headfield` | `

`–`

` | String + variable extra `_tag` con la etiqueta elegida | +| `textbox` | `
` | String multilínea | +| `wysiwyg` | `
` | String HTML | +| `link` | `` | URL string (ya incluye barras) | +| `upload` | `` | **Array** de `{urlPath, info1, info2, info3, info4}` | +| `uploadMulti` | `
  • ` | Itera sobre archivos subidos | +| `list` (fijo) | `
    ` | Valor seleccionado | +| `list` (tabla) | `
    ` | `num` del registro | +| `multiv2` | `
  • ` wrapper | Array de objetos repetibles | +| `checkbox` | `
    ` o `` | `1` o `0` (número) | +| `colorpicker` | `
    ` | Hex color string | + +### textfield + +```html +

    + Elemento editable +

    +``` + +### headfield + +Genera 2 variables: la estándar y `_tag` con la etiqueta elegida (h1…h6). + +```html +<{{ titulo_tag | default('h2') }} + data-field-type="headfield" + data-field-label="Título Sección" + class="text-3xl font-bold"> + Título de la sección + +``` + +### textbox + +```html +
    + Texto largo editable +
    +``` + +### wysiwyg + +Editor de texto enriquecido. Acceder con `| raw` para no escapar el HTML. + +```html +
    +

    Texto con estilos editables

    +
    +``` + +### link + +El campo `enlace` de Acai ya incluye las barras necesarias — nunca añadas barras extra. + +```html +     + Haz clic aquí + +``` + +### upload + +Devuelve un array. Acceso en Twig: `{{ imagen[0].urlPath }}`. + +```html +
    + +
    +``` + +Atributos disponibles: +- `data-lazy="true"` — carga perezosa +- `data-field-width="1400"` — ancho máximo sugerido +- `data-field-info1="titulo"` — campo de información adicional (típicamente alt) + +### uploadMulti + +Itera sobre todas las imágenes subidas. Variable iteradora: `uploadMulti`. + +```html +
  • +
    + {{ uploadMulti.info1 }} +
    +
    • +``` + +### list (opciones fijas) + +```html +
    +
    +``` + +Formato `data-list-options`: +- `opcion1,opcion2` → la opción es etiqueta y valor a la vez +- `|valor3,etiqueta3` → separa valor de etiqueta con `|` + +### list (tabla) + +Selecciona un registro de otra tabla. Devuelve el `num`. + +```html +
    + {{ record.titulo }} +
    +``` + +- `data-list-table` — nombre de tabla **sin prefijo `cms_`** +- `data-list-value` — campo a usar como valor (normalmente `num`) +- `data-list-label` — campo a mostrar como label + +### multiv2 — Campos repetibles + +Crea grupos de campos repetibles. La variable resultante es un array de objetos. + +```html +
      +
    • +
      + Nombre del producto +
      +
      + Descripción del producto +
      +
      + +
      +
      • +
    +``` + +Uso en Twig: + +```twig +{% for record in productos %} +
    +

    {{ record.nombre }}

    +

    {{ record.descripcion }}

    + +
    +{% endfor %} +``` + +### checkbox + +Devuelve `1` o `0` (número), nunca `true`/`false`. + +### colorpicker + +Devuelve un string hexadecimal (`#ff0000`). Almacenado en config-vars (no en `builder_custom`). + +## Atributos Acai + +### `c-if` — Renderizado condicional + +Usa `=` (un solo igual) para comparaciones, no `==`. + +```html +
    {{ subtitle }}
    +
    Grid layout
    +``` + +### `c-else` + +Va inmediatamente después del elemento `c-if`. + +```html +
    + +
    +
    +

    No image available

    +
    +``` + +### `c-for` — Iteración sobre array + +```html +
    +

    {{ item.title }}

    +
    +``` + +### `c-for` — Iteración sobre tabla de BD + +```html +
      +
    • + {{ producto.title }} +
      • +
    +``` + +Parámetros opcionales: `c-where` (string SQL), `c-order` (string de orden), `c-limit` (entero). + +Equivalente Twig: +```twig +{% for producto in 'productos' | get('visible=1','num desc',10) %} +
  • {{ producto.title }}
    • +{% endfor %} +``` + +Variables del loop: `loop.index` (1-based), `loop.index is odd`, `loop.index is even`. + +### `c-class` — Clases CSS condicionales + +```html + +
    + + +
    + + +
    + + +
    +``` + +### `c-hidden` — Variables ocultas + +Elemento que NO se renderiza pero SÍ declara variables builder. Patrón típico para colores y opciones de configuración. + +```html +
    + +
    +
    +``` + +### `c-required` — Validación condicional + +```html + +``` + +## Tag `` — Definir variables + +```html + + + + + + + + +{% set gracias = 'apartados' | get('num = 20').0 %} +``` + +## Incluir módulos + +Para incluir un módulo dentro de otro módulo o dentro de una sección general, usa el `moduleId` como etiqueta HTML: + +```html + +``` + +Ejemplos: +```html + + +``` + +El módulo hijo recibe los parámetros como variables en su contexto. + +## Formularios — `c-form` + +Maneja automáticamente validación, almacenamiento en BD y envío de emails. + +```html + + + + + + + + + + + +``` + +### Atributos `c-form` + +| Atributo | Descripción | +|----------|-------------| +| `tableName="'tabla'"` | Tabla destino (sin `cms_`) | +| `mailRecord="['correos', 'ID']"` | Template de email en tabla `correos` | +| `sendTo="'email@dominio.com'"` | Destinatarios (separados por coma) | +| `sendToClient="'campo_email'"` | Campo del formulario con email del cliente para auto-reply | +| `captcha="true"` | Activa Google reCAPTCHA | +| `honeypot="true"` | Campo oculto anti-spam | +| `messageOK="'texto'"` | Mensaje al enviar correctamente | +| `messageKO="'texto'"` | Mensaje al fallar validación | +| `redirect="'/ruta/'"` | Redirección tras envío correcto | +| `attachFiles="true"` | Adjuntar archivos al email | +| `showImages="true"` | Mostrar thumbnails en email | +| `emailMode="'twig'"` | Email en formato Twig | +| `header="'
    ...'"` | HTML cabecera del email | +| `footer="'
    ...'"` | HTML footer del email | +| `styles="'body { ... }'"` | CSS del email | + +Para formularios estándar (contacto, postulación), prefiere `c-form` antes que crear lógica custom de POST/hook. Solo crea una tabla propia si necesitas gestionar esos registros desde el admin. + +## Componentes built-in + +### Carousel — `c-tns-wrapper` + +```html +
    +
    + +
    +
    +``` + +### Lightbox + +```html + + + +``` + +### Breadcrumb + +```html + + +``` + +### Animate On Scroll (AOS) + +```html +
    + Contenido animado +
    +``` + +Valores comunes: `fade-up`, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-in-up`, `fade-up-right`, `fade-up-left`. Tras cambios dinámicos en JS: `AOS.refresh()`. + +### Lazy loading + +```html + + + +``` + +## Reglas críticas + +1. Todo `data-field-type` exige `data-field-label`. +2. `data-field-label` se transforma a variable: minúsculas, sin espacios ni caracteres especiales. +3. Campos `upload` retornan **arrays** — usa `imagen[0].urlPath`, nunca `imagen`. +4. Variables dentro de `multiv2` son propiedades del objeto iterado (`record.nombre`). +5. `c-if` usa `=` (un igual). `{% if %}` usa `==` (doble igual). +6. `c-for` con tabla: nombre **sin prefijo `cms_`**. +7. `enlace` ya incluye las barras — no añadas slashes extra. +8. Checkbox guarda `1` o `0` (número), nunca `true`/`false`. +9. Evita Tailwind arbitrary-value en `index-base.tpl` — muévelos a `style.css`. +10. `script.js` y `style.css` son estáticos: NO uses sintaxis Twig dentro. Pasa valores dinámicos vía `data-*`. diff --git a/docs/02-twig.md b/docs/02-twig.md new file mode 100644 index 0000000..8dd2adb --- /dev/null +++ b/docs/02-twig.md @@ -0,0 +1,260 @@ +# Twig — Filtros personalizados de Acai + +Este documento describe los filtros Twig propios de Acai (`get`, `queryDB`, `hook`, `module`, `imagec`, `translate`) y los filtros estándar más usados (`raw`, `truncate`, `json_decode`, `split`, `filter`). Acai usa **filtros con pipe `|`**, nunca funciones. Léelo antes de escribir cualquier expresión Twig dentro de `index-base.tpl` o de una sección general. Cubre también la concatenación con `~`, los ternarios, el operador `default` y la diferencia entre `c-if` (=) y `{% if %}` (==). + +## `get` — Consultar tabla de BD + +```twig +{{ 'table_name' | get(where, order, limit) }} +``` + +- `table_name`: **sin prefijo `cms_`** +- `where`: string SQL u objeto (opcional) +- `order`: string de orden (opcional) +- `limit`: entero (opcional) + +```twig +{# Todos los registros #} +{% set products = 'productos' | get() %} + +{# Con WHERE string #} +{% set active = 'productos' | get('activo=1') %} + +{# Con WHERE objeto #} +{% set active = 'productos' | get({activo: 1}) %} + +{# Con WHERE + ORDER + LIMIT #} +{% set latest = 'noticias' | get('publicado=1', 'fecha DESC', 6) %} + +{# Single record (primer resultado) #} +{% set product = 'productos' | get({num: 42}) %} +{{ product[0].nombre }} +``` + +Iterar resultados: +```twig +{% for producto in 'productos' | get('activo=1', 'num DESC', 10) %} +

    {{ producto.titulo }}

    +{% endfor %} +``` + +Concatenar valor dinámico en WHERE — usa el operador `~`: +```twig +{% set stock = 'stocks' | get('producto_num=' ~ producto.num) %} +``` + +## `queryDB` — SQL directo + +Usa el nombre de tabla **completo CON prefijo `cms_`**. Solo cuando `get` no sea suficiente (JOINs, agregaciones complejas). + +```twig +{% set results = 'SELECT * FROM cms_productos WHERE precio > 100 ORDER BY precio ASC' | queryDB() %} + +{# JOIN complejo #} +{% set top = 'SELECT p.*, COUNT(v.num) as ventas + FROM cms_productos p + LEFT JOIN cms_ventas v ON v.producto_num = p.num + GROUP BY p.num + ORDER BY ventas DESC + LIMIT 5' | queryDB() %} +``` + +## `hook` — Ejecutar PHP hook + +```twig +{# Llamar y mostrar resultado #} +{{ 'hooks/module_id/' | hook({param1: 'value', param2: variable}) }} + +{# Capturar en variable #} +{% set result = 'hooks/calcular_precio/' | hook({cantidad: 5, tipo: 'mayoreo'}) %} +

    Total: ${{ result.total }}

    +``` + +El primer argumento es la ruta del endpoint del hook (`hooks//`). El objeto pasa los parámetros, que el PHP recibe como variables (`$cantidad`, `$tipo`). + +## `module` — Renderizar otro módulo + +```twig +{{ 'other_module_id' | module({param1: value1}) }} + +{# Capturar en variable #} +{% set carrito = 'carrito_compras' | module({usuario_id: 123}) %} +``` + +Equivale a ``. + +## `imagec` — Optimizar imágenes + +```twig +{# Redimensionar a ancho específico #} + + +{# Con srcset #} + +``` + +Acai genera versiones optimizadas (webp + tamaños) y las cachea. Usa siempre `imagec` para imágenes en producción. + +## `translate` — Texto editable y traducción + +Cualquier string con `| translate` se resuelve contra la tabla `textos_generales` del proyecto. Cumple **dos funciones a la vez**: + +1. **Traducción**: cada fila guarda la versión del texto por cada idioma habilitado. +2. **Edición de contenidos**: es el canal oficial para que el usuario final modifique esos textos sin tocar código. `| translate` no es solo i18n — es el mecanismo por el que un texto "hardcodeado" se vuelve editable desde el CMS. + +```twig +{{ 'Bienvenido' | translate }} +{{ variable | translate }} +{{ 'Contáctanos' | translate | raw }} +``` + +Cómo funciona: +- Los strings envueltos en `| translate` se buscan en `textos_generales`. +- Si existe la fila, devuelve el valor guardado (en el idioma activo). +- Si no existe, devuelve el texto original tal cual (fallback). +- Las filas se editan desde el admin del CMS o vía `CmsApi` (update sobre `textos_generales`). + +Reglas críticas: +- **NO crees archivos JSON de traducciones, `.po`, ni ningún sistema i18n externo.** El único sistema de textos traducibles/editables es la tabla `textos_generales`. +- **NO hardcodees textos en el código del módulo** si el usuario debe poder editarlos. Envuélvelos en `| translate`. +- Para **cambiar un texto** (traducir o editar), edita la fila correspondiente en `textos_generales` — nunca modifiques el código. +- Para **añadir un texto nuevo editable**, basta con escribir el string con `| translate` en el código; el sistema lo recoge y el usuario lo puede editar desde el admin. + +## Filtros estándar + +### `raw` — Renderizar HTML sin escapar + +```twig +{{ record.description | raw }} +``` + +Imprescindible para `wysiwyg` y para HTML construido en variables. + +### `truncate` — Truncar texto + +```twig +{{ record.description | truncate(150) }} +``` + +### `json_decode` — Parsear JSON + +```twig +{% set data = jsonString | json_decode %} +{{ data.key }} +``` + +### `split`, `filter`, `length`, `default`, `lower`, `upper`, `trim`, `replace` + +Funcionan igual que en Twig estándar. + +```twig +{{ title | default('Sin título') }} +{{ items | length }} +{{ name | upper }} +``` + +## Operadores y sintaxis + +### Concatenación con `~` + +Twig usa `~` (no `.` ni `+`): + +```twig +{{ 'Hello ' ~ name ~ '!' }} +{% set url = '/products/' ~ product.slug ~ '/' %} +``` + +En filtros: +```twig +{% set stock = 'stocks' | get('producto_num=' ~ producto.num) %} +``` + +### Ternario + +```twig +{{ isActive ? 'active' : 'inactive' }} +{{ title | default('Default Title') }} +``` + +### Comparaciones + +| Contexto | Igualdad | +|----------|----------| +| `c-if` | `=` (un solo igual) | +| `{% if %}` | `==` (doble igual) | + +```twig +{# Atributo Acai - un igual #} +
    + +{# Twig estándar - doble igual #} +{% if type == 'premium' %} +{% if items | length > 0 %} +{% if name is not empty %} +``` + +## Ejemplos complejos + +### Galería con productos y stock + +```twig +{% for producto in 'productos' | get('destacado=1', 'num DESC', 12) %} +
    + {{ producto.titulo }} +

    {{ producto.titulo }}

    +

    {{ producto.descripcion | truncate(100) }}

    + + {% set stock = 'stocks' | get('producto_num=' ~ producto.num) %} + Stock: {{ stock[0].cantidad }} +
    +{% endfor %} +``` + +### Múltiples filtros combinados + +```twig +{% set categorias = 'categorias' | get() %} +{% set productos = 'productos' | get('activo=1', 'titulo ASC', 20) %} +{% set stats = 'hooks/obtener_stats/' | hook({fecha_inicio: '2024-01-01'}) %} + +

    {{ stats.titulo | translate }}

    + + + +{% for prod in productos %} +
    + +

    {{ prod.titulo }}

    +
    +{% endfor %} +``` + +### Composición con `` y configuración global + +```twig + +{% set logoUrl = tienda.logo.0.urlPath + ? 'https://' ~ server.HTTP_HOST ~ tienda.logo.0.urlPath + : 'https://' ~ server.HTTP_HOST ~ '/template/estandar/images/logo.png' %} + +{{ tienda.nombre }} +``` + +## Reglas críticas + +1. **Solo filtros, nunca funciones.** `'tabla' | get()`, no `get('tabla')`. +2. **Tablas sin prefijo `cms_`** en `get()`. **Con prefijo `cms_`** en `queryDB()`. +3. **Upload fields son arrays.** `record.imagen[0].urlPath`, no `record.imagen`. +4. **Concatenación con `~`**, no con `.` ni `+`. +5. **`c-if` usa `=`**, **`{% if %}` usa `==`**. +6. **Foreign keys con sufijo `_num`**: `categoria_num`, no `categoria_id`. +7. **`enlace` ya tiene barras** — no las añadas. +8. **PK siempre es `num`**, nunca `id`. +9. **`| translate` para textos editables** — nunca crees JSONs de i18n. +10. Usa `imagec(width)` para imágenes en producción. diff --git a/docs/03-modules-and-sections.md b/docs/03-modules-and-sections.md new file mode 100644 index 0000000..e941c85 --- /dev/null +++ b/docs/03-modules-and-sections.md @@ -0,0 +1,200 @@ +# Módulos y Secciones Generales + +Este documento explica el sistema modular de Acai: la diferencia entre **módulos** (componentes visuales reutilizables que el usuario coloca en páginas Builder) y **secciones generales** (plantillas ligadas a una tabla que se renderizan automáticamente al acceder al `enlace` de un registro). Cubre la estructura de archivos de un módulo, las reglas obligatorias sobre `index-base.tpl`, las variables globales (`section_id`, `interno`, `server.HTTP_HOST`, `loop`), la convención `custom-{tableName}` para detalles de registro, la inclusión de un módulo dentro de otro y el uso de `thisrecord` en secciones generales. Léelo antes de crear, mover o editar cualquier carpeta dentro de `template/estandar/modulos/`. + +## Módulos + +Componentes visuales reutilizables. Viven en `template/estandar/modulos//`. El usuario los arrastra al builder de una página y rellena sus variables. + +### Estructura de archivos + +``` +/ +├── index-base.tpl # Plantilla source (Twig + atributos Acai) — EDITA ESTE +├── index.tpl # Compilado (auto-generado) — NO TOCAR +├── index-twig.tpl # Compilado Twig (auto-generado) — NO TOCAR +├── builder.json # Variables del builder (auto-generado) — NO TOCAR +├── style.css # CSS del módulo (estático) +├── script.js # JS del módulo (estático) +└── hook.php # Hook PHP propio del módulo (opcional) +``` + +Reglas duras: +- **Solo se edita `index-base.tpl`.** `index.tpl`, `index-twig.tpl` y `builder.json` los genera el compilador y se sobrescriben automáticamente. +- Editar `index-base.tpl` con `acai-write` o `acai-line-replace` **dispara la compilación automática**. +- `script.js` y `style.css` son **estáticos** — NO uses sintaxis Twig dentro. Pasa valores dinámicos vía atributos `data-*`. +- `index-base.tpl` solo contiene HTML/Twig. **Nunca** embebas etiquetas ` +``` + +Reglas: +- **Siempre** redefine `delimiters` a `['${', '}']` para no chocar con Twig. +- Mountea sobre un id único usando `section_id`: `#app-{{ section_id }}`. +- Vue se carga como librería global vía `add_global_library` o ya incluida en el proyecto (ver `08-layout-and-libraries.md`). + +## Variables globales disponibles en JS / Twig + +| Variable | Descripción | Ejemplo | +|----------|-------------|---------| +| `section_id` | ID único por instancia del módulo | `
    ` | +| `server.HTTP_HOST` | Dominio actual | `https://{{ server.HTTP_HOST }}/path` | +| `loop.index` | Índice 1-based en `c-for`/`{% for %}` | `{{ loop.index }}` | +| `loop.index is odd` / `is even` | Para layouts alternados | zigzag | +| `interno` | `true` dentro del editor CMS | `c-class="{'editor-mode': interno}"` | + +### Patrón `section_id` + +Cada instancia de un módulo recibe un `section_id` único. Úsalo para anchors, IDs HTML y selector raíz de JS: + +```html +
    +
    + +
    +``` + +## Componentes nativos + +### Carousel — `c-tns-wrapper` + +```html +
    +
      +
    • + +
      • +
    +
    +``` + +| Atributo | Descripción | +|----------|-------------| +| `data-responsive` | Items por breakpoint. JSON `{"0":1,"768":2,"1024":3}` o sintaxis corta `"sm:2, md:3, lg:4"` | +| `data-autoplay-timeout` | Intervalo autoplay (ms) | +| `data-mode` | `"gallery"` o `"carousel"` | +| `data-speed` | Velocidad de transición (ms) | +| `data-nav` | `"true"` para mostrar dots | + +Dots de navegación custom: +```html +
    +
    +
    +
    +``` + +### Lightbox + +```html + + + +``` + +### Breadcrumb + +```html + +``` + +### Animate On Scroll (AOS) + +```html +
    Contenido
    +``` + +Valores comunes: `fade-up`, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-in-up`, `fade-up-right`, `fade-up-left`. + +Tras cambios dinámicos en JS: +```js +AOS.refresh(); +``` + +### Lazy loading + +```html + + + + + +``` + +## Reglas críticas + +1. `script.js` y `style.css` son **estáticos** — sin sintaxis Twig dentro. +2. Para valores dinámicos en JS, pásalos desde `index-base.tpl` vía atributos `data-*`. +3. Define una **clase raíz en kebab-case** por módulo. Scopea TODO el CSS/JS bajo ella. +4. Tailwind first; CSS custom solo donde Tailwind no llegue, siempre con BEM. +5. Vue 3: redefine `delimiters: ['${', '}']` para evitar conflicto con Twig. +6. Mountea Vue sobre `#app-{{ section_id }}`. +7. Usa las clases utilitarias de Acai (`transition3s`, `lazyload`, `bg-main-color`, etc.) antes de inventar utilidades. +8. NO embebas lógica ` -``` - -Siempre usar `'${'` y `'}'` como delimitadores Vue para evitar conflicto con Twig. - ---- - -## Variables Globales Disponibles - -| Variable | Descripción | Ejemplo | -|----------|-------------|---------| -| `section_id` | ID único por instancia del módulo | `
    ` | -| `server.HTTP_HOST` | Dominio actual | `https://{{ server.HTTP_HOST }}/path` | -| `loop.index` | Índice de iteración (1-based) en c-for/for | `{{ loop.index }}` | -| `loop.index is odd` | True en iteraciones impares | Layouts alternados | -| `loop.index is even` | True en iteraciones pares | Patrones zigzag | -| `interno` | True dentro del editor CMS | `c-class="{'editor-mode': interno}"` | - -### Patrón section_id - -Cada instancia de módulo recibe un `section_id` único. Usar para navigation anchor e IDs: - -```html -
    -
    - -
    -``` - ---- - -## Componentes Nativos - -### Carousel (`c-tns-wrapper`) - -```html -
    -
      -
    • - -
      • -
    -
    -``` - -| Atributo | Descripción | Ejemplo | -|----------|-------------|---------| -| `data-responsive` | Items por breakpoint | `"sm:2, md:3, lg:4"` | -| `data-autoplay-timeout` | Intervalo autoplay (ms) | `"5000"` | -| `data-mode` | Modo de transición | `"gallery"` o `"carousel"` | -| `data-speed` | Velocidad de transición (ms) | `"400"` | -| `data-nav` | Puntos de navegación | `"true"` | - -Dots de navegación custom: -```html -
    -
    -
    -
    -``` - -### Lightbox - -```html - - - -``` - -### Breadcrumb - -```html - -``` - -### AOS (Animate On Scroll) - -```html -
    Contenido
    -``` - -Valores comunes: `fade-up`, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-in-up`, `fade-up-right`, `fade-up-left` - -Después de cambios dinámicos: `AOS.refresh()` en JavaScript. - -### Lazy Loading - -```html - - - - - -``` - ---- - -## Buenas prácticas - -- HTML/Twig semántico -- Código limpio y organizado -- Evitar dependencias externas innecesarias -- Evitar estilos inline salvo casos justificados (colores dinámicos del usuario) -- No usar clases globales sin prefijo de módulo diff --git a/docs/hooks-and-api.md b/docs/hooks-and-api.md deleted file mode 100644 index 4b4190f..0000000 --- a/docs/hooks-and-api.md +++ /dev/null @@ -1,389 +0,0 @@ -# Hooks & Server-Side API - -## Hooks - -Hooks son archivos PHP que ejecutan lógica server-side. Pueden existir en dos sitios: -- Hooks globales en `hooks/hooks..php` -- Hooks propios de módulo en `template/estandar/modulos//hook.php` - -### Tipos de hooks - -**1. Hook global** -- Archivo: `hooks/hooks..php` -- Endpoint: `/hooks//` -- Úsalo cuando la lógica se reutiliza entre módulos, páginas o formularios - -**2. Hook propio de módulo** -- Archivo: `template/estandar/modulos//hook.php` -- Endpoint: `/hooks//` -- Úsalo cuando la lógica pertenece solo a ese módulo - -Ejemplos: -- `hooks/hooks.buscar_barcos.php` -> `/hooks/buscar_barcos/` -- `template/estandar/modulos/hero_banner/hook.php` -> `/hooks/hero_banner/` - -Regla práctica: -- Si el hook solo sirve a un módulo, créalo dentro del módulo -- Si varias piezas del proyecto lo van a consumir, créalo como hook global - -## Reglas obligatorias para hooks - -- Un hook debe devolver datos con `return [...]` -- No uses `echo json_encode(...)` -- No uses `exit` -- Para leer parámetros, usa `$_REQUEST[...]` o las variables ya inyectadas por el sistema -- En hooks, usa `CmsApi::get()` o `CocoDB::get()` como primera opción -- No uses `CocoDB::getInstance()` salvo necesidad real muy excepcional -- No escribas SQL manual con `prepare()/bind_param()` salvo que no exista forma razonable de resolverlo con `CmsApi` o `CocoDB` - -### Estructura de un Hook - -```php - true, - "message" => "Valor procesado: " . $resultado, - "value" => $resultado -]; -?> -``` - -### Testing Hooks - -El Docker debe estar corriendo. Hacer curl al endpoint del hook: - -```bash -curl {ACAI_WEB_URL}/hooks/example_hook/ -``` -(Use the project's actual URL, never localhost:8080) - -No usar X-Hooks-Token en desarrollo local. - -### Cómo Llamar Hooks - -La referencia siempre se hace con el endpoint `/hooks//`: -- Para hooks globales, `` es el nombre lógico del hook sin `hooks.` ni `.php` -- Para hooks de módulo, `` es el `module-id` de la carpeta del módulo - -**Desde HTML (recomendado para módulos):** -```html - -

    {{ myVar.message }}

    -``` - -**Desde Twig:** -```twig -{% set resultado = 'hooks/mimodulo/' | hook({param1: 100, param2: 'texto'}) %} -

    {{ resultado.message }}

    -``` - -**Desde JavaScript:** -```js -CmsApi.hook('/hooks/mimodulo/', {param1: 100, param2: 'texto'}, (data) => { - console.log(data.message); -}); -``` - -**Ejemplo real para hook de módulo:** -```js -// Módulo: template/estandar/modulos/buscadorapartados_hjd8s/ -CmsApi.hook('/hooks/buscadorapartados_hjd8s/', { termino: 'vela' }, (data) => { - console.log(data); -}); -``` - -**Desde otro Hook PHP:** -```php - 100, "param2" => "texto"]); -$mensaje = $result["message"]; -?> -``` - -**Desde c-form:** Los hooks se ejecutan automáticamente al enviar el formulario si están configurados. - ---- - -## CmsApi (PHP) - -API server-side para operaciones de base de datos. Disponible en todos los hooks. - -### Read — `CmsApi::get()` - -## IMPORTANTE : Las tablas y nombres de campos puedes extraerlas de los esquemas en cms/data/schema/.ini.php - -```php -// Todos los registros -$products = CmsApi::get("productos"); - -// Con condición WHERE en string -$active = CmsApi::get("productos", "active=1"); - -// Con orden y límite -$latest = CmsApi::get("noticias", "", "fecha DESC", 5); - -// Con condición string -$activos = CmsApi::get("productos", "activo=1"); - -// Condición compleja -$caros = CmsApi::get("productos", "precio > 100"); - -// Múltiples condiciones (AND) -$resultados = CmsApi::get("productos", "activo = 1 AND stock > 0"); - -// Con operadores -$expensive = CmsApi::get("productos", "precio >= 100"); -$search = CmsApi::get("productos", "nombre LIKE '%keyword%'"); -$inList = CmsApi::get("productos", "categoria_num IN (1, 2, 3)"); - -#### Opciones de `get()` - -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `uploads` | bool | `true` | Incluir datos de upload fields | -| `relations` | bool/array | `true` | Resolver foreign keys. Array para limitar: `['category']` | -| `relationsDepth` | int | 2 | Profundidad de relaciones anidadas | -| `translates` | string | current lang | Código de idioma | -| `groupBy` | string | null | GROUP BY clause | -| `aggregates` | array | `[]` | Funciones de agregación | -| `onlyFields` | array | null | Seleccionar solo campos específicos | -| `debug` | bool | false | Mostrar SQL query | -| `redis` | bool | null | Forzar cache Redis | -| `redis_expire` | int | 60 | TTL de cache Redis (segundos) | - -// Con opciones -$datos = CmsApi::get("productos", "", "", "", [ - 'translates' => true, - 'uploads' => true, - 'relations' => true, - 'relationsDepth' => 2 -]); -``` - -### Insert — `CmsApi::insert()` - -## IMPORTANTE : Las tablas y nombres de campos puedes extraerlas de los esquemas en cms/data/schema/.ini.php - -```php -// Un registro -CmsApi::insert('contacto', [ - ["nombre" => "John", "email" => "john@example.com", "mensaje" => "Hello"] -]); - -// Múltiples registros -CmsApi::insert('productos', [ - ["nombre" => "Producto A", "precio" => 100], - ["nombre" => "Producto B", "precio" => 200] -]); - -// Con retorno del último ID -CmsApi::insert('productos', - [["nombre" => "Nuevo", "precio" => 150]], - [], - ['return_last_id' => true] -); -``` - -#### Opciones de insert - -| Option | Description | -|--------|-------------| -| `forceNum` | Permite setear el campo `num` manualmente | -| `ignoreSchema` | Saltar validación de schema | -| `ignoreFields` | Array de campos a ignorar | - - -### Update — `CmsApi::update()` - -## IMPORTANTE : Las tablas y nombres de campos puedes extraerlas de los esquemas en cms/data/schema/.ini.php - -```php -// Con condición string -CmsApi::update('productos', ["precio" => 150], "num=1"); - -// Con condición array -CmsApi::update('productos', - ["activo" => 1], - [["column" => "num", "operator" => "=", "value" => 1]] -); - -// Múltiples registros -CmsApi::update('productos', ["activo" => 0], "precio < 50"); -``` - -#### Opciones de update - -| Option | Description | -|--------|-------------| -| `forceNum` | Permite setear el campo `num` manualmente | -| `ignoreSchema` | Saltar validación de schema | -| `ignoreFields` | Array de campos a ignorar | - - -### Delete — `CmsApi::delete()` - -## IMPORTANTE : Las tablas y nombres de campos puedes extraerlas de los esquemas en cms/data/schema/.ini.php - -```php -CmsApi::delete('productos', "num=5"); - -CmsApi::delete('productos', - [["column" => "activo", "operator" => "=", "value" => 0]] -); -``` - -### Reglas importantes - -- Nombres de tabla **sin** prefijo `cms_` -- Primary key siempre es `num`, nunca `id` -- Foreign keys: `categoria_num`, no `categoria_id` -- Upload fields: no se manejan via insert/update -- Operadores: `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN` - ---- - -## CmsApi (JavaScript — Client-Side) - -```js -// Llamar hook -CmsApi.hook('/hooks/module_id/', { param: 'value' }, function(response) { - // response es la salida del hook -}); - -// Leer registros (si está expuesto via hooks) -CmsApi.get('tableName', { where: conditions }, function(records) { - // records array -}); -``` - ---- - -## CocoDB - -Capa de abstracción de BD de bajo nivel usada internamente por CmsApi. Usar directamente desde hooks cuando necesites más control. - -Para búsquedas y lecturas habituales, prioriza: -1. `CmsApi::get()` -2. `CocoDB::get()` -3. SQL manual solo si de verdad no hay alternativa razonable - -### `CocoDB::get($table, $where, $order, $limit, $options)` -## Funcionalidad exactamente igual a CmsApi::get ( ver referencia CmsApi::get ) - - -### `CocoDB::insertRecords($table, $records, $functions, $options)` -## Funcionalidad exactamente igual a CmsApi::insert ( ver referencia CmsApi::insert ) - -### `CocoDB::updateRecords($table, $records, $where, $functions, $options)` -## Funcionalidad exactamente igual a CmsApi::update ( ver referencia CmsApi::update ) - - -### `CocoDB::deleteRecords($table, $where, $options)` -## Funcionalidad exactamente igual a CmsApi::delete ( ver referencia CmsApi::delete ) - ---- - -## Creación y Actualización de Registros - -### Flujo correcto - -1. Consultar el esquema de la tabla (leer `cms/data/schema/{tabla}.ini.php`) -2. Revisar los tipos de campo -3. Rellenar según el tipo de dato -4. Enviar con la estructura correcta - -### Tipos de campo y formato - -| Tipo | Formato | Ejemplo | -|------|---------|---------| -| **Text field** | String | `"Texto"` | -| **Text box** | String multilínea | `"Línea 1\nLínea 2"` | -| **Date/time** | `YYYY-MM-DD HH:mm:ss` | `"2025-12-03 10:30:00"` | -| **Wysiwyg** | String HTML | `"

    Texto

    "` | -| **List** | String o número | `"activo"` o `"1"` (num si es foreign key) | -| **Checkbox** | Número 1/0 | `1` o `0` | -| **Multivalores** | String JSON | `"[{\"producto\":\"1\"}]"` | -| **Upload** | **NO enviar** — usar `upload_record_image` después de crear el registro | - ---- - -## Table Schemas - -Los schemas están en `cms/data/schema/` como archivos `.ini.php`. Definen: -- Nombres y tipos de campo -- Reglas de validación -- Relaciones (foreign keys) -- Configuración de display - ---- - -## Ejemplos Prácticos - -### Hook de Cálculo de Precio - -```php - 10) { - $precioUnitario *= 0.85; // 15% descuento -} - -return [ - "success" => true, - "precioUnitario" => round($precioUnitario, 2), - "total" => round($precioUnitario * $cantidad, 2), - "descuento" => $tipo === 'mayoreo' ? 15 : 0 -]; -?> -``` - -```html - -

    Total: ${{ precio.total }}

    -``` - -En este ejemplo, el endpoint usa `calcular_precio` porque el archivo vive en: -`template/estandar/modulos/calcular_precio/hook.php` - -### Hook con Operaciones de BD - -```php - false, "message" => "Producto no encontrado"]; -} - -$total = $producto[0]['precio'] * $cantidad; - -// Crear venta -CmsApi::insert('ventas', [[ - "usuario_num" => $usuario_id, - "producto_num" => $producto_id, - "cantidad" => $cantidad, - "total" => $total, - "fecha" => date('Y-m-d H:i:s') -]], [], ['return_last_id' => true]); - -// Actualizar stock -$stock = CmsApi::get("stocks", "producto_num=" . $producto_id); -if (!empty($stock)) { - CmsApi::update('stocks', - ["cantidad" => $stock[0]['cantidad'] - $cantidad], - "producto_num=$producto_id" - ); -} - -return ["success" => true, "total" => $total]; -?> -``` diff --git a/docs/knowledge-index-base.md b/docs/knowledge-index-base.md deleted file mode 100644 index b574e6a..0000000 --- a/docs/knowledge-index-base.md +++ /dev/null @@ -1,159 +0,0 @@ -# Acai CMS — Project Instructions - -This is an Acai CMS website project. Follow these instructions when working with the codebase. - -## Environment - -- The site runs in Docker. **Before using fetch or Playwright, call the `get_web_url` tool** to get the correct development URL. Never hardcode or guess URLs. -- **ALWAYS append `?pruebas=1`** to any URL you visit (e.g. `http://.../?pruebas=1`). This query param is required to view the site in development mode. -- **NEVER navigate to the production domain** (e.g. `keepsailing.es`, `tienda.com`). The production site is NOT your development environment. -- **NEVER use localhost:8080 or https://** — use HTTP (not HTTPS) with the URL from `get_web_url`. - -## Project Structure - -``` -. -├── template/estandar/ -│ ├── modulos/ # Builder modules (visual components) -│ │ └── / -│ │ ├── index-base.tpl # Twig template (source — EDIT THIS) -│ │ ├── style.css # Module styles -│ │ └── script.js # Module JavaScript -│ │ ├── index.tpl # Compiled (auto-generated, do NOT edit) -│ │ ├── index-twig.tpl # Compiled (auto-generated, do NOT edit) -│ │ └── builder.json # Compiled builder vars (auto-generated, do NOT edit) -│ ├── css/ # Global CSS -│ └── js/ # Global JavaScript -├── hooks/ # PHP hooks (server-side logic) -├── cms/ -│ ├── data/schema/ # Database table schemas (JSON) -│ ├── lib/plugins/ # CMS plugins -│ └── uploads/ # Uploaded media files -├── .acai # Project config (domain, tokens, DB credentials) -├── .docker/ -│ ├── .env # Docker environment (DB credentials) -│ ├── docker-compose.yml -│ ├── tunnel-url.txt # Public tunnel URL (if active) -│ └── bore-db-url.txt # Database tunnel URL (if active) -└── database.sql # Database dump -``` - -## Key Concepts - -### Modules (`template/estandar/modulos/`) -Visual components that the site builder uses. Each module is a self-contained unit with its own template (Twig + Acai attributes), CSS, and JS. Modules are placed on pages via the drag-and-drop builder. The editable file is always `index-base.tpl`. - -- Include other modules: `` -- Each module instance gets a unique `section_id` variable for anchors/scoping -- Use `interno` variable to detect CMS editor mode vs public view - -See [docs/modular-system.md](docs/modular-system.md) for detailed rules. - -### Pages -Every record with an `enlace` field is a page. Pages are either **Builder** (modular) or **Standard**: - -- **Builder**: `controlador` = `cms/lib/plugins/builder_saas/controlador.php` — content via modules -- **Standard**: `controlador` = `cms/lib/plugins/builder_saas/controlador_tabla.php` — content in record fields - -**Critical**: Never change `enlace` or `controlador` of existing pages unless explicitly asked. - -See [docs/pages-and-records.md](docs/pages-and-records.md) for full details. - -### General Sections -Database-backed templates (headers, footers, record views) that use the `thisrecord` variable to access record fields. They use the same Twig + Acai attribute engine as modules. - -- Upload fields return arrays: `thisrecord.image[0].urlPath` -- Foreign keys use `_num` suffix: `category_num` - -See [docs/modular-system.md](docs/modular-system.md) for details. - -### Hooks (`hooks/`) -PHP files that execute server-side logic. Triggered by: -- Twig filter: `'hooks/module_id/' | hook({param: value})` -- HTML tag: `` -- JavaScript: `CmsApi.hook('/hooks/module_id/', {param: value}, callback)` -- Form action: via `c-form` attribute - -There are two valid hook locations: -- Global hooks in `hooks/hooks..php` for reusable/shared server-side logic -- Module-specific hooks in `template/estandar/modulos//hook.php` for logic owned by a single module - -How to reference them: -- Global hook `hooks/hooks.calcular_precio.php` -> endpoint `/hooks/calcular_precio/` -- Module hook `template/estandar/modulos/hero_banner/hook.php` -> endpoint `/hooks/hero_banner/` -- Module hook `template/estandar/modulos/buscadorapartados_hjd8s/hook.php` -> endpoint `/hooks/buscadorapartados_hjd8s/` - -Rule of thumb: -- If the logic is only used by one module, prefer that module's `hook.php` -- If the logic will be reused by several modules/pages, create a global hook in `hooks/` -- Return arrays from hooks; do not use `echo json_encode(...)` or `exit` - -See [docs/hooks-and-api.md](docs/hooks-and-api.md) for usage. - -## Database Access - -When the site is running in Docker, you can connect to the database: - -- **Host:** `127.0.0.1` -- **Port:** Check `.docker/docker-compose.yml` for the mapped port (usually 3307+) -- **Credentials:** Read from `.docker/.env`: - - `DB_USERNAME` - - `DB_PASSWORD` - - `DB_DATABASE` - -```bash -docker exec -it dw--db mysql -u root -p -``` - -**Important:** Table names in CmsApi/Twig do NOT use the `cms_` prefix. The primary key is always `num`, never `id`. - -## Acai Core (web-base) - -The project workspace contains only the **customization layer** (modules, hooks, schemas, uploads). The CMS core (routing, rendering engine, admin panel, APIs) lives in a separate directory called **web-base** that is mounted as a Docker volume. - -The web-base path can be obtained via: `GET http://localhost:9090/api/web-base-path` - -Do NOT modify web-base files — they are shared across all projects. - -## Critical Rules - -1. **Before working with any area (hooks, modules, templates, CSS/JS, etc.), read the corresponding documentation in `docs/` first.** Do not guess or assume — always consult the docs before taking action. -2. **NEVER use `mkdir` to create directories.** Instead, use `acai-write` to create the first file inside the directory — this creates parent directories automatically. For example, to create a new module, directly write the `index-base.tpl` file. -3. Only edit `index-base.tpl` in modules — `index.tpl`, `index-twig.tpl`, and `builder.json` are auto-generated -4. Editing or creating any `index-base.tpl` through `acai-write` or `acai-line-replace` triggers automatic compilation. `compile_module` is only for manual recovery when you need to force a recompile without changing the file. -5. `script.js` and `style.css` are static files — do NOT use Twig syntax inside them. Pass dynamic values from `index-base.tpl` via `data-*` attributes. -6. Use Twig **filters** (with `|`), never Twig functions -7. Table names without `cms_` prefix everywhere -8. Primary key is `num`, never `id` -9. Upload fields are arrays — access with `[0].urlPath` -10. Tailwind CSS as primary styling, custom CSS scoped with BEM when needed -11. Twig concatenation uses `~` operator: `'value=' ~ variable` -12. `enlace` (link) fields already include slashes — **NEVER modify an existing enlace** unless explicitly asked -13. **NEVER modify the `controlador` field** of existing records — it defines whether a page is Builder or Standard - -## MCP Tools - -This project has MCP tools for managing modules, records, media, and more. **Before starting any task, consult the tools reference for the correct workflow.** - -See [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) for the complete list of available tools and step-by-step workflows. - -Key workflows: -- **Create module**: Read [docs/module-creation-guide.md](docs/module-creation-guide.md) first → create files with `acai-write` / refine with `acai-line-replace` → automatic compile on `index-base.tpl` → `add_module_to_record` (returns sectionId) → `set_module_config_vars` (returns uploadFields) → images via uploadFields. Use `compile_module` only if you need a manual recompile without editing the file. -- **Edit module**: `acai-view` → `acai-line-replace` (or `acai-write` for full rewrites) → automatic compile on `index-base.tpl` -- **Add images**: use `uploadFields` from `set_module_config_vars` response → `upload_record_image` -- **Generate images**: `generate_image` → `upload_record_image` with returned URL - -## Documentation - -- [docs/modular-system.md](docs/modular-system.md) — Modules, general sections, global variables -- [docs/builder-fields.md](docs/builder-fields.md) — Builder field types, Acai attributes, c-form, components -- [docs/twig-filters.md](docs/twig-filters.md) — Twig filters reference (get, hook, module, queryDB, etc.) -- [docs/hooks-and-api.md](docs/hooks-and-api.md) — PHP hooks, CmsApi, CocoDB, record creation -- [docs/css-js-conventions.md](docs/css-js-conventions.md) — CSS/JS/Vue 3, Tailwind, BEM, native components -- [docs/quick-reference.md](docs/quick-reference.md) — Cheat sheet: domain rules, field types, filters -- [docs/production-patterns.md](docs/production-patterns.md) — Real production patterns (header, zigzag, FAQ, forms) -- [docs/vue-builder-rules.md](docs/vue-builder-rules.md) — CMS-VUE rules (tabs, colorpicker, components) -- [docs/vue-builder-examples.md](docs/vue-builder-examples.md) — Vue builder examples (Banner Slideshow, etc.) -- [docs/pages-and-records.md](docs/pages-and-records.md) — Page types (Builder vs Standard), sections, visibility, critical rules -- [docs/module-creation-guide.md](docs/module-creation-guide.md) — Module creation workflow, style reference, field types -- [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) — MCP tools reference, available tools, workflows diff --git a/docs/mcp-tools-reference.md b/docs/mcp-tools-reference.md deleted file mode 100644 index 4da3f14..0000000 --- a/docs/mcp-tools-reference.md +++ /dev/null @@ -1,159 +0,0 @@ -# MCP Tools Reference - -## Quick Reference - -| Tool | Categoría | Acción | -|------|-----------|--------| -| `compile_module` | Módulos | Recompilación manual de rescate cuando necesitas forzar la compilación sin editar el archivo | -| `check_module` | Módulos | Preview de cómo renderiza un módulo | -| `check_module_usage` | Módulos | Qué páginas usan un módulo | -| `acai-view` | Archivos | Lee un archivo del proyecto por tramos | -| `acai-glob` | Archivos | Busca rutas de archivos por patrón | -| `acai-grep` | Archivos | Busca texto en archivos del proyecto | -| `acai-line-replace` | Archivos | Reemplaza un bloque concreto en un archivo existente | -| `acai-write` | Archivos | Crea o reescribe un archivo completo. Antes de usarlo, lee la doc correspondiente según el tipo de archivo (`module-creation-guide`, `builder-fields`, `css-js-conventions`, `hooks-and-api`) | -| `acai-delete` | Archivos | Borra un archivo del proyecto | -| `list_page_modules` | Registros | Lista módulos de una página | -| `add_module_to_record` | Registros | Añade módulo a una página | -| `remove_module_from_record` | Registros | Elimina módulo de una página | -| `reorder_module` | Registros | Cambia posición de un módulo | -| `toggle_module_visibility` | Registros | Muestra/oculta módulo | -| `get_module_config_vars` | Registros | Lee variables de un módulo | -| `set_module_config_vars` | Registros | Escribe variables de un módulo | -| `list_table_records` | Registros | Buscar/listar registros con filtros | -| `get_record` | Registros | Obtener un registro por num | -| `create_or_update_record` | Registros | Crear o actualizar registros | -| `delete_table_records` | Registros | Eliminar registros (destructivo) | -| `upload_record_image` | Media | Subir imagen a campo de registro (desde URL) | -| `generate_image` | Media | Generar imagen con IA y guardar en uploads | -| `upload_image_to_assets` | Media | Subir imagen a /images/ del template | -| `list_record_uploads` | Media | Listar uploads de un campo | -| `replace_record_image` | Media | Reemplazar imagen existente | -| `delete_record_upload` | Media | Borrar upload | -| `reorder_record_uploads` | Media | Reordenar imágenes de un campo | -| `refresh_acai_token` | Auth | Renovar token JWT expirado | -| `navigate_browser` | Navegación | Navegar el browser del frontend a una URL | -| `save_project_styles` | Proyecto | Guardar resumen de estilos en docs/project-styles.md | -| `rollback_git` | Git | Recuperar cambios de git remoto | -| `get_layout_field` | Layout | Lee el source de los campos globales del layout.json: style, javascript, header, footer | -| `set_layout_field` | Layout | Reemplaza un campo global del layout.json. **USA ESTA TOOL** para editar header/footer — NO toques los .tpl directos | - -## Flujos de trabajo - -### Crear un módulo nuevo desde cero - -1. `acai-write` — Crea `index-base.tpl`, `style.css`, `script.js` y cualquier hook necesario con rutas relativas al proyecto -2. `acai-write` o `acai-line-replace` compilan automáticamente al tocar `index-base.tpl` -3. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`) -4. `set_module_config_vars` — Rellena las variables con contenido (textos, colores, opciones). **OBLIGATORIO** — sin esto el módulo no muestra nada. Devuelve: - - `configVars`: mapa de variables → recordNums - - `uploadFields`: mapa de variables upload → `{ fieldName, recordNum }` — **usa estos directamente** para subir imágenes sin necesidad de leer builder.json - - Para vars multi con uploads: `uploadFields["varName.subVarName"]` es un array con `[{ index, fieldName, recordNum }]` -5. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del `uploadFields` devuelto en el paso 4 -6. Verificar con `check_module` o recargando la página - -### Editar un módulo existente - -1. `get_module_config_vars` — Leer el estado actual del módulo (variables, recordNums) -2. `acai-view` — Leer solo el tramo de `index-base.tpl` que se va a modificar -3. `acai-line-replace` — Editar el bloque concreto. Usa `acai-write` solo si el archivo es nuevo o el cambio es masivo -4. La compilación es automática tras cada edición de `index-base.tpl` -5. Si cambias variables: `set_module_config_vars` para actualizar valores - -### Editar archivos del proyecto con bajo consumo de tokens - -1. `acai-view` — Leer el archivo o un rango de líneas -2. `acai-glob` — Encontrar archivos relevantes por ruta cuando no conoces el path exacto -3. `acai-grep` — Buscar texto o atributos concretos dentro de archivos del proyecto -4. `acai-line-replace` — Reemplazar el bloque exacto en archivos existentes -5. `acai-write` — Crear archivos nuevos o reescribirlos por completo si es necesario -6. `acai-delete` — Borrar archivos solo cuando sea explícitamente necesario - -Reglas: -- Usa siempre rutas relativas al proyecto -- No edites `index.tpl`, `index-twig.tpl` ni `builder.json` — son auto-generados -- Tras editar cualquier `index-base.tpl` con las file tools, la compilación se ejecuta automáticamente - -### Añadir/modificar imágenes de un módulo - -**Tras `set_module_config_vars`** (método recomendado — sin pasos extra): -1. El response de `set_module_config_vars` incluye `uploadFields` con los `recordNum` y `fieldName` de cada variable upload -2. `upload_record_image` con `tableName: "builder_custom"`, `recordId` y `fieldName` del `uploadFields` -3. Para uploads dentro de vars multi: `uploadFields["records.imagen"]` devuelve array con `{ index, fieldName, recordNum }` por cada record - -**Sin haber llamado a `set_module_config_vars`**: -1. `get_module_config_vars` — Obtener el `recordNum` de builder_custom -2. Leer `builder.json` del módulo para encontrar el `fieldName` real (ej: `image1`, NO el nombre de la variable) -3. `upload_record_image` con: - - `tableName`: `"builder_custom"` (siempre sin cms_) - - `recordId`: el recordNum del paso 1 - - `fieldName`: el campo de relations del builder.json (ej: `image1`) - - `imageUrl`: usa la URL recomendada por la tool que generó/subió la imagen. En Forge, si `generate_image` devuelve `uploadUrl` o `fullUrl`, priorízala frente a `dockerUrl` - -### Generar imagen con IA - -1. `generate_image` con prompt descriptivo + style (photographic, digital-art, minimalist...) -2. La imagen se guarda en `cms/uploads/generated/` y devuelve una URL local de preview (`dockerUrl`) y, cuando aplica, una URL recomendada para subida (`uploadUrl` / `fullUrl`) -3. Para `upload_record_image`, usa la URL recomendada por la tool. En Forge, prioriza `uploadUrl` o `fullUrl` si están presentes - -### Gestionar registros de una tabla - -1. `list_table_records` — Buscar registros con filtros (`where`, `order`, `limit`) -2. `get_record` — Obtener un registro completo por num -3. `create_or_update_record` — Crear o actualizar (la tabla sin prefijo `cms_`, PK es `num`) -4. `delete_table_records` — Eliminar por IDs - -### Explorar el sitio - -1. `list_page_modules` — Ver qué módulos tiene cada página -2. `get_module_config_vars` — Ver los datos de cada módulo -3. `check_module` — Preview de cómo renderiza - -## Reglas importantes para todas las tools - -1. **tableName** siempre SIN prefijo `cms_` (ej: `apartados`, no `cms_apartados`) -2. **Primary key** es siempre `num`, nunca `id` -3. **Uploads** son arrays — acceder con `[0].urlPath` -4. **fieldName de imágenes** viene de `builder.json` → `vars.NOMBRE.relations.builder_custom` (ej: `image1`), NO del nombre de la variable -5. **recordId para imágenes** es el `num` de `builder_custom`, NO el sectionId del módulo -6. Tras `set_module_config_vars`, TODAS las variables del módulo (incluyendo upload) reciben config-vars automáticamente -7. Si el token expira (error 403), usar `refresh_acai_token` - -## Layout global (header, footer, style, javascript) - -Los 4 campos globales del proyecto (`style.css`, `script.js`, `header`, `footer`) viven en `cms/lib/plugins/builder_saas/layout.json`. - -### REGLA CRÍTICA - -**NUNCA uses `acai-view`, `acai-line-replace`, `acai-write` ni `acai-delete` sobre**: -- `cms/lib/plugins/builder_saas/layout.json` -- `template/estandar/modulos/custom-header-twig/*` -- `template/estandar/modulos/custom-footer-twig/*` -- `template/estandar/modulos/custom-header/*` -- `template/estandar/modulos/custom-footer/*` - -Esos ficheros son **artefactos generados** a partir del `layout.json`. Editarlos directamente provoca: -- Desincronización con `layout.json.{header,footer}ModuleCustom.htmlParsed`. -- Sobrescritura de tus cambios cuando el usuario abre el builder visual y guarda. -- Comportamiento inconsistente entre el render público y el builder. - -### Workflow correcto - -Para leer: -``` -get_layout_field({ field: "header" }) // devuelve el source Twig del header -get_layout_field({ field: "footer" }) -get_layout_field({ field: "style" }) // CSS global -get_layout_field({ field: "javascript" }) // JS global -``` - -Para editar: -``` -set_layout_field({ field: "footer", content: "
    ...nuevo HTML/Twig...
    " }) -``` - -El backend: -1. Escribe el source en `layout.json.{field}`. -2. Sincroniza `layout.json.{field}ModuleCustom.htmlParsed`. -3. Regenera los `.tpl` del módulo `custom-{field}-twig/`. -4. Compila el Twig a PHP. diff --git a/docs/modular-system.md b/docs/modular-system.md deleted file mode 100644 index ecec0c3..0000000 --- a/docs/modular-system.md +++ /dev/null @@ -1,105 +0,0 @@ -# Acai Modular System - -## Modules - -Modules are the visual building blocks of Acai websites. Each module lives in `template/estandar/modulos//`. - -### File Structure - -``` -/ -├── index-base.tpl # Source template (EDIT THIS) -├── index.tpl # Compiled output (auto-generated, do NOT edit) -├── index-twig.tpl # Compiled Twig output (auto-generated, do NOT edit) -├── builder.json # Compiled builder vars (auto-generated, do NOT edit) -├── style.css # Module-scoped styles -└── script.js # Module JavaScript -``` - -### Template Syntax - -Templates use a hybrid of **Twig** and **Acai attributes**. The source file is always `index-base.tpl`. - -```html -
    -
    -

    - Title here -

    -

    - Description text -

    - - Call to action -
    -
    -``` - -### Including Modules from Other Modules - -```html - -``` - -Parameters are received as variables inside the included module. - -### Global Variables - -| Variable | Description | -|----------|-------------| -| `section_id` | Unique ID per module instance (use for anchors, JS scoping) | -| `interno` | `true` when viewing in CMS editor, `false` on public site | -| `server.HTTP_HOST` | Current domain | -| `loop.index` | 1-based iteration index (inside `c-for`) | -| `loop.index is odd` / `loop.index is even` | For alternating layouts | - - -## General Sections - -General sections are database-backed templates used for record views, headers, footers, and reusable layouts. They use the same template engine as modules. - -### Key Differences from Modules - -- Access record data via the `thisrecord` variable -- Upload fields return **arrays**: `thisrecord.image[0].urlPath` -- Additional upload metadata: `info1` (alt text), `info2`, `info3`, `info4` -- Foreign key fields use `_num` suffix: `thisrecord.category_num` -- Saved via `save_general_section()` (not `save_module()`) -- Parser type 2 = Twig (recommended), 0 = Acai legacy syntax - -### Example: Record Template - -```html -
    - {{ thisrecord.imagen[0].info1 }} -

    {{ thisrecord.nombre }}

    -

    {{ thisrecord.descripcion | raw }}

    - {{ thisrecord.precio }}€ -
    -``` - -### Variable Assignment - -Use `` tag to create variables from queries: - -```html - - -``` - - -## Repeatable Content (multiv2) - -The `multiv2` builder field type creates repeatable groups of fields: - -```html -
    -

    {{ item.title }}

    -

    {{ item.description }}

    - -
    -``` - -Access individual items: `record.items[0].title`, `record.items[1].image`, etc. diff --git a/docs/module-creation-guide.md b/docs/module-creation-guide.md deleted file mode 100644 index 0e23bb6..0000000 --- a/docs/module-creation-guide.md +++ /dev/null @@ -1,100 +0,0 @@ -# Module Creation Guide - -## Style Reference - -When creating new modules, you MUST match the visual style of the existing project. Follow these steps IN ORDER: - -### Step 1: Check for `docs/project-styles.md` -- If the file exists → read it and use it as your style reference. DONE — skip to module creation. -- If the file does NOT exist → continue to Step 2. - -### Step 2: Determine if exploration is needed -- Count modules in `template/estandar/modulos/` that have `builder.json` and do NOT start with `custom-` -- If 3+ qualifying modules exist → continue to Step 3 -- If fewer than 3 → skip exploration, create the module based on the user's description. The style will be defined as modules are created. - -### Step 3: Explore and GENERATE the style guide (MANDATORY) -- Read `index-base.tpl` and `style.css` of 3-4 representative modules (only those with `builder.json`, skip `custom-*`) -- **You MUST then call `save_project_styles`** with a markdown summary including: - - Primary/secondary/accent colors (hex values) - - Font families and sizes used - - Spacing scale (padding/margin patterns) - - Common Tailwind classes and custom CSS patterns - - Button styles, card styles, section layouts - - Any recurring design patterns (gradients, shadows, borders, etc.) -- This saves `docs/project-styles.md` which will be read by future module creation tasks — no re-exploration needed. - -**After creating a module:** if `docs/project-styles.md` does not exist yet and there are now 3+ modules, call `save_project_styles`. - -## Module Structure - -Each module lives in `template/estandar/modulos//` with: -- `index-base.tpl` — Twig template (source — EDIT THIS) -- `style.css` — Module styles -- `script.js` — Module JavaScript -- `builder.json` — Compiled builder vars (auto-generated, do NOT edit) -- `index.tpl` / `index-twig.tpl` — Compiled (auto-generated, do NOT edit) - -## Creating a Module — Full Workflow - -If the module needs JavaScript, you MUST read `docs/css-js-conventions.md` before writing `index-base.tpl` or `script.js`. -If the module needs server-side logic, dynamic data processing, form handling, or reusable backend behavior, you MUST read `docs/hooks-and-api.md` before creating `hook.php` or any global hook. -If the module will call hooks from Twig, also review `docs/twig-filters.md` for the `hook` filter syntax. -If `index-base.tpl` contains builder fields (`data-field-type`), you MUST review `docs/builder-fields.md` before writing the template. - -Hard rules for module files: -- `index-base.tpl` is for HTML/Twig only -- `script.js` is for module JavaScript -- `style.css` is for module CSS -- `hook.php` is for server-side logic -- Do NOT embed `