Initial commit

docs/modular-system.md

@@ -0,0 +1,105 @@
+# Acai Modular System
+
+## Modules
+
+Modules are the visual building blocks of Acai websites. Each module lives in `template/estandar/modulos/<module-id>/`.
+
+### File Structure
+
+```
+<module-id>/
+├── 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
+<section class="hero-section" id="{{ section_id }}">
+  <div class="container mx-auto px-4">
+    <h2 data-field-type="headfield" class="text-3xl font-bold">
+      Title here
+    </h2>
+    <p data-field-type="textbox" class="text-lg text-gray-600">
+      Description text
+    </p>
+    <img data-field-type="upload" src="placeholder.jpg" class="w-full rounded-lg" />
+    <a data-field-type="link" href="#" class="btn">Call to action</a>
+  </div>
+</section>
+```
+
+### Including Modules from Other Modules
+
+```html
+<module_id :param1="value1" :param2="'string value'"></module_id>
+```
+
+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
+<article class="product-card">
+  <img src="{{ thisrecord.imagen[0].urlPath }}"
+       alt="{{ thisrecord.imagen[0].info1 }}"
+       class="w-full h-64 object-cover" />
+  <h3 class="text-xl font-semibold">{{ thisrecord.nombre }}</h3>
+  <p class="text-gray-600">{{ thisrecord.descripcion | raw }}</p>
+  <span class="text-2xl font-bold">{{ thisrecord.precio }}€</span>
+</article>
+```
+
+### Variable Assignment
+
+Use `<set>` tag to create variables from queries:
+
+```html
+<set :categories="'categorias' | get()"></set>
+<set :featured="'productos' | get({destacado: 1}, 'orden ASC', 3)"></set>
+```
+
+
+## Repeatable Content (multiv2)
+
+The `multiv2` builder field type creates repeatable groups of fields:
+
+```html
+<div c-for="item in record.items">
+  <h3 data-field-type="textfield">{{ item.title }}</h3>
+  <p data-field-type="textbox">{{ item.description }}</p>
+  <img data-field-type="upload" src="{{ item.image }}" />
+</div>
+```
+
+Access individual items: `record.items[0].title`, `record.items[1].image`, etc.