de codex

docs/css-js-conventions.md

@@ -72,6 +72,10 @@ Patrón para colores configurables por el usuario:
 
 JavaScript scopeado al módulo usando `section_id`:
 
+This is the default and expected place for module JavaScript.
+Do NOT embed `<script>` tags directly inside `index-base.tpl` for normal module behavior.
+Keep `index-base.tpl` for HTML/Twig markup and put interactive logic in `script.js`.
+
 ```js
 const section = document.getElementById('{{ section_id }}');
 if (section) {
@@ -88,6 +92,15 @@ CmsApi.hook('/hooks/module_id/', { action: 'getData', id: 123 }, function(respon
 });
 ```
 
+If you are calling a hook that belongs to the current module, the endpoint must use the real module id:
+
+```js
+// Module folder: template/estandar/modulos/buscadorapartados_hjd8s/
+CmsApi.hook('/hooks/buscadorapartados_hjd8s/', { termino: 'vela' }, function(response) {
+  console.log(response);
+});
+```
+
 ### Cuándo usar Vue 3
 
 Usar Vue 3 CDN cuando la lógica requiera:

docs/hooks-and-api.md

@@ -26,6 +26,16 @@ 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
@@ -79,6 +89,14 @@ CmsApi.hook('/hooks/mimodulo/', {param1: 100, param2: 'texto'}, (data) => {
 });
 ```
 
+**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
 <?php
@@ -213,6 +231,11 @@ CmsApi.get('tableName', { where: conditions }, function(records) {
 
 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)`
 
 ```php

docs/module-creation-guide.md

@@ -37,14 +37,24 @@ Each module lives in `template/estandar/modulos/<moduleId>/` with:
 
 ## Creating a Module — Full Workflow
 
-If the module needs server-side logic, dynamic data processing, form handling, or reusable backend behavior, read `docs/hooks-and-api.md` before creating `hook.php` or any global hook.
+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.
 
+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 `<script>` tags in `index-base.tpl`
+- Do NOT put PHP logic in `index-base.tpl`
+
 1. **Read style reference** (steps above)
 2. **`acai-write`** — Create the module files directly (`index-base.tpl`, `style.css`, `script.js`, optional `hook.php`) using project-relative paths and complete file contents.
    - If the server-side logic belongs only to that module, create `template/estandar/modulos/<module-id>/hook.php`
    - If the logic should be reused across modules/pages, create a global hook in `hooks/hooks.<hook-id>.php`
    - Inside the module, reference its own hook with `/hooks/<module-id>/`
+   - Example: module folder `template/estandar/modulos/buscadorapartados_hjd8s/` -> hook endpoint `/hooks/buscadorapartados_hjd8s/`
 3. **Automatic compile** — Writing `index-base.tpl` automatically creates the generated template placeholders and triggers compilation. `compile_module` is only a manual recovery tool if you need to force a recompile without changing the file.
 4. **`add_module_to_record`** — Adds the module to a page. Response includes `sectionId` — use it directly in the next step.
 5. **`set_module_config_vars`** — Fill variables with content. Response includes `uploadFields` with `{ fieldName, recordNum }` for each upload variable.