diff --git a/CLAUDE.md b/CLAUDE.md index b741045..0bc5830 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,6 +73,18 @@ PHP files that execute server-side logic. Triggered by: - 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/` + +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/` + See [docs/hooks-and-api.md](docs/hooks-and-api.md) for usage. ## Database Access diff --git a/docs/hooks-and-api.md b/docs/hooks-and-api.md index 21eec92..b6577d3 100644 --- a/docs/hooks-and-api.md +++ b/docs/hooks-and-api.md @@ -2,7 +2,29 @@ ## Hooks -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`. +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 ### Estructura de un Hook @@ -34,6 +56,10 @@ 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 @@ -379,6 +405,9 @@ return [

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 diff --git a/docs/module-creation-guide.md b/docs/module-creation-guide.md index f97eb35..4e2640d 100644 --- a/docs/module-creation-guide.md +++ b/docs/module-creation-guide.md @@ -39,6 +39,9 @@ Each module lives in `template/estandar/modulos//` with: 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//hook.php` + - If the logic should be reused across modules/pages, create a global hook in `hooks/hooks..php` + - Inside the module, reference its own hook with `/hooks//` 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.