ajustes

docs/11-quick-reference.md

@@ -0,0 +1,128 @@
+# Quick Reference — Cheat sheet
+
+Este documento es un **resumen ejecutable** de las reglas críticas, los tipos de campo, los filtros Twig, los formatos de datos para insert/update y las variables globales. Es la **fuente única de verdad** para resolver dudas rápidas sin tener que abrir los docs largos. Léelo antes de cualquier operación cuando quieras refrescar las reglas; el resto de docs (`01`–`10`) profundizan en cada tema.
+
+## Reglas inmutables
+
+| Regla | Correcto | Incorrecto |
+|-------|----------|------------|
+| Nombres de tabla en tools/Twig/CmsApi | `'productos'` | `'cms_productos'` |
+| Nombres en `queryDB` | `cms_productos` | `productos` |
+| Primary key | `record.num` | `record.id` |
+| Foreign keys | `categoria_num` | `categoria_id` |
+| Upload fields | `record.imagen[0].urlPath` | `record.imagen` |
+| Optimizar imagen | `imagen[0].urlPath \| imagec(800)` | `imagen.url` |
+| Filtros Twig | `{{ 'tabla' \| get() }}` | `{{ get('tabla') }}` |
+| Campo enlace | `{{ producto.enlace }}` (ya tiene barras) | `"/{{ producto.enlace }}/"` |
+| Builder var name | `data-field-label` → minúsculas, sin espacios | Mantener casing original |
+| Checkbox | `1` o `0` (número) | `true` / `false` |
+| Formato fecha | `YYYY-MM-DD HH:mm:ss` | Cualquier otro |
+| `c-if` igualdad | `c-if="x = 'valor'"` (un `=`) | `c-if="x == 'valor'"` |
+| Twig `{% if %}` | `{% if x == 'valor' %}` (doble `==`) | `{% if x = 'valor' %}` |
+| Concatenación Twig | `'value=' ~ variable` | `'value=' + variable` |
+
+## Tipos de builder field (`data-field-type`)
+
+| Tipo | Elemento | Devuelve |
+|------|----------|----------|
+| `textfield` | `<p>` | String |
+| `headfield` | `<h1>`–`<h6>` | String + variable `_tag` |
+| `textbox` | `<div>` | String multilínea |
+| `wysiwyg` | `<div class="wysiwyg">` | HTML string |
+| `link` | `<a>` | URL string |
+| `upload` | `<img>` | Array `[{urlPath, info1, info2, info3, info4}]` |
+| `uploadMulti` | `<li>` | Itera archivos subidos |
+| `list` (fijo) | `<div data-list-options="...">` | Valor seleccionado |
+| `list` (tabla) | `<div data-list-table="...">` | `num` del registro |
+| `multiv2` | `<li>` wrapper | Array de objetos |
+| `checkbox` | `<input>` o `<div>` | `1` / `0` |
+| `colorpicker` | `<div>` | Hex color |
+
+## Atributos Acai
+
+| Atributo | Uso | Ejemplo |
+|----------|-----|---------|
+| `c-if` | Condicional | `<p c-if="activo = 1">` |
+| `c-else` | Rama else | `<p c-else>` |
+| `c-for` | Loop array | `<li c-for="item in items">` |
+| `c-for` (tabla) | Loop BD | `<li c-for="p in productos" c-where="'activo=1'" c-limit="10">` |
+| `c-hidden` | Variable oculta | `<div c-hidden="true">` |
+| `c-class` | Clase condicional | `<div c-class="{ 'bg-red': color == '1' }">` |
+| `c-required` | Required condicional | `c-required="'2' not in camposquitar"` |
+| `c-form` | Formulario | `<c-form tableName="'contacto'" captcha="true">` |
+
+## Filtros Twig
+
+| Filtro | Uso |
+|--------|-----|
+| `get` | `'tabla' \| get(where, order, limit)` |
+| `queryDB` | `'SELECT ... FROM cms_tabla' \| queryDB()` |
+| `hook` | `'hooks/module_id/' \| hook({params})` |
+| `module` | `'module_id' \| module({params})` |
+| `imagec` | `path \| imagec(width)` |
+| `translate` | `'texto' \| translate` (tabla `textos_generales`) |
+| `raw` | `variable \| raw` |
+| `truncate` | `text \| truncate(100)` |
+| `json_decode` | `'json_string' \| json_decode` |
+| `default` | `variable \| default('fallback')` |
+| `length`, `upper`, `lower`, `trim`, `replace`, `split`, `filter` | Estándar Twig |
+
+## Formato de datos para insert/update
+
+| Tipo | Formato | Ejemplo |
+|------|---------|---------|
+| `textfield` | String | `"Texto"` |
+| `textbox` | String multilínea | `"Línea 1\nLínea 2"` |
+| `date`/datetime | `YYYY-MM-DD HH:mm:ss` | `"2025-12-03 10:30:00"` |
+| `wysiwyg` | HTML string | `"<p>Texto</p>"` |
+| `list` | String o número | `"activo"` o `"1"` |
+| `checkbox` | Número 1/0 | `1` o `0` |
+| `multitext` | String JSON | `"[{\"item\":\"valor\"}]"` |
+| `upload` | NO enviar — usar `upload_record_image` después |
+
+## Variables globales
+
+| Variable | Descripción |
+|----------|-------------|
+| `section_id` | ID único por instancia del módulo |
+| `interno` | `true` dentro del editor CMS |
+| `server.HTTP_HOST` | Dominio actual (sin protocolo) |
+| `loop.index` | Índice 1-based en `c-for`/`{% for %}` |
+| `loop.index is odd` / `is even` | Layouts alternados |
+| `thisrecord` | Registro actual (solo en secciones generales) |
+
+## Decisión rápida — qué tool usar
+
+| Intención | Tool / workflow |
+|-----------|-----------------|
+| Crear módulo nuevo | `acai-write` `index-base.tpl` → `add_module_to_record` → `set_module_config_vars` |
+| Editar template de módulo | `acai-view` → `acai-line-replace` |
+| Ver datos de un módulo en una página | `get_module_config_vars` |
+| Cambiar valores de un módulo | `set_module_config_vars` |
+| Subir imagen a un módulo | Usa `uploadFields` de `set_module_config_vars` → `upload_record_image` (`tableName: "builder_custom"`) |
+| Crear tabla nueva | `create_table` (pregunta `enlace`/`seoMetas` antes) → `create_field` |
+| Crear detalle de registro | Sección general en `template/estandar/modulos/custom-{tableName}/` |
+| Editar header / footer | `get_layout_field` → `set_layout_field` (NUNCA edites los `.tpl` directamente) |
+| Añadir librería global | `list_global_libraries` → `add_global_library` (`top` o `bottom`) |
+| Hook que se ejecuta antes de cada página | `acai-write` el `.php` → `set_hook_middleware({ middleWare: ["allurls"] })` |
+| Generar imagen IA | `generate_image` → `upload_record_image` con `uploadUrl`/`fullUrl` |
+| Buscar archivos | `acai-glob` |
+| Buscar texto en archivos | `acai-grep` |
+| URL del proyecto | `get_web_url` (añade `?pruebas=1`) |
+| Navegar el preview del usuario | `navigate_browser` |
+| Token JWT expirado (403) | `refresh_acai_token` |
+| Necesito un doc no cargado | `read_doc({ name: "..." })` |
+| Listado de docs | `list_docs()` |
+
+## Errores comunes a evitar
+
+- Editar `index.tpl`, `index-twig.tpl` o `builder.json` (autogenerados).
+- Editar `layout.json` o `custom-header-twig/*` directamente (usa `set_layout_field`).
+- Usar el `sectionId` como `recordId` para subir imágenes (es el `num` de `builder_custom`).
+- Usar el nombre de la variable como `fieldName` (es el campo de relations: `image1`, no `imagenes`).
+- Crear página por registro en `apartados` para detalles (usa `custom-{tableName}/`).
+- Cambiar `enlace` o `controlador` de un registro existente.
+- Usar `localhost:8080` o dominios de producción (siempre `get_web_url` + `?pruebas=1`).
+- Crear archivos JSON de i18n (usa `| translate` + tabla `textos_generales`).
+- Usar Twig dentro de `script.js` o `style.css` (estáticos — pasa valores via `data-*`).
+- Llamar `mkdir` (usa `acai-write` directamente — crea el directorio padre).