` | String + variable `_tag` con la etiqueta elegida |
+| `textbox` | `` | String multi-línea |
+| `wysiwyg` | `` | HTML string |
+| `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 |
-| Type | Description | Returns |
-|------|-------------|---------|
-| `textfield` | Single line text | String |
-| `headfield` | Heading text (generates `_tag` variable for semantic tag: h1-h6) | String |
-| `textbox` | Multi-line text | String |
-| `wysiwyg` | Rich text editor (HTML output) | HTML string |
-| `link` | URL field (already includes slashes) | String |
-| `upload` | Single image/file | Array: `[0].urlPath`, `[0].info1` (alt), `[0].info2-4` |
-| `uploadMulti` | Multiple images | Iterable: `item.urlPath` |
-| `list` | Dropdown (fixed options or from table) | String or foreign key num |
-| `multiv2` | Repeatable group of fields | Array of objects |
-
-### headfield Example
+### textfield
```html
-<{{ title_tag | default('h2') }} data-field-type="headfield" class="text-3xl font-bold">
- Section Title
+
+ Elemento editable
+
+```
+
+### headfield
+
+Genera 2 variables: la estándar y otra con sufijo `_tag` con la etiqueta elegida por el usuario.
+
+```html
+<{{ title_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
```
-### upload Example
+### textbox
```html
-
-![{{ image[0].info1 }}]({{ image[0].urlPath }})
-
-
-
- 
+
+ Texto largo editable
```
-### list Example
+### wysiwyg
```html
-
-
-
-
-
+
+ Texto con estilos editables
+
```
+### link
+
+```html
+
+ Haz clic aquí
+
+```
+
+### upload
+
+```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 (usado como alt)
+
+Acceso en Twig: `{{ imagen[0].urlPath }}`, `{{ imagen[0].info1 }}`
+
+### uploadMulti
+
+Itera sobre todas las imágenes subidas:
+
+```html
+
+
+ ![{{ uploadMulti.info1 }}]()
+
+
+```
+
+### list (opciones fijas)
+
+```html
+
+
+```
+
+Formato de opciones: `opcion1,opcion2,|opcion3,valor3|opcion4`
+
+### list (tabla)
+
+```html
+
+ {{ record.titulo }}
+
+```
+
+- `data-list-table`: Nombre de tabla sin prefijo `cms_`
+- `data-list-value`: Campo a usar como valor (generalmente `num`)
+- `data-list-label`: Campo a mostrar como label
+
+### multiv2 — Campos repetibles
+
+```html
+
+ -
+
+ Nombre del producto
+
+
+ Descripción del producto
+
+
+
![]()
+
+
+
+```
+
+Uso en Twig — las variables son propiedades del objeto iterado:
+
+```twig
+{% for record in productos %}
+
+ {{ record.nombre }}
+ {{ record.descripcion }}
+ 
+
+{% endfor %}
+```
+
+---
## Acai Attributes
-### `c-if` — Conditional Rendering
+### `c-if` — Renderizado condicional
```html
-
-Banner content
-
-
-Grid layout
-
-
+
{{ subtitle }}
+
+
+Grid layout
```
### `c-else`
-Must immediately follow the `c-if` element:
+Debe ir inmediatamente después del elemento `c-if`:
```html
@@ -82,91 +201,173 @@ Must immediately follow the `c-if` element:
```
-### `c-for` — Iteration
+### `c-for` — Iteración sobre array
```html
-
{{ item.title }}
-
-
-
- {{ product.nombre }}
-
```
-Available inside loop: `loop.index` (1-based), `loop.index is odd`, `loop.index is even`
-
-### `c-class` — Dynamic CSS Classes
+### `c-for` — Iteración sobre tabla de BD
```html
-
- Content
-
+
+ -
+ {{ producto.title }}
+
+
```
-### `c-hidden` — Hidden Elements
+Parámetros opcionales: `c-where` (condición SQL), `c-order` (orden), `c-limit` (límite).
-Element is not rendered but can declare builder variables:
+Equivalente en Twig:
+```twig
+{% for producto in 'productos' | get('visible=1','num desc',10) %}
+ {{ producto.title }}
+{% endfor %}
+```
+
+Dentro del loop: `loop.index` (1-based), `loop.index is odd`, `loop.index is even`
+
+### `c-class` — Clases CSS condicionales
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### `c-hidden` — Elementos ocultos
+
+Elemento que no se renderiza pero puede declarar variables builder:
```html
-
+
```
-### `c-required` — Conditional Required Fields
+### `c-required` — Campos requeridos condicionales
```html
-
+
```
+---
-## Forms (`c-form`)
-
-Complete form handling with automatic validation, storage, and email sending.
+## Definiendo variables con ``
```html
-
+
```
-### c-form Attributes
+### Atributos de c-form
-| Attribute | Description |
-|-----------|-------------|
-| `tableName="'table'"` | Store submissions in database table |
-| `mailRecord="['correos', 'ID']"` | Email template from `correos` table |
-| `sendTo="'email@domain.com'"` | Recipient email(s), comma-separated |
-| `sendToClient="'fieldname'"` | Field containing client's email for auto-reply |
-| `captcha="true"` | Enable Google reCAPTCHA |
-| `honeypot="true"` | Anti-spam hidden field |
-| `messageOK="'text'"` | Success message |
-| `messageKO="'text'"` | Error message |
-| `redirect="'/path/'"` | Redirect after successful submit |
-| `attachFiles="true"` | Attach uploaded files to email |
-| `showImages="true"` | Show image thumbnails in email |
+| Atributo | Descripción |
+|----------|-------------|
+| `tableName="'table'"` | Tabla donde almacenar registros |
+| `mailRecord="['correos', 'ID']"` | Template de email de la tabla `correos` |
+| `sendTo="'email@domain.com'"` | Destinatarios (separados por coma) |
+| `sendToClient="'campo_email'"` | Campo con email del cliente para auto-reply |
+| `captcha="true"` | Google reCAPTCHA |
+| `honeypot="true"` | Campo oculto anti-spam |
+| `messageOK="'texto'"` | Mensaje de éxito |
+| `messageKO="'texto'"` | Mensaje de error |
+| `redirect="'/path/'"` | Redirección tras envío exitoso |
+| `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 para el email |
+---
-## Built-in Components
+## Componentes Built-in
### Carousel (`c-tns-wrapper`)
@@ -208,6 +409,18 @@ Complete form handling with automatic validation, storage, and email sending.
```html
![]()
-
+
```
+
+---
+
+## Puntos importantes
+
+1. **Nombres de variables:** `data-field-label` → sin espacios ni caracteres especiales, minúsculas
+2. **Variables en multiv2:** Son propiedades del objeto iterado (`record.nombre`)
+3. **Campos upload:** Retornan arrays, no strings (`imagen[0].urlPath`, no `imagen`)
+4. **c-if usa `=` no `==`:** `c-if="layout = 'grid'"` (un solo igual)
+5. **c-for tabla:** El nombre de tabla va sin prefijo `cms_`
+6. **Enlace:** Ya incluye barras, no añadir extras
+7. **Checkbox:** Valores `1` o `0`, no `true`/`false`
diff --git a/docs/css-js-conventions.md b/docs/css-js-conventions.md
index f117c8a..8460082 100644
--- a/docs/css-js-conventions.md
+++ b/docs/css-js-conventions.md
@@ -1,63 +1,78 @@
# CSS & JavaScript Conventions
+## Estructura del módulo
+
+- Genera HTML + CSS + JS (o Vue 3 si es necesario)
+- Define una clase raíz en kebab-case: `product-card`, `hero-section`, etc.
+- Todo el CSS y JS scopeado bajo esa clase raíz
+
+---
+
## CSS
### Tailwind First
-Use Tailwind CSS as the primary styling method. Only use custom CSS when Tailwind is insufficient.
+Usar TailwindCSS como método principal. Solo CSS custom cuando Tailwind no cubra el estilo o se necesiten estados complejos/transiciones específicas.
```html
-
Title
-
-
```
-### BEM for Custom CSS
+### BEM para CSS Custom
-When custom CSS is needed, scope everything under a root class using BEM naming:
+Cuando se necesite CSS personalizado, siempre scopeado bajo la clase raíz con BEM:
```css
-/* Root class in kebab-case */
.hero-section { }
.hero-section__title { }
.hero-section__image { }
.hero-section--dark { }
```
-Never use global classes without a module prefix.
+Nunca usar clases globales sin prefijo de módulo.
-### CSS Variables
-
-Acai provides theme variables:
+### CSS Variables del tema
```css
-var(--main-color) /* Primary brand color */
-var(--main-color-light) /* Lighter variant */
-var(--main-color-dark) /* Darker variant */
+var(--main-color) /* Color de marca primario */
+var(--main-color-light) /* Variante clara */
+var(--main-color-dark) /* Variante oscura */
```
-### Utility Classes (Built-in)
+### Estilos inline con fallbacks
-| Class | Description |
+Patrón para colores configurables por el usuario:
+
+```html
+
+
+```
+
+### Clases utilitarias de Acai
+
+| Clase | Descripción |
|-------|-------------|
-| `transition3s` | 0.3s smooth transition |
-| `click-a-child` | Makes parent clickable via child `` tag |
-| `line-clamp2` / `line-clamp3` / `line-clamp5` | Text truncation with ellipsis |
-| `filter-white` | CSS filter to make images/icons white |
-| `lazyload` | Lazy loading (use with `data-src`) |
+| `transition3s` | Transición suave 0.3s |
+| `click-a-child` | Hace el padre clickeable via primer `` hijo |
+| `line-clamp2` / `line-clamp3` / `line-clamp5` | Truncar texto a N líneas |
+| `filter-white` | Filtro CSS para hacer imágenes/iconos blancos |
+| `lazyload` | Lazy loading (usar con `data-src`) |
+| `text-shadow` | Sombra de texto para legibilidad sobre imágenes |
+| `wysiwyg` | Wrapper para contenido de texto enriquecido |
+| `bg-main-color` / `bg-main-color-light` / `bg-main-color-dark` | Fondos con color primario |
+| `text-main-color` / `text-main-color-light` / `text-main-color-dark` | Texto con color primario |
+---
## JavaScript
### Module Scripts (`script.js`)
-Keep JavaScript scoped to the module. Use `section_id` for targeting:
+JavaScript scopeado al módulo usando `section_id`:
```js
-// Scope to this module instance
const section = document.getElementById('{{ section_id }}');
if (section) {
const buttons = section.querySelectorAll('.btn');
@@ -68,15 +83,23 @@ if (section) {
### CmsApi (Client-Side)
```js
-// Call a hook
CmsApi.hook('/hooks/module_id/', { action: 'getData', id: 123 }, function(response) {
console.log(response);
});
```
-### Vue 3 Integration
+### Cuándo usar Vue 3
-For complex interactivity, use Vue 3 via CDN with Composition API:
+Usar Vue 3 CDN cuando la lógica requiera:
+- Doble binding / reactividad
+- Solicitudes asíncronas complejas
+- Componentes reutilizables
+- Gestión de estado local
+- Ciclos de vida
+
+Para lógica simple, usar JavaScript vanilla.
+
+### Vue 3 Integration
```html
@@ -87,7 +110,7 @@ For complex interactivity, use Vue 3 via CDN with Composition API:
```
-**Important:** Use `'${'` and `'}'` as Vue delimiters to avoid conflicts with Twig's `{{ }}` syntax.
+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
+![]()
+
+
+![]()
+```
+
+---
+
+## 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
index 8e2b32c..21eec92 100644
--- a/docs/hooks-and-api.md
+++ b/docs/hooks-and-api.md
@@ -2,155 +2,210 @@
## Hooks
-Hooks are PHP files in the `hooks/` directory that execute server-side logic. They can also live inside a module at `template/estandar/modulos//hook.php`.
+Hooks son archivos PHP en `hooks/` que ejecutan lógica server-side. También pueden estar dentro de un módulo en `template/estandar/modulos//hook.php`.
-### Testing Hooks
-
-To test hooks, the site's Docker container must be running. Make a curl request to the Docker URL with the hook path. For example, if a hook is named `hooks.example_hook.php`:
-
-```bash
-curl http://{DOCKER_URL_AND_PORT}/hooks/example_hook/
-```
-
-Replace `{DOCKER_URL_AND_PORT}` with your local Docker address (e.g., `localhost:8080`) and parse hook name for url endpoint.
-
-Do not use X-Hooks-Token because its not needed on developer environment.
-
-### How to Call Hooks
-
-**From Twig:**
-```twig
-{{ 'hooks/module_id/' | hook({param1: 'value1', param2: variable}) }}
-```
-
-**From HTML (with result):**
-```html
-{{ myVar }}
-```
-
-**From JavaScript:**
-```js
-CmsApi.hook('/hooks/module_id/', { param1: 'value1' }, function(response) {
- console.log(response);
-});
-```
-
-**From c-form:**
-Hooks are automatically triggered on form submission when configured.
-
-### Hook Parameters
-
-Parameters are received as PHP variables:
+### Estructura de un Hook
```php
true,
+ "message" => "Valor procesado: " . $resultado,
+ "value" => $resultado
+];
+?>
```
-### Hook Return Values
+### Testing Hooks
-Hooks can `echo` or `return` values. When called from Twig or `` tag, the output is captured into the result variable.
+El Docker debe estar corriendo. Hacer curl al endpoint del hook:
+```bash
+curl http://localhost:8080/hooks/example_hook/
+```
+
+No usar X-Hooks-Token en desarrollo local.
+
+### Cómo Llamar Hooks
+
+**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);
+});
+```
+
+**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)
-Server-side API for database operations. Available in all hooks.
+API server-side para operaciones de base de datos. Disponible en todos los hooks.
-### Read Records
+### Read — `CmsApi::get()`
```php
-// Get all records
+// Todos los registros
$products = CmsApi::get('productos');
-// With WHERE condition
+// Con condición WHERE
$active = CmsApi::get('productos', ['active' => 1]);
-// With order and limit
+// Con orden y límite
$latest = CmsApi::get('noticias', [], 'fecha DESC', 5);
-// With operators
+// Con condición string
+$activos = CmsApi::get('productos', 'activo=1');
+
+// Condición compleja como array
+$caros = CmsApi::get('productos', [
+ ["column" => "precio", "operator" => ">", "value" => 100]
+]);
+
+// Múltiples condiciones (AND)
+$resultados = CmsApi::get('productos', [
+ ["column" => "activo", "operator" => "=", "value" => 1],
+ ["column" => "stock", "operator" => ">", "value" => 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]]]);
-```
-### Insert Records
-
-```php
-$newRecord = CmsApi::insert('contacto', [
- 'nombre' => 'John',
- 'email' => 'john@example.com',
- 'mensaje' => 'Hello',
+// Con opciones
+$datos = CmsApi::get('productos', '', '', '', [
+ 'translates' => true,
+ 'uploads' => true,
+ 'relations' => true,
+ 'relationsDepth' => 2
]);
```
-### Update Records
+### Insert — `CmsApi::insert()`
```php
-CmsApi::update('productos',
- ['precio' => 29.99, 'activo' => 1], // fields to update
- ['num' => 42] // where condition
+// 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]
);
```
-### Delete Records
+### Update — `CmsApi::update()`
```php
-CmsApi::delete('productos', ['num' => 42]);
+// 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");
```
-### Important Rules
+### Delete — `CmsApi::delete()`
-- Table names **without** `cms_` prefix
-- Primary key is always `num`, never `id`
-- Upload fields are handled separately (not via insert/update)
-- Operators: `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN`
+```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
-// Hook call
+// Llamar hook
CmsApi.hook('/hooks/module_id/', { param: 'value' }, function(response) {
- // response is the hook output
+ // response es la salida del hook
});
-// Record operations (if exposed via hooks)
+// Leer registros (si está expuesto via hooks)
CmsApi.get('tableName', { where: conditions }, function(records) {
// records array
});
```
+---
## CocoDB
-Low-level database abstraction layer used internally by CmsApi. Use directly from hooks when you need more control.
+Capa de abstracción de BD de bajo nivel usada internamente por CmsApi. Usar directamente desde hooks cuando necesites más control.
### `CocoDB::get($table, $where, $order, $limit, $options)`
-Reads records from a table. This is the same method CmsApi::get wraps.
-
```php
-// Basic query
+// Básico
$records = CocoDB::get('productos', ['activo' => 1], 'orden ASC', 10);
-// With advanced where (array syntax for operators)
+// Where con operadores avanzados
$records = CocoDB::get('productos', [
['column' => 'precio', 'value' => 100, 'operator' => '>='],
['column' => 'categoria_num', 'value' => [1, 2, 3], 'operator' => 'IN'],
]);
-// OR conditions
+// Condiciones OR
$records = CocoDB::get('productos', [
['column' => 'nombre', 'value' => '%keyword%', 'operator' => 'LIKE'],
['column' => 'descripcion', 'value' => '%keyword%', 'operator' => 'LIKE', 'or' => true],
]);
-// NOT condition
+// NOT
$records = CocoDB::get('productos', [
['column' => 'estado', 'value' => 'borrador', 'operator' => '=', 'not' => true],
]);
@@ -160,63 +215,59 @@ $records = CocoDB::get('productos', [
['column' => 'fecha_baja', 'value' => '', 'operator' => 'IS NULL'],
]);
-// Limit with offset
+// Limit con offset
$records = CocoDB::get('productos', [], 'num DESC', ['limit' => 10, 'offset' => 20]);
```
-#### Options for `get()`
+#### Opciones de `get()`
| Option | Type | Default | Description |
|--------|------|---------|-------------|
-| `uploads` | bool | `true` | Include upload field data |
-| `relations` | bool/array | `true` | Resolve foreign key relations. Pass array to limit: `['category']` |
-| `relationsDepth` | int | 2 | Depth of nested relation resolution |
-| `translates` | string | current lang | Language code for translations |
+| `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 | `[]` | Aggregate functions |
-| `onlyFields` | array | null | Select specific fields only |
-| `debug` | bool | false | Output SQL query for debugging |
-| `redis` | bool | null | Force Redis cache |
-| `redis_expire` | int | 60 | Redis cache TTL in seconds |
+| `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) |
### `CocoDB::insertRecords($table, $records, $functions, $options)`
-Insert one or multiple records.
-
```php
-// Single record
+// Un registro
$count = CocoDB::insertRecords('contacto', [
'nombre' => 'John',
'email' => 'john@example.com',
]);
-// Returns number of inserted records. Use mysql_insert_id() to get the new num.
+// Usar mysql_insert_id() para obtener el nuevo num
-// Multiple records
+// Múltiples
$count = CocoDB::insertRecords('productos', [
['nombre' => 'Product A', 'precio' => 10],
['nombre' => 'Product B', 'precio' => 20],
]);
```
-#### Options for insert/update
+#### Opciones de insert/update
| Option | Description |
|--------|-------------|
-| `forceNum` | Allow setting the `num` field manually |
-| `ignoreSchema` | Skip schema validation |
-| `ignoreFields` | Array of field names to skip |
+| `forceNum` | Permite setear el campo `num` manualmente |
+| `ignoreSchema` | Saltar validación de schema |
+| `ignoreFields` | Array de campos a ignorar |
### `CocoDB::updateRecords($table, $records, $where, $functions, $options)`
-Update records matching a where condition.
-
```php
CocoDB::updateRecords('productos',
- ['precio' => 29.99, 'activo' => 1], // fields to update
- ['num' => 42] // where condition
+ ['precio' => 29.99, 'activo' => 1],
+ ['num' => 42]
);
-// With operator in where
+// Con operador en where
CocoDB::updateRecords('productos',
['activo' => 0],
[['column' => 'stock', 'value' => 0, 'operator' => '<=']]
@@ -225,68 +276,140 @@ CocoDB::updateRecords('productos',
### `CocoDB::deleteRecords($table, $where, $options)`
-Delete records matching a where condition.
-
```php
CocoDB::deleteRecords('productos', ['num' => 42]);
-// With operator
CocoDB::deleteRecords('logs', [
['column' => 'fecha', 'value' => '2024-01-01', 'operator' => '<']
]);
```
-### Where Clause Syntax
+### Parámetro `$functions`
-The `$where` parameter supports two formats:
-
-**Simple (key-value):**
-```php
-['campo' => 'valor'] // campo = 'valor'
-```
-
-**Advanced (array of conditions):**
-```php
-[
- 'column' => 'field_name', // Required
- 'value' => 'match_value', // Required
- 'operator' => '=', // =, !=, <, >, <=, >=, LIKE, IN, IS NULL
- 'or' => false, // Use OR instead of AND
- 'not' => false, // Negate the condition
- 'raw_key' => false, // Skip column existence check
-]
-```
-
-### Functions Parameter
-
-The `$functions` parameter lets you apply MySQL functions to values during insert/update:
+Permite aplicar funciones MySQL a valores durante insert/update:
```php
CocoDB::insertRecords('logs', [
'mensaje' => 'Login exitoso',
'fecha' => '',
], [
- 'fecha' => 'NOW()', // Will use MySQL NOW() instead of the value
+ 'fecha' => 'NOW()',
]);
```
+### Where Clause — Formatos
+
+**Simple (key-value):**
+```php
+['campo' => 'valor'] // campo = 'valor'
+```
+
+**Avanzado (array de condiciones):**
+```php
+[
+ 'column' => 'field_name',
+ 'value' => 'match_value',
+ 'operator' => '=', // =, !=, <, >, <=, >=, LIKE, IN, IS NULL
+ 'or' => false, // OR en vez de AND
+ 'not' => false, // Negar la condición
+ 'raw_key' => false, // Saltar check de existencia de columna
+]
+```
+
+---
+
+## 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
-Table schemas are stored as JSON in `cms/data/schema/`. Each file defines:
-- Field names and types
-- Validation rules
-- Relationships (foreign keys)
-- Display configuration
+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
-### Field Format Types
+---
-| Type | PHP Format | Notes |
-|------|-----------|-------|
-| Text | String | Plain text |
-| Date/time | `YYYY-MM-DD HH:mm:ss` | MySQL datetime format |
-| Checkbox | `1` or `0` | Boolean as integer |
-| WYSIWYG | HTML string | Rich text with Tailwind classes |
-| List | String or num | Foreign key if linked to table |
-| Multivalores | JSON string | Serialized array |
-| Upload | — | Handled separately, never in insert/update |
+## 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 }}
+```
+
+### 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/production-patterns.md b/docs/production-patterns.md
new file mode 100644
index 0000000..1c294a6
--- /dev/null
+++ b/docs/production-patterns.md
@@ -0,0 +1,262 @@
+# Patrones de Producción
+
+Patrones reales usados en módulos y secciones generales de producción. Usar como referencia al crear nuevos módulos.
+
+---
+
+## Patrón 1: Cabecera de Sección (Pretítulo + Título + Subtítulo)
+
+Bloque de cabecera con colores y alineación configurables. Casi todos los módulos lo usan:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {% if titulo %}
+
+ {% endif %}
+
+
+
+
+
+
+
+
+```
+
+---
+
+## Patrón 2: Layout Zigzag/Ajedrez (Imagen + Texto alternado)
+
+Usa `loop.index is odd/even` para alternar:
+
+```html
+
+
+
+
+  }})
+
+
+
+ {{ record.titulobloque | raw }}
+ {{ record.textobloque | raw }}
+
+ {{ record.enlacebloque_anchor }}
+
+
+
+
+```
+
+---
+
+## Patrón 3: Acordeón FAQ
+
+```html
+
+
+
+ {{ loop.index }}.
+
+
+
+
+
+
+
+
+
+
+```
+
+JavaScript para toggle:
+```javascript
+document.addEventListener("DOMContentLoaded", function () {
+ document.querySelectorAll(".faq-page").forEach(faq => {
+ faq.addEventListener("click", function () {
+ const body = faq.nextElementSibling;
+ const isActive = faq.classList.toggle("active");
+ body.classList.toggle("hidden", !isActive);
+ AOS.refresh();
+ });
+ });
+});
+```
+
+---
+
+## Patrón 4: Formulario de Contacto Completo
+
+```html
+
' %}
+{% set gracias = 'apartados' | get('num = 20').0 %}
+
+
+
+
+
+
+
+
+
+
+
+```
+
+---
+
+## Patrón 5: Compartir en Redes Sociales
+
+```html
+
+ -
+
+ Facebook
+
+
+ -
+
+ WhatsApp
+
+
+
+```
+
+---
+
+## Patrón 6: Sección General — Detalle de Producto
+
+```html
+
+
+
+
+
+{% set productosRelacionados = 'productos' | get('categoria = ' ~ thisrecord.categoria ~ ' and num!=' ~ thisrecord.num, 'globalOrder ASC', '3') %}
+
+
+ {{ 'Productos relacionados' | translate }}
+
+ -
+
+
+
+
+```
+
+---
+
+## Patrón 7: Galería con Carousel (modo Gallery)
+
+```html
+
+
+ -
+
+
![{{ uploadMulti.info1 }}]()
+
+
+
+
+
+
+
+
+```
diff --git a/docs/quick-reference.md b/docs/quick-reference.md
new file mode 100644
index 0000000..137e0e7
--- /dev/null
+++ b/docs/quick-reference.md
@@ -0,0 +1,85 @@
+# Quick Reference
+
+## Reglas Críticas
+
+| Regla | Correcto | Incorrecto |
+|-------|----------|------------|
+| Nombres de tabla | `'productos'` | `'cms_productos'` |
+| Primary key | `record.num` | `record.id` |
+| Foreign keys | `categoria_num` | `categoria_id` |
+| Upload fields | `record.imagen[0].urlPath` | `record.imagen` |
+| Optimizar imagen | `record.imagen[0].urlPath \| imagec(800)` | `record.imagen.url` |
+| Filtros Twig | `{{ 'table' \| get() }}` | `{{ get('table') }}` |
+| Campo enlace | `{{ producto.enlace }}` (ya tiene barras) | `"/{{ producto.enlace }}/"` |
+| Nombres builder vars | `data-field-label` → sin espacios/especiales, minúsculas | Mantener casing original |
+| Checkbox | `1` o `0` (número) | `true`/`false` |
+| Formato fecha | `YYYY-MM-DD HH:mm:ss` | Cualquier otro formato |
+| c-if igualdad | `c-if="x = 'valor'"` (un `=`) | `c-if="x == 'valor'"` |
+| Twig if igualdad | `{% if x == 'valor' %}` (doble `==`) | `{% if x = 'valor' %}` |
+| queryDB tablas | `SELECT * FROM cms_tabla` (con prefijo) | `SELECT * FROM tabla` |
+| get tablas | `'tabla' \| get()` (sin prefijo) | `'cms_tabla' \| get()` |
+
+## Builder Variable Types
+
+| Type | Elemento | Retorna |
+|------|----------|---------|
+| `textfield` | `` | String |
+| `headfield` | `
`-`` | String + var `_tag` |
+| `textbox` | `
+ Elemento editable +
+``` + +### headfield + +Genera 2 variables: la estándar y otra con sufijo `_tag` con la etiqueta elegida por el usuario. + +```html +<{{ title_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 ``` -### upload Example +### textbox ```html - -Texto con estilos editables
+-
+
-
+ + Nombre del producto +++ Descripción del producto ++++
+
+
{{ record.nombre }}
+{{ record.descripcion }}
+{{ item.title }}
{{ product.nombre }}
--
+
- + {{ producto.title }} + +
Title
+```
+
+### Clases utilitarias de Acai
+
+| Clase | Descripción |
|-------|-------------|
-| `transition3s` | 0.3s smooth transition |
-| `click-a-child` | Makes parent clickable via child `` tag |
-| `line-clamp2` / `line-clamp3` / `line-clamp5` | Text truncation with ellipsis |
-| `filter-white` | CSS filter to make images/icons white |
-| `lazyload` | Lazy loading (use with `data-src`) |
+| `transition3s` | Transición suave 0.3s |
+| `click-a-child` | Hace el padre clickeable via primer `` hijo |
+| `line-clamp2` / `line-clamp3` / `line-clamp5` | Truncar texto a N líneas |
+| `filter-white` | Filtro CSS para hacer imágenes/iconos blancos |
+| `lazyload` | Lazy loading (usar con `data-src`) |
+| `text-shadow` | Sombra de texto para legibilidad sobre imágenes |
+| `wysiwyg` | Wrapper para contenido de texto enriquecido |
+| `bg-main-color` / `bg-main-color-light` / `bg-main-color-dark` | Fondos con color primario |
+| `text-main-color` / `text-main-color-light` / `text-main-color-dark` | Texto con color primario |
+---
## JavaScript
### Module Scripts (`script.js`)
-Keep JavaScript scoped to the module. Use `section_id` for targeting:
+JavaScript scopeado al módulo usando `section_id`:
```js
-// Scope to this module instance
const section = document.getElementById('{{ section_id }}');
if (section) {
const buttons = section.querySelectorAll('.btn');
@@ -68,15 +83,23 @@ if (section) {
### CmsApi (Client-Side)
```js
-// Call a hook
CmsApi.hook('/hooks/module_id/', { action: 'getData', id: 123 }, function(response) {
console.log(response);
});
```
-### Vue 3 Integration
+### Cuándo usar Vue 3
-For complex interactivity, use Vue 3 via CDN with Composition API:
+Usar Vue 3 CDN cuando la lógica requiera:
+- Doble binding / reactividad
+- Solicitudes asíncronas complejas
+- Componentes reutilizables
+- Gestión de estado local
+- Ciclos de vida
+
+Para lógica simple, usar JavaScript vanilla.
+
+### Vue 3 Integration
```html
{{ myVar }} {{ myVar.message }} {{ resultado.message }} Texto Total: ${{ precio.total }} ` | String |
+| `headfield` | `
+
+
+
+```
+
+### Breadcrumb
+
+```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
index 8e2b32c..21eec92 100644
--- a/docs/hooks-and-api.md
+++ b/docs/hooks-and-api.md
@@ -2,155 +2,210 @@
## Hooks
-Hooks are PHP files in the `hooks/` directory that execute server-side logic. They can also live inside a module at `template/estandar/modulos/
+
{{ record.titulobloque | raw }}
+ ' %}
+{% set gracias = 'apartados' | get('num = 20').0 %}
+
+
+
+```
+
+---
+
+## Patrón 6: Sección General — Detalle de Producto
+
+```html
+{{ 'Productos relacionados' | translate }}
+
+
+
+
+
+
`-`
` | String + var `_tag` |
+| `textbox` | `