Crear un Mantenedor desde Cero

¿Qué es un Mantenedor?

Un mantenedor es una pantalla que permite al usuario administrar los registros de una tabla de base de datos: listar, crear, editar y eliminar. Es el CRUD básico del sistema.

En este proyecto, un mantenedor completo se compone de tres capas de código PHP más una capa de JavaScript en el frontend:

Arquitectura en Capas

El sistema sigue una arquitectura en capas estricta. Ninguna capa puede saltarse a otra: la Presentación solo habla con BLL, BLL solo habla con DAO.

Regla de dependencias

Flujo de una operación

Usuario → Controller → BO → Svc → Dao → SQL Server
                     ←   DTO  ←  DTO ←

Archivos a Crear

Para la tabla Tools.Traza necesitas crear los siguientes archivos, en este orden:

DAO Entity — Traza.php

La Entity es un objeto PHP plano (POCO) que representa exactamente una tabla de base de datos. Sus propiedades mapean columna por columna a la tabla SQL.

Ubicación del archivo

Application/Dao/Entities/Tools/Traza.php

Código completo

<?php
namespace Application\Dao\Entities\Tools;

use Intouch\Framework\Annotation\Attributes\Entity;
use Intouch\Framework\Annotation\Attributes\EntityField;

// El atributo #[Entity] le indica al framework a qué schema de BD pertenece
#[Entity(Schema: 'Tools')]
class Traza {
    use TrazaT;   // Trait hermano — extensiones manuales van ahí

    // PrimaryKey: true → campo autoincremental, siempre parte en 0
    #[EntityField(PrimaryKey: true)]
    public int    $IdTraza = 0;

    // Campos normales — tipados, con valor por defecto
    public string $Descripcion    = '';
    public int    $IndVigente     = 0;
    public int    $IndEliminado   = 0;

    function __construct() { }
}

Anotaciones disponibles

Tipos PHP según columna SQL

DAO Trait de Entity — TrazaT.php

El Trait hermano de la Entity existe para que puedas agregar métodos o propiedades sin tocar la clase base (que podría regenerarse). Si no necesitas nada extra, lo dejas vacío.

Ubicación del archivo

Application/Dao/Entities/Tools/TrazaT.php

Código — vacío (mínimo requerido)

<?php
namespace Application\Dao\Entities\Tools;

trait TrazaT {
    // Agrega aquí métodos o propiedades extra si los necesitas
}

DAO VW Entity — VWTraza.php

La VWEntity representa una vista de base de datos (prefijo VW). Se usa para las búsquedas y listados, ya que una vista puede tener JOINs y campos calculados que la tabla base no tiene.

Para Traza, que no tiene llaves foráneas, la vista tiene las mismas columnas que la tabla. Pero el patrón siempre se respeta.

Ubicación del archivo

Application/Dao/Entities/Tools/VWTraza.php

Código completo

<?php
namespace Application\Dao\Entities\Tools;

use Intouch\Framework\Annotation\Attributes\Entity;
use Intouch\Framework\Annotation\Attributes\EntityField;

#[Entity(Schema: 'Tools')]
class VWTraza {
    use VWTrazaT;

    // Nota: la VW NO tiene #[EntityField(PrimaryKey: true)]
    // porque es una vista de solo lectura
    public int    $IdTraza = 0;
    public string $Descripcion    = '';
    public int    $IndVigente     = 0;
    public int    $IndEliminado   = 0;

    function __construct() { }
}

Diferencias entre Entity y VWEntity

Trait de VW Entity — VWTrazaT.php

Application/Dao/Entities/Tools/VWTrazaT.php

<?php
namespace Application\Dao\Entities\Tools;

trait VWTrazaT {
    // Vacío para mantenedor simple
}

DAO DAO Service — TrazaDao.php

El DAO es la clase que expone las operaciones de persistencia para una Entity. Hereda de GenericDao, que ya implementa todas las operaciones estándar. En la mayoría de los casos, el cuerpo queda prácticamente vacío: solo el constructor.

Ubicación del archivo

Application/Dao/Services/Tools/TrazaDao.php

Código completo

<?php
namespace Application\Dao\Services\Tools;

use Application\Dao\Entities\Tools\Traza;
use Intouch\Framework\Dao\GenericDao;

class TrazaDao extends GenericDao {
    use TrazaDaoT;

    function __construct($domain) {
        // Le indica a GenericDao qué Entity manejar y a qué conexión conectarse
        parent::__construct(
            Traza::class,
            $domain
        );
    }
}

¿Qué es $domain?

Es la clave de conexión definida en Application/Configuration/connection.config.json. Siempre se pasa desde la capa BLL usando la constante ConnectionEnum::DEFAULT. Nunca pongas el string directamente.

Operaciones que hereda de GenericDao

Trait del DAO — TrazaDaoT.php

Application/Dao/Services/Tools/TrazaDaoT.php

<?php
namespace Application\Dao\Services\Tools;

trait TrazaDaoT {
    // Agrega aquí métodos DAO adicionales si los necesitas
    // Por ejemplo, consultas SQL personalizadas con stored procedures
}

DAO VW DAO Service — VWTrazaDao.php

Igual que el DAO de la tabla, pero apunta a la VWEntity. Se usa exclusivamente para operaciones de lectura (listados y búsquedas).

Ubicación del archivo

Application/Dao/Services/Tools/VWTrazaDao.php

Código completo

<?php
namespace Application\Dao\Services\Tools;

use Application\Dao\Entities\Tools\VWTraza;
use Intouch\Framework\Dao\GenericDao;

class VWTrazaDao extends GenericDao {
    use VWTrazaDaoT;

    function __construct($domain) {
        parent::__construct(
            VWTraza::class,   // ← apunta a la VWEntity
            $domain
        );
    }
}

Trait del VW DAO — VWTrazaDaoT.php

Application/Dao/Services/Tools/VWTrazaDaoT.php

<?php
namespace Application\Dao\Services\Tools;

trait VWTrazaDaoT {
    // Vacío para mantenedor simple
}

Relación entre los archivos DAO

BLL DTO — TrazaDto.php

El DTO (Data Transfer Object) es el objeto que viaja entre la capa de Presentación y la capa BLL. Es un objeto plano sin lógica, con las mismas propiedades que la Entity pero sin las anotaciones del framework DAO.

Usa el constructor con named parameters de PHP 8, lo que permite instanciarlo pasando solo los campos que necesitas.

Ubicación del archivo

Application/BLL/DataTransferObjects/Tools/TrazaDto.php

Código completo

<?php
namespace Application\BLL\DataTransferObjects\Tools;

class TrazaDto {
    use TrazaDtoT;

    public function __construct(
        // Mismos campos que la Entity, mismos tipos, mismos valores por defecto
        public int    $IdTraza = 0,
        public string $Descripcion    = '',
        public int    $IndVigente     = 0,
        public int    $IndEliminado   = 0,
    ) { }
}

Named parameters — ¿cómo se usa?

// Crear un DTO pasando solo los campos necesarios (PHP 8+)
$traza = new TrazaDto(
    IdTraza: 0,
    Descripcion:    'Cardiología',
    IndVigente:     1,
    IndEliminado:   0
);

// También válido: solo ID (el resto toma su valor por defecto)
$traza = new TrazaDto(IdTraza: 42);

Trait del DTO — TrazaDtoT.php

Application/BLL/DataTransferObjects/Tools/TrazaDtoT.php

<?php
namespace Application\BLL\DataTransferObjects\Tools;

trait TrazaDtoT {
    // El Trait del DTO es el lugar correcto para agregar:
    // - Propiedades calculadas (ej: nombre completo)
    // - Colecciones de objetos relacionados (ej: public array $Profesionales = [])
    // - __get / __set para acceso dinámico a propiedades no declaradas
}

BLL VW DTO — VWTrazaDto.php

Igual que el DTO, pero para la vista. Se usa para los resultados de búsqueda que llena la grilla.

Ubicación del archivo

Application/BLL/DataTransferObjects/Tools/VWTrazaDto.php

Código completo

<?php
namespace Application\BLL\DataTransferObjects\Tools;

class VWTrazaDto {
    use VWTrazaDtoT;

    public function __construct(
        public int    $IdTraza = 0,
        public string $Descripcion    = '',
        public int    $IndVigente     = 0,
        public int    $IndEliminado   = 0,
    ) { }
}

Trait — VWTrazaDtoT.php

<?php
namespace Application\BLL\DataTransferObjects\Tools;

trait VWTrazaDtoT {
    // Vacío para mantenedor simple
}

BLL Service — TrazaSvc.php

El Service (Svc) conecta el trío DTO + Entity + Dao. Es quien sabe cómo mapear un DTO a una Entity y viceversa. Hereda de GenericSvc, que ya implementa todo el mapeo y expone las mismas operaciones que el DAO pero trabajando con DTOs.

Ubicación del archivo

Application/BLL/Services/Tools/TrazaSvc.php

Código completo

<?php
namespace Application\BLL\Services\Tools;

use Application\Dao\Services\Tools\TrazaDao;
use Application\BLL\DataTransferObjects\Tools\TrazaDto;
use Application\Dao\Entities\Tools\Traza;
use Intouch\Framework\BLL\Service\GenericSvc;

class TrazaSvc extends GenericSvc {
    use TrazaSvcT;

    function __construct($domain) {
        parent::__construct(
            TrazaDto::class,    // ← el DTO que maneja
            Traza::class,       // ← la Entity correspondiente
            new TrazaDao($domain)  // ← el DAO que usa internamente
        );
    }
}

Operaciones que hereda de GenericSvc

Las mismas que GenericDao pero recibe y retorna DTOs en lugar de Entities:

Transacciones — métodos estáticos de GenericSvc

// Iniciar transacción
GenericSvc::BeginMultipleOperations(ConnectionEnum::DEFAULT);

// ... operaciones Insert/Update/Delete ...

// Confirmar
GenericSvc::SaveMultipleOperations();

// O revertir (en el catch)
GenericSvc::UndoMultipleOperations();

Trait del Svc — TrazaSvcT.php

Application/BLL/Services/Tools/TrazaSvcT.php

<?php
namespace Application\BLL\Services\Tools;

trait TrazaSvcT {
    // Aquí puedes definir $innerMappings = [] para mapeos especiales DTO ↔ Entity
    // Vacío para mantenedor simple
}

BLL VW Service — VWTrazaSvc.php

El Svc de la vista, que se usa exclusivamente para búsquedas con filtros en el BO.

Ubicación del archivo

Application/BLL/Services/Tools/VWTrazaSvc.php

Código completo

<?php
namespace Application\BLL\Services\Tools;

use Application\Dao\Services\Tools\VWTrazaDao;
use Application\BLL\DataTransferObjects\Tools\VWTrazaDto;
use Application\Dao\Entities\Tools\VWTraza;
use Intouch\Framework\BLL\Service\GenericSvc;

class VWTrazaSvc extends GenericSvc {
    use VWTrazaSvcT;

    function __construct($domain) {
        parent::__construct(
            VWTrazaDto::class,
            VWTraza::class,
            new VWTrazaDao($domain)
        );
    }
}

Trait — VWTrazaSvcT.php

<?php
namespace Application\BLL\Services\Tools;

trait VWTrazaSvcT {
    // Vacío para mantenedor simple
}

BLL Business Object — TrazaBO.php

El Business Object (BO) es el corazón de la lógica de negocio. No hereda de ninguna clase base del framework. Contiene un método por cada caso de uso del mantenedor: guardar, buscar, eliminar, validar.

El Controller instancia el BO y le delega todo. El BO nunca genera HTML ni conoce controles de UI.

Ubicación del archivo

Application/BLL/BusinessObjects/Mantenedores/Tools/TrazaBO.php

Código completo

<?php
namespace Application\BLL\BusinessObjects\Mantenedores\Tools;

use Application\BLL\Services\Tools\TrazaSvc;
use Application\BLL\Services\Tools\VWTrazaSvc;
use Application\BLL\DataTransferObjects\Tools\TrazaDto;
use Application\Configuration\ConnectionEnum;
use Intouch\Framework\BLL\Service\GenericSvc;
use Intouch\Framework\Dao\BindVariable;
use Intouch\Framework\Exceptions\BusinessException;
use Intouch\Framework\Exceptions\ExceptionCodesEnum;
use ReflectionClass;

class TrazaBO {

    use TrazaBOT;   // ← flags y validaciones en el Trait

    // ─────────────────────────────────────────────────────────────
    // GUARDAR (actualizar registro existente)
    // ─────────────────────────────────────────────────────────────
    public function GuardarTraza($registro) {

        $trazaSvc = new TrazaSvc(ConnectionEnum::DEFAULT);

        try {
            GenericSvc::BeginMultipleOperations(ConnectionEnum::DEFAULT);

            $traza = new TrazaDto(
                IdTraza: $registro->IdTraza,
                Descripcion:    $registro->Descripcion,
                IndVigente:     $registro->IndVigente,
                IndEliminado:   0   // nunca se actualiza por esta vía
            );

            $trazaSvc->Update($traza);

            GenericSvc::SaveMultipleOperations();
            return true;
        }
        catch(\Exception $e) {
            GenericSvc::UndoMultipleOperations();
            throw $e;
        }
    }

    // ─────────────────────────────────────────────────────────────
    // GUARDAR NUEVO (insertar registro)
    // ─────────────────────────────────────────────────────────────
    public function GuardarNuevaTraza($registro) {

        $trazaSvc = new TrazaSvc(ConnectionEnum::DEFAULT);

        try {
            GenericSvc::BeginMultipleOperations(ConnectionEnum::DEFAULT);

            // Garantizar que se crea un registro nuevo (PK = 0)
            $registro->IdTraza = 0;

            $traza = new TrazaDto(
                IdTraza: $registro->IdTraza,
                Descripcion:    $registro->Descripcion,
                IndVigente:     1,   // los nuevos registros parten vigentes
                IndEliminado:   0
            );

            $nuevaTraza = $trazaSvc->Insert($traza);

            // Verificar que el insert fue exitoso
            if (!isset($nuevaTraza) || $nuevaTraza->IdTraza <= 0) {
                GenericSvc::UndoMultipleOperations();
                throw new \Exception("Ha ocurrido un problema al guardar el registro", 1);
            }

            GenericSvc::SaveMultipleOperations();
            return true;
        }
        catch(\Exception $e) {
            GenericSvc::UndoMultipleOperations();
            throw $e;
        }
    }

    // ─────────────────────────────────────────────────────────────
    // BUSCAR (listado con filtros)
    // ─────────────────────────────────────────────────────────────
    public function BuscarTraza($filtros) {

        // Usamos VWTrazaSvc para la búsqueda (vista de BD)
        $trazaSvc = new VWTrazaSvc(ConnectionEnum::DEFAULT);

        $bindings = [];

        // Flag del Trait: ocultar eliminados lógicamente
        if ($this->OcultarEliminadosEnBusqueda) {
            $bindings[] = new BindVariable("IndEliminado", "=", 0);
        }

        // Filtro por ID exacto
        if (isset($filtros->IdTraza) && $filtros->IdTraza != "-1") {
            $bindings[] = new BindVariable("IdTraza", "=", $filtros->IdTraza);
        }

        // Filtro por descripción (búsqueda parcial)
        if (isset($filtros->Descripcion) && $filtros->Descripcion != "") {
            $bindings[] = new BindVariable("Descripcion", "LIKE", '%' . $filtros->Descripcion . '%');
        }

        return $trazaSvc->GetBy(
            bindings: $bindings,
            avoidNull: true   // evita nulls en el resultado
        );
    }

    // ─────────────────────────────────────────────────────────────
    // VALIDAR ELIMINACIÓN (retorna mensaje si no se puede eliminar)
    // ─────────────────────────────────────────────────────────────
    public function SePuedeEliminarTraza($IdTraza) {

        $mensajes = $this->ValidarEliminarTraza($IdTraza);

        if (count($mensajes) > 0) {
            return implode('<br>', $mensajes);
        }

        return "";   // string vacío = se puede eliminar sin advertencias
    }

    // ─────────────────────────────────────────────────────────────
    // ELIMINAR
    // ─────────────────────────────────────────────────────────────
    public function EliminarTraza($IdTraza) {

        GenericSvc::BeginMultipleOperations(ConnectionEnum::DEFAULT);

        try {
            // Eliminar dependencias en cascada (definidas en el Trait)
            $this->EliminarElementosDependientesTraza($IdTraza);

            $trazaSvc = new TrazaSvc(ConnectionEnum::DEFAULT);

            // Flag del Trait: eliminación lógica (IndEliminado=1) o física
            if ($this->EliminacionLogica) {
                $trazaSvc->LogicDelete($IdTraza);   // soft delete
            }
            else {
                $trazaSvc->Delete($IdTraza);          // hard delete
            }

            GenericSvc::SaveMultipleOperations();
        }
        catch (\Exception $e) {
            GenericSvc::UndoMultipleOperations();
            throw new BusinessException(
                ExceptionCodesEnum::ERR_DATA_DELETE,
                'al intentar eliminar el registro de Traza'
            );
        }

        return '';
    }

    // ─────────────────────────────────────────────────────────────
    // OBTENER DATA (para cargar el popup nuevo o edición)
    // ─────────────────────────────────────────────────────────────
    public function ObtenerDataTraza(
        $IdTraza  = 0,
        $NombreIdPadre   = '',
        $ValorIdPadre    = -1
    ) {
        $data = [];

        if ($IdTraza != 0) {
            // Edición: cargar el registro existente
            $trazaSvc   = new TrazaSvc(ConnectionEnum::DEFAULT);
            $data['Elemento'] = $trazaSvc->Find($IdTraza);
        }
        else {
            // Nuevo: crear un DTO vacío
            $data['Elemento'] = new TrazaDto(IdTraza: 0);
        }

        return (object)$data;
    }
}

BindVariable — filtros dinámicos

El objeto BindVariable es la forma correcta de pasar filtros a GetBy, FindBy y CountBy:

BLL Trait del BO — TrazaBOT.php

El Trait del BO contiene los flags de comportamiento y los métodos de validación y eliminación en cascada. Es el lugar donde personalizas el comportamiento del mantenedor sin tocar la clase base.

Ubicación del archivo

Application/BLL/BusinessObjects/Mantenedores/Tools/TrazaBOT.php

Código completo

<?php
namespace Application\BLL\BusinessObjects\Mantenedores\Tools;

use Application\Configuration\ConnectionEnum;
use Intouch\Framework\Dao\BindVariable;

trait TrazaBOT {

    // ── FLAGS DE COMPORTAMIENTO ──────────────────────────────────

    // true  → EliminarTraza usará LogicDelete (IndEliminado=1)
    // false → usará Delete (borrado físico)
    public $EliminacionLogica           = true;

    // true  → BuscarTraza filtrará WHERE IndEliminado = 0
    public $OcultarEliminadosEnBusqueda = true;

    // ── VALIDACIONES DE ELIMINACIÓN ──────────────────────────────
    public function ValidarEliminarTraza($IdTraza) : array {

        $mensajes = [];

        // Ejemplo: verificar si hay Profesionales asociados antes de eliminar
        //
        // $profesionalSvc = new ProfesionalSvc(ConnectionEnum::DEFAULT);
        // $cantidad = $profesionalSvc->CountBy([
        //     new BindVariable('IndEliminado', '=', 0),
        //     new BindVariable('IdTraza', '=', $IdTraza)
        // ]);
        //
        // if ($cantidad > 0) {
        //     $mensajes[] = "Existen $cantidad profesional(es) asociados a esta traza.";
        // }

        return $mensajes;
    }

    // ── ELIMINACIÓN EN CASCADA ───────────────────────────────────
    public function EliminarElementosDependientesTraza($IdTraza) {

        // Ejemplo: eliminar los profesionales de esta traza antes de eliminarla
        // (new ProfesionalBO())->EliminarByTraza($IdTraza);

        return;
    }
}

¿Por qué separar el Trait del BO?

CTRL Controller Web — TrazaController.php

El Controller Web tiene una sola responsabilidad: renderizar la vista principal cuando el usuario navega a la URL del mantenedor. Es el punto de entrada de la ruta web (no AJAX).

En un mantenedor simple, este controller tiene un único método: Ver().

Ubicación del archivo

Application/Controllers/Mantenedores/Tools/TrazaController.php

Código completo

<?php
namespace Application\Controllers\Mantenedores\Tools;

use Application\BLL\BusinessObjects\Mantenedores\Tools\TrazaBO;
use Application\Resources\AssetManagerFactory;
use Intouch\Framework\Annotation\Attributes\ReturnViewResult;
use Intouch\Framework\Annotation\Attributes\Route;
use Intouch\Framework\Controllers\BaseController;

// Seguridad por defecto en toda la clase
#[Route(Authorization: 'ALLOW_ALL', RequireSession: true)]
class TrazaController extends BaseController {
    use TrazaControllerT;

    public function __construct() {
        parent::__construct(assetManagerFactory: new AssetManagerFactory());
    }

    // Solo ADMIN puede acceder a este mantenedor
    #[Route(Authorization: 'ENFORCE', Roles: ['ADMIN'], RequireSession: true)]
    #[ReturnViewResult]
    public function Ver() {

        // Preparar datos iniciales para la vista (DTO vacío, listas de selects, etc.)
        $trazaBO = new TrazaBO();
        $data = $trazaBO->ObtenerDataTraza();

        // RenderView busca la vista en: Views/Mantenedores/Tools/Traza/verView.php
        return $this->RenderView('ver', $data);
    }
}

Anotaciones de ruta y seguridad

¿Cómo resuelve RenderView la vista?

El método RenderView('ver', $data) busca el archivo:

Application/Views/[namespace del controller]/Traza/verView.php

Como el namespace es Mantenedores/Tools, buscará:

Application/Views/Mantenedores/Tools/Traza/verView.php

Trait del Controller Web — TrazaControllerT.php

Application/Controllers/Mantenedores/Tools/TrazaControllerT.php

<?php
namespace Application\Controllers\Mantenedores\Tools;

trait TrazaControllerT {
    // Métodos adicionales del controller web
}

CTRL Controller API — Api/TrazaController.php

El Controller API expone los endpoints AJAX que el JavaScript del frontend llama. Cada método corresponde a una acción del mantenedor: buscar, guardar, eliminar, abrir popup.

Todos los métodos están decorados con #[ReturnActionResult] o #[ReturnActionViewResult] según si retornan datos o HTML.

Ubicación del archivo

Application/Controllers/Api/Mantenedores/Tools/TrazaController.php

Código completo

<?php
namespace Application\Controllers\Api\Mantenedores\Tools;

use Application\BLL\BusinessObjects\Mantenedores\Tools\TrazaBO;
use Application\Resources\AssetManagerFactory;
use Intouch\Framework\Annotation\Attributes\ReturnActionResult;
use Intouch\Framework\Annotation\Attributes\ReturnActionViewResult;
use Intouch\Framework\Annotation\Attributes\Route;
use Intouch\Framework\Controllers\BaseController;
use Intouch\Framework\Exceptions\BusinessException;
use Intouch\Framework\Exceptions\ExceptionCodesEnum;
use Intouch\Framework\View\Display;

#[Route(Authorization: 'ALLOW_ALL', RequireSession: false)]
class TrazaController extends BaseController {

    use TrazaControllerT;

    public function __construct() {
        parent::__construct(assetManagerFactory: new AssetManagerFactory());
    }

    // ─────────────────────────────────────────────────────────────
    // Verificar si se puede eliminar (retorna advertencias)
    // ─────────────────────────────────────────────────────────────
    #[Route(Methods: ['POST'], Authorization: 'ALLOW_ALL', RequireSession: false)]
    #[ReturnActionResult]
    public function SePuedeEliminarTraza($IdTraza) {
        $trazaBO = new TrazaBO();
        return $trazaBO->SePuedeEliminarTraza($IdTraza);
    }

    // ─────────────────────────────────────────────────────────────
    // Eliminar el registro
    // ─────────────────────────────────────────────────────────────
    #[Route(Methods: ['POST'], Authorization: 'ALLOW_ALL', RequireSession: false)]
    #[ReturnActionResult]
    public function EliminarTraza($IdTraza) {
        $trazaBO = new TrazaBO();
        return $trazaBO->EliminarTraza($IdTraza);
    }

    // ─────────────────────────────────────────────────────────────
    // Abrir el popup (nuevo o edición)
    // ─────────────────────────────────────────────────────────────
    #[Route(Methods: ['POST'], Authorization: 'ALLOW_ALL', RequireSession: false)]
    #[ReturnActionViewResult]
    public function PopUpTraza($IdTraza, $NombreIdPadre, $ValorIdPadre) {
        $trazaBO = new TrazaBO();
        $data = $trazaBO->ObtenerDataTraza(
            $IdTraza, $NombreIdPadre, $ValorIdPadre
        );
        // RenderView → Views/Mantenedores/Tools/Traza/popupView.php
        $view = Display::GetRenderer('Mantenedores/Tools/Traza')
                       ->RenderView('popup', $data);
        return $view;
    }

    // ─────────────────────────────────────────────────────────────
    // Guardar (nuevo o existente, diferenciado por ID)
    // ─────────────────────────────────────────────────────────────
    #[Route(Methods: ['POST'])]
    #[ReturnActionResult]
    public function GuardarTraza($TrazaRegistro) {
        $trazaBO = new TrazaBO();

        try {
            // ID = 0 → es nuevo; ID > 0 → actualizar existente
            if (!isset($TrazaRegistro->IdTraza)
                || $TrazaRegistro->IdTraza == 0) {
                $trazaBO->GuardarNuevaTraza($TrazaRegistro);
            }
            else {
                $trazaBO->GuardarTraza($TrazaRegistro);
            }
        }
        catch (\Exception $ex) {
            throw new BusinessException(
                ExceptionCodesEnum::ERR_DATA_INSERT,
                ' al guardar el registro'
            );
        }

        return 0;
    }

    // ─────────────────────────────────────────────────────────────
    // Buscar (retorna HTML de la grilla)
    // ─────────────────────────────────────────────────────────────
    #[Route(Methods: ['POST'], Authorization: 'ALLOW_ALL', RequireSession: false)]
    #[ReturnActionViewResult]
    public function BuscarTraza($RegistroTrazaBuscar) {
        $trazaBO = new TrazaBO();
        $trazas = $trazaBO->BuscarTraza($RegistroTrazaBuscar);

        // RenderView → Views/Mantenedores/Tools/Traza/verGridView.php
        $view = Display::GetRenderer('Mantenedores/Tools/Traza')
                       ->RenderView('verGrid', $trazas);
        return $view;
    }
}

Diferencia entre las anotaciones de retorno

Trait del Controller API — TrazaControllerT.php

Application/Controllers/Api/Mantenedores/Tools/TrazaControllerT.php

<?php
namespace Application\Controllers\Api\Mantenedores\Tools;

trait TrazaControllerT {
    // Endpoints adicionales personalizados van aquí
}

VIEW Vista Principal — verView.php

Esta es la pantalla principal del mantenedor. Contiene el formulario de filtros de búsqueda, los botones de buscar/limpiar/nuevo, y un contenedor vacío donde se inyectará la grilla de resultados vía AJAX.

No contiene HTML crudo: usa los componentes del framework (Display, Panel, Container, FormRowGroup, etc.).

Ubicación del archivo

Application/Views/Mantenedores/Tools/Traza/verView.php

Directivas de layout y bundle JS

@@Layout(authenticated)           ← usa el layout de app autenticada
@@IncludeScriptBundle(mantenedorTrazaJS)  ← incluye el JS del mantenedor

Código completo

<?php
use Application\Views\Mantenedores\Tools\Traza\verGridT;
use Intouch\Framework\View\Display;
use Intouch\Framework\View\DisplayDefinitions\Button;
use Intouch\Framework\View\DisplayDefinitions\FormButton;
use Intouch\Framework\View\DisplayDefinitions\FormRowFieldText;
use Intouch\Framework\View\DisplayDefinitions\FormRowGroup;
use Intouch\Framework\View\DisplayEvents\ButtonOnClickEvent;
use Intouch\Framework\View\DisplayEvents\FormButtonOnClickEvent;
use Intouch\Framework\Widget\Container;
use Intouch\Framework\Widget\Definitions\ActionButton\ButtonStyleEnum;
use Intouch\Framework\Widget\Panel;
use Intouch\Framework\Widget\Text;
use Intouch\Framework\Widget\TitleDescription;
?>

@@Layout(authenticated)
@@IncludeScriptBundle(mantenedorTrazaJS)

<?php
// ── ENCABEZADO DE PÁGINA ─────────────────────────────────────────
$pageHeader = verGridT::GetHeader();   // título e ícono definidos en verGridT
$pageHeader->Draw();

$display = new Display();

// ── BOTONES DEL FORMULARIO DE BÚSQUEDA ──────────────────────────
$display->AddButton(
    new FormButton(
        Key:         'btnBuscarTraza',
        FormKey:     'frmencabezado',
        Child:       new Text('Buscar Trazas'),
        ButtonStyle: ButtonStyleEnum::BUTTON_INFO,
        Classes:     ['pull-right'],
        Events:      [new FormButtonOnClickEvent()]
    )
);

$display->AddButton(
    new FormButton(
        Key:         'btnLimpiarTraza',
        FormKey:     'frmencabezado',
        Child:       new Text('Limpiar Filtros'),
        ButtonStyle: ButtonStyleEnum::BUTTON_DEFAULT,
        Styles:      [['margin-right', '8px']],
        Classes:     ['pull-right'],
        Events:      [new FormButtonOnClickEvent()]
    )
);

// ── CAMPOS DE FILTRO ─────────────────────────────────────────────
$rowGroups = [];
$rowGroups[] = new FormRowGroup(
    Key:   'grp-informacion-traza',
    Title: 'Opciones de Búsqueda',
    Rows: [
        [
            // Campo de texto para filtrar por descripción
            'Descripcion' => new FormRowFieldText(
                PropertyName: 'Descripcion',
                Label:        'Nombre',
                Colspan:      4
            ),
        ]
    ]
);

$display->AddFormFromObject(
    formKey:      'frmencabezado',
    object:       $data,       // DTO vacío pasado desde el Controller
    fillData:     false,       // no pre-llenar con datos
    keyFieldName: 'IdTraza',
    rowGroups:    $rowGroups
);

// ── BOTÓN NUEVO ──────────────────────────────────────────────────
$display->AddButton(
    new Button(
        Key:         'btnNuevaTraza',
        Child:       new Text('Nuevo'),
        Classes:     ['pull-right'],
        ButtonStyle: ButtonStyleEnum::BUTTON_PRIMARY,
        Events:      [new ButtonOnClickEvent()]
    )
);

// ── LAYOUT GENERAL ───────────────────────────────────────────────
(
    new Container(
        Classes: ['view-content'],
        Children: [
            // Panel superior: filtros de búsqueda
            new Panel(
                Body: new Container(
                    Children: [
                        $display->Widgets()['frmencabezado'],
                        $display->Widgets()['btnBuscarTraza'],
                        $display->Widgets()['btnLimpiarTraza'],
                    ]
                ),
            ),
            // Panel inferior: contenedor de la grilla (se llena por AJAX)
            new Panel(
                Header: new Container(
                    Children: [
                        $display->Widgets()['btnNuevaTraza'],
                        new TitleDescription(
                            Title:       'Resultado',
                            Description: 'Listado de: Traza'
                        )
                    ]
                ),
                Body: new Container(
                    Key:      'formulario-traza',  ← ID usado por el JS para inyectar la grilla
                    Children: []
                ),
            )
        ]
    )
)->Draw();

$display->DrawScripts();

Componentes clave

VIEW Vista Grilla — verGridView.php

Esta vista genera la tabla de resultados. El Controller API la renderiza y la devuelve como HTML al JavaScript, que la inyecta en el contenedor #formulario-traza.

Define las columnas de la tabla, los botones de acción por fila (Editar, Eliminar), y delega el orden y visibilidad a verGridT.

Ubicación del archivo

Application/Views/Mantenedores/Tools/Traza/verGridView.php

Código completo

<?php
use Application\Views\Mantenedores\Tools\Traza\verGridT;
use Intouch\Framework\BLL\Filters\DataTableSettingsFilterDto;
use Intouch\Framework\View\Display;
use Intouch\Framework\View\DisplayDefinitions\TableButton;
use Intouch\Framework\View\DisplayDefinitions\TogglePlacementEnum;
use Intouch\Framework\View\DisplayDefinitions\TableCell;
use Intouch\Framework\View\DisplayEvents\TableButtonOnClickEvent;
use Intouch\Framework\Widget\Container;
use Intouch\Framework\Widget\Definitions\ActionButton\ButtonStyleEnum;
use Intouch\Framework\Widget\FaIcon;
use Intouch\Framework\Widget\Label;
use Intouch\Framework\Widget\Definitions\Label\LabelSizeEnum;
use Intouch\Framework\Widget\Definitions\Label\LabelStyleEnum;

$display = new Display();

// ── DEFINICIÓN DE COLUMNAS ───────────────────────────────────────
$cells = [

    // Columna Descripcion — texto plano
    'Descripcion' => new TableCell(
        PropertyName: "Descripcion",
        Label:        "Nombre",
    ),

    // Columna IndVigente — renderizada como etiqueta SI/NO
    'IndVigente' => new TableCell(
        PropertyName: "IndVigente",
        Label:        "¿Vigente?",
        BodyClasses:  ['text-center'],
        FormatFunction: function($element, $cell) {
            return new Label(
                LabelStyle: ($element->IndVigente == 1)
                    ? LabelStyleEnum::LABEL_SUCCESS
                    : LabelStyleEnum::LABEL_LIGHT,
                LabelSize: LabelSizeEnum::LABEL_LARGE,
                Content:   ($element->IndVigente == 1) ? 'SI' : 'NO'
            );
        }
    ),
];

// Aplicar orden y visibilidad de columnas definido en verGridT
$cells = verGridT::GetCellOrderAndVisibility($cells);
foreach ($cells as $cell) {
    verGridT::CustomCell($cell);
}

// ── BOTONES DE ACCIÓN POR FILA ───────────────────────────────────
$buttons = verGridT::GetCustomButtons();

// Botón Editar → llama a btnEditarTraza_OnClick() en el JS
$buttons[] = new TableButton(
    Child:           new FaIcon('fa-edit'),
    Key:             'btnEditarTraza',
    OnClickClass:    'btn-editar-traza',
    ButtonStyle:     ButtonStyleEnum::BUTTON_WARNING,
    TogglePopUp:     true,
    ToggleText:      'Editar Traza',
    TogglePlacement: TogglePlacementEnum::TOP,
    Events:          [new TableButtonOnClickEvent()],
);

// Botón Eliminar → llama a btnEliminarTraza_OnClick() en el JS
$buttons[] = new TableButton(
    Key:             'btnEliminarTraza',
    Child:           new FaIcon('fa-trash'),
    OnClickClass:    'btn-eliminar-traza',
    ButtonStyle:     ButtonStyleEnum::BUTTON_DANGER,
    TogglePopUp:     true,
    ToggleText:      'Eliminar Traza',
    TogglePlacement: TogglePlacementEnum::TOP,
    Events:          [new TableButtonOnClickEvent()],
);

// ── TABLA DE DATOS ───────────────────────────────────────────────
$display->AddTableFromCollection(
    tableKey:         'tbTraza',
    RowIdFieldName:   'IdTraza',     ← campo que actúa como PK de la fila
    RowAttributeNames: [                    ← atributos data-xxx que se agregan a cada fila
        'IdTraza', 'Descripcion', 'IndVigente', 'IndEliminado'
    ],
    Data:     $data,                        ← array de VWTrazaDto
    Buttons:  $buttons,
    CellDefinitions: $cells,
    TablaSimple: false,
    CustomDataTable: new DataTableSettingsFilterDto(
        HideAllButtons: true
    )
);

(new Container(
    Children: [$display->Widgets()['tbTraza']]
))->Draw();

$display->DrawScripts(addLoadEvent: false);

¿Cómo funciona RowAttributeNames?

El framework agrega atributos data-xxx a cada fila <tr> de la tabla. Cuando el usuario hace click en "Editar" o "Eliminar", el JS lee esos atributos para saber qué registro manipular:

// En el JS, el botón recibe rowInfo con los datos de la fila
function btnEditarTraza_OnClick(rowInfo) {
    PopUpTraza(rowInfo.RowData.pk);   // pk = IdTraza
}

FormatFunction — personalizar celdas

Cuando necesitas mostrar algo diferente al valor crudo del campo, usas FormatFunction:

VIEW Vista Popup — popupView.php

Esta vista genera el formulario modal que aparece cuando el usuario hace click en "Nuevo" o "Editar". El mismo archivo sirve para ambos casos: detecta el modo según si IdTraza > 0.

Ubicación del archivo

Application/Views/Mantenedores/Tools/Traza/popupView.php

Código completo

<?php
use Application\Views\Mantenedores\Tools\Traza\verGridT;
use Intouch\Framework\View\Display;
use Intouch\Framework\View\DisplayDefinitions\FormButton;
use Intouch\Framework\View\DisplayDefinitions\FormRowFieldCheck;
use Intouch\Framework\View\DisplayDefinitions\FormRowFieldHidden;
use Intouch\Framework\View\DisplayDefinitions\FormRowFieldText;
use Intouch\Framework\View\DisplayDefinitions\FormRowGroup;
use Intouch\Framework\View\DisplayEvents\FormButtonOnClickEvent;
use Intouch\Framework\Widget\Container;
use Intouch\Framework\Widget\Definitions\ActionButton\ButtonStyleEnum;
use Intouch\Framework\Widget\Definitions\PopUpModal\ColorLineStyleEnum;
use Intouch\Framework\Widget\PopUpContent;
use Intouch\Framework\Widget\Text;

$display = new Display();

// ── DETECTAR MODO (nuevo vs edición) ────────────────────────────
$editMode = (isset($data) && isset($data->Elemento) && ($data->Elemento->IdTraza) > 0);

// Adaptar textos y estilos según el modo
$btnGuardarText = ($editMode) ? 'Guardar Cambios' : 'Guardar Nuevo';
$btnStyle       = ($editMode) ? ButtonStyleEnum::BUTTON_WARNING   : ButtonStyleEnum::BUTTON_PRIMARY;
$lineStyle      = ($editMode) ? ColorLineStyleEnum::LINE_WARNING   : ColorLineStyleEnum::LINE_SUCCESS;
$popupTitle     = ($editMode) ? 'Editar'                          : 'Nuevo';
$popupSubTitle  = ($editMode) ? 'Editar Traza'             : 'Nueva Traza';

// ── BOTÓN GUARDAR ────────────────────────────────────────────────
$display->AddButton(
    new FormButton(
        Key:        'btnGuardarTraza',
        FormKey:    'frmTraza',
        Child:      new Text($btnGuardarText),
        ButtonStyle: $btnStyle,
        Events:     [new FormButtonOnClickEvent()]
    )
);

// ── CAMPOS DEL FORMULARIO ────────────────────────────────────────
$frmGroups = [];
$frmGroups[] = new FormRowGroup(
    Key:  'IdTraza',
    Rows: [
        [
            // ID siempre oculto (lo lee el JS para saber si es insert o update)
            'IdTraza' => new FormRowFieldHidden(
                PropertyName: 'IdTraza'
            ),

            // Descripción — campo de texto visible
            'Descripcion' => new FormRowFieldText(
                PropertyName: 'Descripcion',
                Label:        'Descripción',
                Required:     false,
                Colspan:      4
            ),

            // IndVigente:
            //   en EDICIÓN → checkbox visible para poder cambiar vigencia
            //   en NUEVO   → hidden (el BO lo setea en 1 automáticamente)
            'IndVigente' => (isset($data->Elemento) && ($data->Elemento->IdTraza > 0))
                ? new FormRowFieldCheck(
                    PropertyName: 'IndVigente',
                    Label:        '<span>&nbsp;</span>',
                    Title:        'Vigente',
                    Required:     false,
                    Colspan:      4
                )
                : new FormRowFieldHidden(
                    PropertyName: 'IndVigente'
                ),

            // IndEliminado — siempre hidden (nunca editable desde UI)
            'IndEliminado' => new FormRowFieldHidden(
                PropertyName: 'IndEliminado'
            ),
        ]
    ]
);

// Delegar el orden de campos a verGridT
$frmGroups = verGridT::GetFormOrderAndVisibility($frmGroups[0], $data);

// ── FORMULARIO ───────────────────────────────────────────────────
$display->AddFormFromObject(
    formKey:     'frmTraza',
    keyFieldName: 'IdTraza',
    object:      $data->Elemento,   ← pre-llena con el DTO (vacío en nuevo, con datos en edición)
    fillData:    true,
    rowGroups:   $frmGroups
);

// ── CONTENEDOR MODAL ─────────────────────────────────────────────
$popUp = new PopUpContent(
    Key:               'popupTraza',
    ColorLineStyle:    $lineStyle,
    Title:             $popupTitle,
    SubTitle:          $popupSubTitle,
    DismissButtonText: 'Cancelar',
    DismissButtonStyle: ButtonStyleEnum::BUTTON_DEFAULT,
    Buttons: [
        $display->Widgets()['btnGuardarTraza'],
    ],
    Content: new Container(
        Classes:  ['view-content'],
        Children: [$display->Widgets()['frmTraza']]
    )
);

$popUp->Draw();
$display->DrawScripts(addLoadEvent: false);
?>

<script>
$(function() {
    // Quitar marca de error al volver a editar el campo
    $('.form-input').on('focus', function() {
        $(this).removeClass('form-error');
    });
    $('.form-input').on('select2:select', function() {
        $(this).removeClass('form-error');
    });
});
//# sourceURL=Traza_PopUp_OnPageLoad.js
</script>

Tipos de campos disponibles

ColorLineStyle del PopUp

VIEW Template de Grilla — verGridT.php

El verGridT es una clase estática que actúa como "template de configuración" de la grilla. Define el orden de columnas, el orden de campos del formulario, y permite personalizar celdas y agregar botones extra. Es el archivo más frecuentemente modificado cuando se necesita ajustar el mantenedor.

Ubicación del archivo

Application/Views/Mantenedores/Tools/Traza/verGridT.php

Código completo

<?php
namespace Application\Views\Mantenedores\Tools\Traza;

use Intouch\Framework\View\DisplayDefinitions\FormRowGroup;
use Intouch\Framework\View\DisplayDefinitions\TableButton;
use Intouch\Framework\View\DisplayEvents\TableButtonOnClickEvent;
use Intouch\Framework\View\DisplayDefinitions\TogglePlacementEnum;
use Intouch\Framework\Widget\Definitions\ActionButton\ButtonStyleEnum;
use Intouch\Framework\Widget\FaIcon;
use Intouch\Framework\Widget\PageHeader;

class verGridT {

    // ── ORDEN DE COLUMNAS DE LA GRILLA ──────────────────────────────
    // Solo las columnas que retornes aquí aparecerán en la tabla.
    // Cambia el orden agregando/quitando elementos del $newArray.
    public static function GetCellOrderAndVisibility($cells, $data = null) : array {
        $newArray = [];
        $newArray[] = $cells['Descripcion'];
        $newArray[] = $cells['IndVigente'];
        return $newArray;
    }

    // ── ORDEN DE CAMPOS DEL FORMULARIO POPUP ────────────────────────
    // Define qué campos aparecen y en qué orden en el modal.
    public static function GetFormOrderAndVisibility($frmGroup, $data) : array {
        $result = [];
        $newfrmGroup = new FormRowGroup(Key: 'frmgrp-traza', Rows: []);
        $row = [];
        $row[] = $frmGroup->Rows[0]['IdTraza'];
        $row[] = $frmGroup->Rows[0]['Descripcion'];
        $row[] = $frmGroup->Rows[0]['IndVigente'];
        $row[] = $frmGroup->Rows[0]['IndEliminado'];
        $newfrmGroup->Rows[] = $row;
        $result[] = $newfrmGroup;
        return $result;
    }

    // ── ORDEN DE CAMPOS DE BÚSQUEDA ─────────────────────────────────
    public static function GetSearchFormOrderAndVisibility($rowGroup) : array {
        $result = [];
        $newrowGroup = new FormRowGroup(Key: 'rowgrp-traza', Rows: []);
        $row = [];
        $row[] = $rowGroup->Rows[0]['Descripcion'];
        $newrowGroup->Rows[] = $row;
        $result[] = $newrowGroup;
        return $result;
    }

    // ── PERSONALIZAR CELDAS INDIVIDUALMENTE ─────────────────────────
    // Modifica propiedades de una celda específica.
    // switch por PropertyName para afectar solo esa columna.
    public static function CustomCell($cell) {

        // Ejemplo automático: columnas "IndXxx" muestran label "¿Xxx?"
        if (substr($cell->PropertyName, 0, 3) == 'Ind') {
            $cell->Label = '¿' . substr($cell->PropertyName, 3) . '?';
        }

        // Personalización por columna específica
        switch ($cell->PropertyName) {

            // Ejemplo:
            // case "Descripcion":
            //     $cell->BodyClasses = ['text-bold'];
            //     return;

            default: return;
        }
    }

    // ── BOTONES EXTRA POR FILA ──────────────────────────────────────
    // Agrega botones adicionales (además de Editar y Eliminar).
    // Ej: un botón "Ver Profesionales" que abre un sub-mantenedor.
    public static function GetCustomButtons($buttons = [], $filtros = null, $isPopup = false) {

        // Ejemplo comentado:
        // $buttons[] = new TableButton(
        //     Child: new FaIcon('fa-users'),
        //     Key: 'btnVerProfesionales',
        //     OnClickClass: 'btn-ver-profesionales',
        //     ButtonStyle: ButtonStyleEnum::BUTTON_PRIMARY,
        //     TogglePopUp: true,
        //     ToggleText: 'Ver Profesionales',
        //     TogglePlacement: TogglePlacementEnum::TOP,
        //     Events: [new TableButtonOnClickEvent()],
        // );

        return $buttons;
    }

    // ── ENCABEZADO DE PÁGINA ────────────────────────────────────────
    // Título, descripción e ícono FontAwesome de la pantalla.
    public static function GetHeader() {
        return new PageHeader(
            Title:       'Trazas',
            Description: 'Seleccione un elemento para editar, o agregue elementos nuevos',
            IconName:    'fa-stethoscope'
        );
    }
}

Guía rápida de modificaciones comunes en verGridT

JS Cliente AJAX — TrazaSvc.js

Este archivo define la clase JavaScript que encapsula todas las llamadas AJAX al Controller API. Sigue el mismo patrón que el Svc PHP: un método por endpoint. El frontend nunca llama directamente a una URL; siempre usa esta clase.

Ubicación del archivo

public/services/mantenedores/Tools/TrazaSvc.js

Código completo

class TrazaSvc extends Service {

    constructor() {
        // Define el prefijo de ruta del Controller API
        // Se resuelve como: /api/mantenedores/tools/traza/{metodo}
        super('mantenedores/tools/traza');
    }

    // Verifica si se puede eliminar (retorna advertencias como HTML)
    SePuedeEliminarTraza(idTraza, onSuccessCallback = null, onErrorCallback = null) {
        this.Call(
            'SePuedeEliminarTraza',
            'post',
            { IdTraza: idTraza },
            onSuccessCallback,
            onErrorCallback,
            { title: 'Por favor espere...', text: 'Verificando...' }
        );
    }

    // Elimina el registro (llamado después de confirmar)
    EliminarTraza(idTraza, onSuccessCallback = null, onErrorCallback = null) {
        this.Call(
            'EliminarTraza',
            'post',
            { IdTraza: idTraza },
            onSuccessCallback,
            onErrorCallback,
            { title: 'Por favor espere...', text: 'Eliminando el registro' }
        );
    }

    // Carga el HTML del popup (nuevo o edición)
    PopUpTraza(idTraza, nombreIdPadre, valorIdPadre, onSuccessCallback = null, onErrorCallback = null) {
        this.Call(
            'PopUpTraza',
            'post',
            {
                IdTraza: idTraza,
                NombreIdPadre:  nombreIdPadre,
                ValorIdPadre:   valorIdPadre
            },
            onSuccessCallback,
            onErrorCallback
        );
    }

    // Guarda el registro (insert o update)
    GuardarTraza(entity, onSuccessCallback = null, onErrorCallback = null) {
        this.Call(
            'GuardarTraza',
            'post',
            entity,
            onSuccessCallback,
            onErrorCallback,
            { title: 'Por favor espere...', text: 'Guardando el registro' }
        );
    }

    // Busca registros y retorna el HTML de la grilla
    BuscarTraza(entity, onSuccessCallback = null, onErrorCallback = null) {
        this.Call(
            'BuscarTraza',
            'post',
            entity,
            onSuccessCallback,
            onErrorCallback
        );
    }
}

// Factory function usada internamente por el framework
function TrazaSvc_invoke() {
    return new TrazaSvc();
}

Signatura de this.Call()

Trait JS — TrazaSvcT.js

public/services/mantenedores/Tools/TrazaSvcT.js

// Código adicional para el funcionamiento del mantenedor de: Traza
// Agregar aquí métodos JS adicionales si se necesitan

JS Lógica Frontend — traza.js

Este archivo contiene los event handlers y la lógica del frontend: qué pasa cuando el usuario hace click en cada botón. El framework llama automáticamente a estas funciones usando la convención {keyDelBoton}_OnClick.

Ubicación del archivo

public/scripts/mantenedores/tools/traza.js

Código completo

// ── INICIALIZACIÓN ───────────────────────────────────────────────
$(function() {
    // Aquí puedes ejecutar código al cargar la página
    // Ej: simular click en "Buscar" para mostrar todos al entrar
    // $('#btnBuscarTraza').trigger("click");
});

// ── VALIDACIÓN DE CAMPO INDIVIDUAL ──────────────────────────────
function ValidarTrazaElemento(elemento) {
    var errores = [];
    var empty   = false;
    var name    = $(elemento).attr('data-property-name');
    var label   = $(elemento).attr('data-property-label');

    if ($(elemento).attr('required') == 'required') {
        if ($(elemento).IsEmpty()) {
            errores.push("Este campo es obligatorio");
            empty = true;
        }
    }
    // Otras validaciones: RUT, email, teléfono
    if (!empty && $(elemento).attr('validar-rut') != null) {
        if (!$(elemento).ValidarRut()) errores.push("El rut ingresado no es válido");
    }

    return { Field: name, Label: label, Cantidad: errores.length, Errores: errores };
}

// ── VALIDACIÓN GENERAL DEL FORMULARIO ───────────────────────────
function ValidarTrazaGeneral(eventInfo) {
    var result         = "";
    var erroresGenerales = [];
    var obj = Object.entries(eventInfo.FormElements);

    for (var i = 0; i < obj.length; i++) {
        let elemento = obj[i][1];
        let errores  = ValidarTrazaElemento(elemento);

        if (errores.Cantidad > 0) {
            erroresGenerales.push(errores);
            $(elemento).addClass('form-error');
        }
    }

    if (erroresGenerales.length > 0) {
        result = '<div class="errores-validacion-container">';
        erroresGenerales.forEach(function(field) {
            result += '<div class="error-validacion-container">';
            result += '<div class="error-validacion-titulo">' + field.Label + '</div>';
            field.Errores.forEach(function(msg) {
                result += '<div class="error-validacion-detalle">' + msg + '</div>';
            });
            result += '</div>';
        });
        result += '</div>';
    }
    return result;
}

// ── EVENTO: LIMPIAR FILTROS ──────────────────────────────────────
function btnLimpiarTraza_OnClick(eventInfo) {
    var obj = Object.entries(eventInfo.FormElements);
    for (var i = 0; i < obj.length; i++) {
        let elemento = obj[i][1];
        if ($(elemento).is('input') || $(elemento).prop('type') == 'text') {
            $(elemento).val('');
        }
        else if ($(elemento).prop('type') == 'select-one' || $(elemento).prop('type') == 'select-multiple') {
            $(elemento).val(-1).change();
        }
    }
}

// ── EVENTO: BUSCAR ───────────────────────────────────────────────
function btnBuscarTraza_OnClick(eventInfo) {

    // Mostrar spinner mientras carga
    $('#formulario-traza').html($('#content-wait-modal').html());
    if ($.fn.DataTable.isDataTable('#tbTraza')) {
        $('#tbTraza').DataTable().destroy();
    }

    Swal.fire({ title: 'Buscando', allowOutsideClick: false,
                showConfirmButton: false, willOpen: () => Swal.showLoading() });

    var formData = eventInfo.FormData;
    var entity = {
        RegistroTrazaBuscar: JSON.stringify({
            Descripcion: (formData.Descripcion == null) ? '' : formData.Descripcion,
        })
    };

    var trazaSvc = new TrazaSvc();
    trazaSvc.BuscarTraza(
        entity,
        function(result) {
            Swal.close();
            $('#formulario-traza').html(result);  ← inyecta la grilla
        },
        function(errorCode, errorMessage) {
            Swal.close();
            $('#formulario-traza').html('<div class="note-box">' + errorMessage + '</div>');
        }
    );
}

// ── FUNCIÓN AUXILIAR: abrir popup ───────────────────────────────
function PopUpTraza(idTraza = 0) {

    var nombreIdPadre = $('#nombre-id-padre').val() || "";
    var valorIdPadre  = $('#valor-id-padre').val()  || -1;

    const trazaPopUp = NewPopUp({ dismissOnOutsideClick: true });
    var trazaSvc = new TrazaSvc();

    trazaSvc.PopUpTraza(
        idTraza, nombreIdPadre, valorIdPadre,
        function(result) {
            $(trazaPopUp).RefreshPopUp(result);  ← inyecta el HTML del modal
        },
        function(errorCode, errorMessage) {
            Toast.fire({ icon: 'error', title: errorMessage });
            $('.modal').modal('hide');
        }
    );
}

// ── EVENTO: NUEVO ────────────────────────────────────────────────
function btnNuevaTraza_OnClick() {
    PopUpTraza();          ← sin ID → modo nuevo
}

// ── EVENTO: EDITAR ───────────────────────────────────────────────
function btnEditarTraza_OnClick(rowInfo) {
    PopUpTraza(rowInfo.RowData.pk);  ← con ID → modo edición
}

// ── EVENTO: GUARDAR (en el popup) ────────────────────────────────
function btnGuardarTraza_OnClick(eventInfo) {

    let formData = eventInfo.FormData;

    // 1. Validar campos requeridos
    var validacionGeneral = ValidarTrazaGeneral(eventInfo);
    if (validacionGeneral != "") {
        Swal.fire({ title: "Errores en el formulario", html: validacionGeneral,
                    width: 640, icon: 'error' });
        return;
    }

    // 2. Validación personalizada (opcional, en trazaT.js)
    if (typeof ValidarTraza === 'function') {
        var validacion = ValidarTraza(formData);
        if (validacion != "") {
            Toast.fire({ icon: 'error', title: validacion });
            return;
        }
    }

    // 3. Armar el payload y llamar al servicio
    const trazaSvc = new TrazaSvc();
    var entity = {
        TrazaRegistro: JSON.stringify({
            IdTraza: formData.IdTraza,
            Descripcion:    formData.Descripcion,
            IndVigente:     formData.IndVigente,
            IndEliminado:   formData.IndEliminado,
        })
    };

    trazaSvc.GuardarTraza(
        entity,
        function(success) {
            // Refrescar la grilla
            $('#btnBuscarTraza').trigger("click");
            Swal.fire({
                title: '¡Guardado!',
                text:  'El registro fue guardado correctamente.',
                icon:  "success",
                confirmButtonText: "OK",
            }).then(() => { $('.modal').last().modal('hide'); });
        },
        function(errorCode, errorMessage) {
            Toast.fire({ icon: 'error', title: errorMessage });
        }
    );
}

// ── EVENTO: ELIMINAR ────────────────────────────────────────────
function btnEliminarTraza_OnClick(rowInfo) {

    const trazaSvc = new TrazaSvc();
    var idTraza    = rowInfo.RowData.pk;

    // 1. Verificar si hay advertencias antes de mostrar confirmación
    trazaSvc.SePuedeEliminarTraza(
        idTraza,
        function(result) {

            var alertWidth = 400;
            if (result != "") {
                result     = '<span class="swal-warning">' + result + '</span><br><br>';
                alertWidth = 640;
            }

            // 2. Mostrar confirmación
            Swal.fire({
                title:              '¿Eliminar registro?',
                html:               result + '<span>¿Confirmas la eliminación?</span>',
                showCancelButton:   true,
                width:              alertWidth,
                confirmButtonText:  'Sí, eliminar',
                cancelButtonText:   'Cancelar',
                confirmButtonColor: '#e0001c',
                cancelButtonColor:  '#9b9b9b',
            }).then((confirmed) => {
                if (confirmed.isConfirmed) {

                    // 3. Ejecutar eliminación
                    trazaSvc.EliminarTraza(
                        idTraza,
                        function() {
                            DropTableRow('tbTraza', idTraza);  ← quita la fila de la grilla
                            Toast.fire({ icon: 'info', title: 'Registro eliminado.' });
                        },
                        function(errorCode, errorMessage) {
                            Toast.fire({ icon: 'error', title: errorMessage });
                        }
                    );
                }
            });
        },
        function(errorCode, errorMessage) {
            Toast.fire({ icon: 'error', title: errorMessage });
        }
    );
}

Convención de nombres de funciones

Trait JS — trazaT.js

public/scripts/mantenedores/tools/trazaT.js

// Extensiones personalizadas del mantenedor de Traza
// Ejemplos de funciones que puedes definir aquí:

// Validación adicional al guardar:
// function ValidarTraza(formData) {
//     if (formData.Descripcion.length < 3) return "La descripción debe tener al menos 3 caracteres.";
//     return "";
// }

// Lógica post-refresco de grilla:
// function CustomRefrescarTrazas(IdTraza) {
//     return true; // retornar true ejecuta el refresco estándar
// }

JS Registro del Bundle JavaScript

Para que la vista pueda incluir los archivos JS del mantenedor con la directiva @@IncludeScriptBundle(mantenedorTrazaJS), ese bundle debe estar registrado en el archivo de configuración central.

Ubicación del archivo

Application/Configuration/bundles.config.json

Entrada a agregar

Busca el archivo JSON y agrega la siguiente entrada en el objeto raíz:

{
  // ... otras entradas existentes ...

  "mantenedorTrazaJS": {
    "IdBundle":       "mantenedorTrazaJS",
    "Tipo":           "javascript",
    "Versionado":     true,
    "BundleLocation": "scripts",
    "Sources": [
      { "Folder": "mantenedores/tools", "File": "traza.js"  },
      { "Folder": "mantenedores/tools", "File": "trazaT.js" }
    ]
  }
}

¿Qué hace cada campo?

✅ Checklist Final

Usa esta lista para verificar que no falta ningún archivo antes de probar el mantenedor en el navegador.

Capa DAO — 8 archivos

• Application/Dao/Entities/Tools/Traza.php
• Application/Dao/Entities/Tools/TrazaT.php
• Application/Dao/Entities/Tools/VWTraza.php
• Application/Dao/Entities/Tools/VWTrazaT.php
• Application/Dao/Services/Tools/TrazaDao.php
• Application/Dao/Services/Tools/TrazaDaoT.php
• Application/Dao/Services/Tools/VWTrazaDao.php
• Application/Dao/Services/Tools/VWTrazaDaoT.php

Capa BLL — 10 archivos

• Application/BLL/DataTransferObjects/Tools/TrazaDto.php
• Application/BLL/DataTransferObjects/Tools/TrazaDtoT.php
• Application/BLL/DataTransferObjects/Tools/VWTrazaDto.php
• Application/BLL/DataTransferObjects/Tools/VWTrazaDtoT.php
• Application/BLL/Services/Tools/TrazaSvc.php
• Application/BLL/Services/Tools/TrazaSvcT.php
• Application/BLL/Services/Tools/VWTrazaSvc.php
• Application/BLL/Services/Tools/VWTrazaSvcT.php
• Application/BLL/BusinessObjects/Mantenedores/Tools/TrazaBO.php
• Application/BLL/BusinessObjects/Mantenedores/Tools/TrazaBOT.php

Controllers — 4 archivos

• Application/Controllers/Mantenedores/Tools/TrazaController.php
• Application/Controllers/Mantenedores/Tools/TrazaControllerT.php
• Application/Controllers/Api/Mantenedores/Tools/TrazaController.php
• Application/Controllers/Api/Mantenedores/Tools/TrazaControllerT.php

Vistas PHP — 4 archivos

• Application/Views/Mantenedores/Tools/Traza/verView.php
• Application/Views/Mantenedores/Tools/Traza/verGridView.php
• Application/Views/Mantenedores/Tools/Traza/popupView.php
• Application/Views/Mantenedores/Tools/Traza/verGridT.php

JavaScript — 4 archivos

• public/services/mantenedores/Tools/TrazaSvc.js
• public/services/mantenedores/Tools/TrazaSvcT.js
• public/scripts/mantenedores/tools/traza.js
• public/scripts/mantenedores/tools/trazaT.js

Configuración — 1 entrada en JSON

• Entrada mantenedorTrazaJS en Application/Configuration/bundles.config.json

Checklist de funcionamiento

• La URL del mantenedor carga sin error 500
• El formulario de búsqueda se muestra correctamente
• Al hacer click en "Buscar" aparece la grilla con los registros
• Al hacer click en "Nuevo" se abre el popup con el formulario vacío
• Al guardar un nuevo registro, aparece en la grilla
• Al hacer click en "Editar" de una fila, el popup se abre con los datos del registro
• Al guardar los cambios, la grilla se actualiza
• Al hacer click en "Eliminar", aparece el diálogo de confirmación
• Al confirmar la eliminación, la fila desaparece de la grilla
• El campo IndVigente se muestra como checkbox solo en modo edición

📋 Referencia Rápida — Convenciones de Nombres