# Hooks & Server-Side API

## 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/<module-id>/hook.php`.

### How to Call Hooks

**From Twig:**
```twig
{{ 'hooks/module_id/' | hook({param1: 'value1', param2: variable}) }}
```

**From HTML (with result):**
```html
<hook result="myVar" endpoint="/hooks/module_id/" :param1="value1" :param2="'string'"></hook>
<p>{{ myVar }}</p>
```

**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:

```php
<?php
// Called with: 'hooks/my_hook/' | hook({category: 'electronics', limit: 10})
// Available as:
$category; // 'electronics'
$limit;    // 10
```

### Hook Return Values

Hooks can `echo` or `return` values. When called from Twig or `<hook>` tag, the output is captured into the result variable.


## CmsApi (PHP)

Server-side API for database operations. Available in all hooks.

### Read Records

```php
// Get all records
$products = CmsApi::get('productos');

// With WHERE condition
$active = CmsApi::get('productos', ['active' => 1]);

// With order and limit
$latest = CmsApi::get('noticias', [], 'fecha DESC', 5);

// With operators
$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',
]);
```

### Update Records

```php
CmsApi::update('productos',
    ['precio' => 29.99, 'activo' => 1],  // fields to update
    ['num' => 42]                          // where condition
);
```

### Delete Records

```php
CmsApi::delete('productos', ['num' => 42]);
```

### Important Rules

- Table names **without** `cms_` prefix
- Primary key is always `num`, never `id`
- Upload fields are handled separately (not via insert/update)
- Operators: `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN`


## CmsApi (JavaScript — Client-Side)

```js
// Hook call
CmsApi.hook('/hooks/module_id/', { param: 'value' }, function(response) {
  // response is the hook output
});

// Record operations (if exposed via hooks)
CmsApi.get('tableName', { where: conditions }, function(records) {
  // records array
});
```


## CocoDB

Low-level database abstraction layer. Use when CmsApi is too high-level.

<!-- TODO: Document CocoDB methods (query, insert, update, delete, transactions) -->


## 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

### 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 |