agenticSystem/docs/11-quick-reference.md

Quick Reference — Cheat sheet

Este documento es un resumen ejecutable de las reglas críticas, los tipos de campo, los filtros Twig, los formatos de datos para insert/update y las variables globales. Es la fuente única de verdad para resolver dudas rápidas sin tener que abrir los docs largos. Léelo antes de cualquier operación cuando quieras refrescar las reglas; el resto de docs (01–10) profundizan en cada tema.

Reglas inmutables

Regla	Correcto	Incorrecto
Nombres de tabla en tools/Twig/CmsApi	'productos'	'cms_productos'
Nombres en queryDB	cms_productos	productos
Primary key	record.num	record.id
Foreign keys	categoria_num	categoria_id
Upload fields	record.imagen[0].urlPath	record.imagen
Optimizar imagen	imagen[0].urlPath | imagec(800)	imagen.url
Filtros Twig	{{ 'tabla' | get() }}	{{ get('tabla') }}
Campo enlace	{{ producto.enlace }} (ya tiene barras)	"/{{ producto.enlace }}/"
Builder var name	data-field-label → minúsculas, sin espacios	Mantener casing original
Checkbox	1 o 0 (número)	true / false
Formato fecha	YYYY-MM-DD HH:mm:ss	Cualquier otro
c-if igualdad	c-if="x = 'valor'" (un =)	c-if="x == 'valor'"
Twig {% if %}	{% if x == 'valor' %} (doble ==)	{% if x = 'valor' %}
Concatenación Twig	'value=' ~ variable	'value=' + variable

Tipos de builder field (data-field-type)

Tipo	Elemento	Devuelve
textfield	<p>	String
headfield	<h1>–<h6>	String + variable _tag
textbox	<div>	String multilínea
wysiwyg	<div class="wysiwyg">	HTML string
link	<a>	URL string
upload	<img>	Array [{urlPath, info1, info2, info3, info4}]
uploadMulti	<li>	Itera archivos subidos
list (fijo)	<div data-list-options="...">	Valor seleccionado
list (tabla)	<div data-list-table="...">	num del registro
multiv2	<li> wrapper	Array de objetos
checkbox	<input> o <div>	1 / 0
colorpicker	<div>	Hex color

Atributos Acai

Atributo	Uso	Ejemplo
c-if	Condicional	<p c-if="activo = 1">
c-else	Rama else	<p c-else>
c-for	Loop array	<li c-for="item in items">
c-for (tabla)	Loop BD	<li c-for="p in productos" c-where="'activo=1'" c-limit="10">
c-hidden	Variable oculta	<div c-hidden="true">
c-class	Clase condicional	<div c-class="{ 'bg-red': color == '1' }">
c-required	Required condicional	c-required="'2' not in camposquitar"
c-form	Formulario	<c-form tableName="'contacto'" captcha="true">

Filtros Twig

Filtro	Uso
get	'tabla' | get(where, order, limit)
queryDB	'SELECT ... FROM cms_tabla' | queryDB()
hook	'hooks/module_id/' | hook({params})
module	'module_id' | module({params})
imagec	path | imagec(width)
translate	'texto' | translate (tabla textos_generales)
raw	variable | raw
truncate	text | truncate(100)
json_decode	'json_string' | json_decode
default	variable | default('fallback')
length, upper, lower, trim, replace, split, filter	Estándar Twig

Formato de datos para insert/update

Tipo	Formato	Ejemplo
textfield	String	"Texto"
textbox	String multilínea	"Línea 1\nLínea 2"
date/datetime	YYYY-MM-DD HH:mm:ss	"2025-12-03 10:30:00"
wysiwyg	HTML string	"<p>Texto</p>"
list	String o número	"activo" o "1"
checkbox	Número 1/0	1 o 0
multitext	String JSON	"[{\"item\":\"valor\"}]"
upload	NO enviar — usar upload_record_image después

Variables globales

Variable	Descripción
section_id	ID único por instancia del módulo
interno	true dentro del editor CMS
server.HTTP_HOST	Dominio actual (sin protocolo)
loop.index	Índice 1-based en c-for/{% for %}
loop.index is odd / is even	Layouts alternados
thisrecord	Registro actual (solo en secciones generales)

Decisión rápida — qué tool usar

Intención	Tool / workflow
Crear módulo nuevo	acai-write index-base.tpl → add_module_to_record → set_module_config_vars
Editar template de módulo	acai-view → acai-line-replace
Ver datos de un módulo en una página	get_module_config_vars
Cambiar valores de un módulo	set_module_config_vars
Subir imagen a un módulo	Usa uploadFields de set_module_config_vars → upload_record_image (tableName: "builder_custom")
Crear tabla nueva	create_table (pregunta enlace/seoMetas antes) → create_field
Crear detalle de registro	Sección general en template/estandar/modulos/custom-{tableName}/
Editar header / footer	get_layout_field → set_layout_field (NUNCA edites los .tpl directamente)
Añadir librería global	list_global_libraries → add_global_library (top o bottom)
Hook que se ejecuta antes de cada página	acai-write el .php → set_hook_middleware({ middleWare: ["allurls"] })
Generar imagen IA	generate_image → upload_record_image con uploadUrl/fullUrl
Buscar archivos	acai-glob
Buscar texto en archivos	acai-grep
URL del proyecto	get_web_url (añade ?pruebas=1)
Navegar el preview del usuario	navigate_browser
Token JWT expirado (403)	refresh_acai_token
Necesito un doc no cargado	read_doc({ name: "..." })
Listado de docs	list_docs()

Errores comunes a evitar

• Editar index.tpl, index-twig.tpl o builder.json (autogenerados).
• Editar layout.json o custom-header-twig/* directamente (usa set_layout_field).
• Usar el sectionId como recordId para subir imágenes (es el num de builder_custom).
• Usar el nombre de la variable como fieldName (es el campo de relations: image1, no imagenes).
• Crear página por registro en apartados para detalles (usa custom-{tableName}/).
• Cambiar enlace o controlador de un registro existente.
• Usar localhost:8080 o dominios de producción (siempre get_web_url + ?pruebas=1).
• Crear archivos JSON de i18n (usa | translate + tabla textos_generales).
• Usar Twig dentro de script.js o style.css (estáticos — pasa valores via data-*).
• Llamar mkdir (usa acai-write directamente — crea el directorio padre).