ListController en FacturaScripts

El ListController está diseñado para gestionar listados en FacturaScripts, permitiendo mostrar una o varias pestañas, cada una con el listado de registros de un modelo. Utiliza archivos de XMLView para definir qué columnas mostrar y cómo deben visualizarse.

Ejemplo completo: ListProject.php

A continuación, se muestra cómo implementar un listado de proyectos en el ejemplo MyNewProject:

<?php
namespace FacturaScripts\Plugins\MyNewPlugin\Controller;

use FacturaScripts\Core\Lib\ExtendedController\ListController;

class ListProject extends ListController
{
    public function getPageData(): array
    {
        $page = parent::getPageData();
        $page['title'] = 'projects';
        $page['menu'] = 'sales';
        $page['icon'] = 'fa-solid fa-search';
        return $page;
    }

    protected function createViews()
    {
        // Se crean las pestañas usando funciones separadas para mayor claridad
        $this->createViewsProject();
    }

    protected function createViewsProject(string $viewName = 'ListProject'): void
    {
        $this->addView($viewName, 'Project')
            ->addOrderBy(['name'], 'name')
            ->addSearchFields(['name']);
    }
}

Métodos principales de ListController

createViews()

En este método se deben crear todas las pestañas mediante addView() y definir sus campos de búsqueda, filtros y opciones de ordenación.

addView()

Añade una nueva pestaña para listar los registros de un modelo. Parámetros:

viewName: Nombre identificador de la pestaña, debe coincidir con el archivo XMLView.
modelName: Nombre del modelo a mostrar.
viewTitle (opcional): Título de la pestaña, traducido automáticamente.
icon (opcional): Icono que se mostrará en la pestaña.

Columnas a mostrar

El controlador busca un archivo XMLView con el mismo nombre que la pestaña (viewName). Este archivo determina qué columnas se mostrarán y su formato.

addColor()

Permite añadir colores personalizados a las filas del listado. Más información en Añadir colores desde el controlador.

Ejemplo de uso:

$this->addColor($viewName, 'idestado', $value, $color, $title);

Parámetros de addColor():

$viewName: Nombre identificador de la pestaña.
$fieldName: Campo en el que se realiza la comprobación, debe coincidir con el fieldname del XML.
$value: Valor a comparar.
$color: Color a mostrar en la fila.
$title: Descripción que se muestra en la leyenda del color.

addSearchFields()

Define los campos sobre los que actuará el buscador integrado de la pestaña.

viewName: Nombre identificador de la pestaña.
fields: Array con los campos a buscar.

Ejemplo:

$this->addSearchFields($viewName, ['name', 'description']);
// Alternativamente
$this->listView($viewName)->addSearchFields(['name', 'description']);

addOrderBy()

Añade opciones de ordenación para la pestaña.

viewName: Nombre de la pestaña.
fields: Campos de ordenación (acepta expresiones de SQL ORDER BY).
label (opcional): Título de la opción de ordenación. Si no se especifica, se usará el primer campo.
default (opcional): 1 para orden ascendente por defecto, 2 para descendente.

Nota: Es recomendable incluir dos opciones de ordenación por campo: una ascendente y otra descendente.

Ejemplos:

// Epígrafes
$this->addOrderBy('ListEpigrafe', ['descripcion'], 'description')
    ->addOrderBy(['CONCAT(codepigrafe, codejercicio)'], 'code', 2)
    ->addOrderBy(['codejercicio'], 'exercise');

// Clientes
$this->addOrderBy('ListCliente', ['codcliente'], 'code')
    ->addOrderBy(['nombre'], 'name', 1)
    ->addOrderBy(['fecha'], 'date')
    ->addOrderBy(['codgrupo', 'codcliente'], 'group');

// Grupos
$this->addOrderBy('ListGrupoClientes', ['codgrupo'], 'code')
    ->addOrderBy(['nombre'], 'name', 1);

Personalización con Settings

Todas las vistas permiten personalizar su comportamiento mediante la propiedad settings. Para más detalles, consulte Personalizando con settings.

Añadir botones al listado

Puedes añadir botones a cualquier pestaña con el método addButton() de la vista:

$this->tab($viewName)->addButton([
    'action' => 'my-action',
    'color' => 'warning',
    'icon' => 'fa-solid fa-wand-magic-sparkles',
    'label' => 'my-label'
]);

Al hacer clic se ejecutará la acción my-action del controlador, que debes implementar en el método execPreviousAction() o execAfterAction().

También puedes agrupar varios botones en un desplegable creando primero el grupo con addButtonGroup() y añadiendo después los botones con la clave group:

$this->tab($viewName)->addButtonGroup([
    'name' => 'doc-actions',
    'icon' => 'fa-solid fa-circle-check',
    'label' => 'actions'
]);

$this->tab($viewName)->addButton([
    'group' => 'doc-actions',
    'action' => 'approve-document',
    'icon' => 'fa-solid fa-check',
    'label' => 'approve-document'
]);

Tienes el detalle de todos los tipos y propiedades de los botones en row actions.

Añadir filtros al listado

ListController incluye un sistema para filtrar los datos de manera flexible, permitiendo al usuario seleccionar entre varias opciones según lo que configures. Cada filtro debe ser correctamente parametrizado con el nombre de la vista, el campo sobre el que se aplica, la etiqueta y otros detalles.

Anterior Siguiente