Tipos de campo soportados en Ragnos

En Ragnos, los campos de un dataset se definen mediante el método addField(). Este método es parte fundamental de la configuración de un RDatasetController. Cada campo es una descripción declarativa de cómo un atributo del dominio:

• Se valida
• Se muestra en formularios
• Se muestra en grillas
• Se persiste (o no) en base de datos

Ragnos utiliza esta metadata para generar automáticamente formularios, validaciones, listados y comportamiento CRUD.

1. Estructura general de addField()

$this->addField('nombreCampo', [
    'label' => 'Etiqueta visible',
    'rules' => 'reglas|de|validacion',
    'type'  => 'tipo',
    'query' => 'expresion SQL'
]);

Parámetros comunes

2. Campo de texto (string)

$this->addField('customerName', [
    'label' => 'Nombre',
    'rules' => 'required'
]);

• Persistente
• Editable
• Texto libre

3. Campo numérico

$this->addField('postalCode', [
    'label' => 'Código postal',
    'rules' => 'required|numeric'
]);

• Persistente
• Editable
• Numérico

4. Campo monetario (money)

$this->addField('creditLimit', [
    'label' => 'Límite de crédito',
    'rules' => 'required|money'
]);

• Validador custom
• Normalización automática
• Uso financiero

5. Campo readonly

$this->addField('Contacto', [
    'label' => 'Contacto',
    'rules' => 'readonly'
]);

• Visible
• No editable

6. Campo hidden

$this->addField('Contacto', [
    'label' => 'Contacto',
    'rules' => 'readonly',
    'type'  => 'hidden'
]);

• No visible en formularios
• Útil para UX

7. Campo calculado (query)

$this->addField('Contacto', [
    'label' => 'Contacto',
    'rules' => 'readonly',
    'query' => "concat(contactLastName, ', ', contactFirstName)",
    'type'  => 'hidden'
]);

• No persistente
• SQL dinámico
• Solo lectura

8. Campo relacionado (addSearch)

$this->addSearch('salesRepEmployeeNumber', 'Tienda\\Empleados');

• Clave foránea lógica
• Selector dinámico
• Sin JOIN manual

9. Campo clave primaria

$this->setIdField('customerNumber');

• Identidad del dataset

• Obligatorio

• Por defecto, los campos Id se consideran autoincrementales. Si no es el caso, se debe incluir explícitamente $this->setAutoIncrement(false);.

10. Campo dropdown (enum)

• Breve descripción: un dropdown (enum) presenta un conjunto cerrado de opciones (clave => etiqueta). Se almacena la clave seleccionada en la base de datos; la etiqueta se usa solo para la interfaz.

• Configuración típica:

• type: "dropdown"
• options: array asociativo [valor => etiqueta]
• default: clave por defecto
• rules: validar con reglas CI4 (ej. required, in_list)

• se recomienda para listas cortas y estables; para grandes volúmenes usar addSearch (selector relacionado).

• Ejemplo estático:

$this->addField('status', [
        'label'   => 'Estado',
        'type'    => 'dropdown',
        'options' => [
                'shipped'   => 'Enviado',
                'pending'   => 'Pendiente',
                'cancelled' => 'Cancelado'
        ],
        'default' => 'pending',
        'rules'   => 'required|in_list[shipped,pending,cancelled]'
]);

• Ejemplo dinámico (cargar desde DB):

$rows   = $this->db->table('categories')->select('id, name')->get()->getResultArray();
$options = array_column($rows, 'name', 'id');

$this->addField('categoryId', [
        'label'   => 'Categoría',
        'type'    => 'dropdown',
        'options' => $options,
        'rules'   => 'required|in_list[' . implode(',', array_keys($options)) . ']'
]);

• Placeholder / opción vacía: agregar una entrada con clave vacía para forzar selección: 'options' => ['' => '(Seleccione)'] + $options

• Validación y seguridad:

• Use in_list para evitar valores no permitidos.

• Si las opciones son dinámicas, regenere la lista en cada carga de formulario para que la in_list coincida.

• UX y performance:

• Dropdown para <~20-30 opciones.
• Para relaciones con muchas filas, usar addSearch o un componente tipo autocompletar.

• Si necesita seleccionar múltiples valores, prefiera un componente multiselect (o un campo tipo relación); no use dropdown simple.

• Internacionalización: almacene claves estables y traduzca etiquetas en la generación de options para facilitar cambios de idioma.

• Persistencia: el valor guardado es la clave; si necesita guardar la etiqueta, considere un campo calculado o una vista.

11. Resumen

En Ragnos, los campos son declaraciones del dominio, no simples inputs.