Controlador ListController¶
Este controlador es un contenedor de vistas del tipo ListView, que gestiona automáticamente la visualización y filtrado de datos, mostrando la información de cada vista en una tabla de filas y columnas. No permite la edición de los datos pero al hacer click sobre una de las filas se realiza una llamada automática al controlador de edición del modelo. Para este evento se utiliza la configuración de la primera columna que tenga informado el atributo onclick.
Para el uso de este controlador es necesario crear las vistas en formato XML, tal y como se describe en el documento Vistas XML, incluido en la documentación de Facturascripts.
Cómo usar el controlador¶
Para utilizar ListController debemos crearnos una nueva clase PHP que herede o extienda de ListController, debiendo implementar los siguientes métodos:
- createViews: Encargado de crear y añadir las vistas que deseamos visualizar dentro del ListController.
- getPageData: Establece los datos generales (título, icono, menú, etc) para la vista principal (la primera que añadimos en createViews). Este método se vió en el apartado Controlador y es obligatorio en todos los controladores.
Añadir y configurar las vistas¶
createViews¶
Dentro de este método, en nuestra nueva clase, debemos ir creando las distintas vistas que se visualizarán, y para cada vista debemos indicar los campos de búsqueda y los campos de ordenación. Opcionalmente podremos añadir opciones de filtrado para que el usuario pueda complementar el filtrado de búsqueda existente. Este método tiene una visibilidad de protected de manera que los plugins pueden ir extendiendo nuestra clase y añadir nuevas vistas, o modificar las existentes.
La manera de añadir una vista es mediante el método addView incluido en el propio controlador. Una vez añadida la vista, debemos configurarla indicando los campos de búsqueda y la ordenación mediante los métodos addSearchFields y addOrderBy.
addView¶
Este método añade una nueva vista o pestaña al controlador. Para la correcta llamada al método debemos informar mediante cadenas de texto:
| viewName: | nombre identificador de la pestaña. Debe coincidir con el nombre del archivo XML que define la vista. |
|---|---|
| modelName: | nombre del modelo que utiliza la vista. |
| viewTitle: | título de la pestaña. Se debe indicar el identificador de la cadena a traducir. |
| icon: | identificador Font Awesome del icono. Si se omite el controlador utilizará un icono por defecto. |
addSearchFields¶
Al añadir los campos de búsqueda debemos indicar el nombre de la vista al que añadimos los campos y un array con los nombre de los campos.
Ejemplo de creación y adición de campos para búsqueda
/* Epigrafes */
$this->addView('FacturaScripts\Core\Model\Epigrafe', 'ListEpigrafe', 'Epigrafes');
$this->addSearchFields('ListEpigrafe', ['descripcion', 'codepigrafe', 'codejercicio']);
/* Clientes */
$this->addView('FacturaScripts\Core\Model\Cliente', 'ListCliente', 'customers', 'fa-users');
$this->addSearchFields('ListCliente', ['nombre', 'razonsocial', 'codcliente', 'email']);
/* Grupos */
$this->addView('FacturaScripts\Core\Model\GrupoClientes', 'ListGrupoClientes', 'groups', 'fa-folder-open');
$this->addSearchFields('ListGrupoClientes', ['nombre', 'codgrupo']);
addOrderBy¶
Podemos añadir todos los campos de ordenación, no confundir con los campos de búsqueda, realizando distintas llamadas al método addOrderBy e indicando el nombre de la vista a la que añadimos la ordenación, una o varias expresiones de ordenación (cualquier expresión aceptada por la cláusula ORDER BY de SQL), texto a visualizar al usuario y el indicativo de orden por defecto.
Consideraciones:
- Si se indica una única expresión de ordenación usaremos la expresión entre comillas a modo de cadena de texto.
- Si se indican múltiples expresiones de ordenación usaremos un array de cadenas de texto.
- Si no se indica texto a visualizar, se empleará el valor informado en la expresión de ordenación (aplicando el sistema de traducciones). Se recomienda informar este texto para evitar traducciones erróneas.
- Si no se indica valor de ordenación por defecto, se entiende que no hay una ordenación por defecto y se aplicará el primer orden añadido.
- Al añadir una ordenación siempre se añaden dos opciones de ordenación, una ascendente y otra descendente.
- Para establecer una ordenación por defecto, al añadir la ordenación podemos indicar como valores 1 para la ascendente y 2 para la descendente.
Ejemplo de adición de ordenación (siguiendo el ejemplo anterior) con ordenación por código descendente
/* Epigrafes */
$this->addOrderBy('ListEpigrafe', 'descripcion', 'description');
$this->addOrderBy('ListEpigrafe', 'CONCAT(codepigrafe, codejercicio)', 'code', 2);
$this->addOrderBy('ListEpigrafe', 'codejercicio');
/* Clientes */
$this->addOrderBy('ListCliente', 'codcliente', 'code');
$this->addOrderBy('ListCliente', 'nombre', 'name', 1);
$this->addOrderBy('ListCliente', 'fecha', 'date');
$this->addOrderBy('ListCliente', ['codgrupo', 'codcliente'], 'group');
/* Grupos */
$this->addOrderBy('ListGrupoClientes', 'codgrupo', 'code');
$this->addOrderBy('ListGrupoClientes', 'nombre', 'name', 1);
Personalización con Settings¶
Todas las vistas usadas en los controladores extendidos disponen de la propiedad settings que nos permiten personalizando ciertos aspectos de la vista, además de pasar configuraciones propias a la plantilla TWIG y archivos JavaScripts que implementemos.
Algunos valores utilizados por ListController:
| active: | Indica si la vista (pestaña/tab) está activa o apagada (disabled). |
|---|---|
| icon: | Establece el icono para la vista. |
| modalInsert: | Permite establecer un formulario modal para la inserción de datos. |
| btnNew: | Muestra/Oculta el botón de nuevo. |
| btnDelete: | Muestra/Oculta el botón de eliminar. |
| btnPrint: | Muestra/Oculta el botón de imprimir. |
// Oculta los botones nuevo y eliminar
$this->setSettings('MyView', 'btnNew', false);
$this->setSettings('MyView', 'btnDelete', false);
// Establece el modal action1 como acción al pulsar el botón insertar
$this->setSettings('MyView', 'modalInsert', 'action1');
// Este es un valor nuevo creado por el desarrollador para algún proposito especial
$this->setSettings('MyView', 'myconfig', value);
Adición de filtros¶
El controlador ListController integra un sistema de filtrado de datos que permite personalizar de manera sencilla las opciones de filtrado que se presentan al usuario. Cada tipo de filtro requiere de una parametrización propia para su funcionamiento como el nombre de la vista a la que lo añadimos, y entre los tipos de filtros disponibles están:
| addFilterAutocomplete: | |
|---|---|
Filtro tipo texto donde al escribir el usuario se realiza una consulta al servidor recibiendo una lista de datos que contienen el texto introducido por el usuario.
|
|
| addFilterCheckbox: | |
Filtro tipo checkbox o de selección booleana.
|
|
| addFilterDatePicker: | |
Filtro de tipo fecha que permite seleccionar de un calendario que se despliega al seleccionarse el filtro.
|
|
| addFilterNumber: | |
Filtro de tipo numérico y/o importes.
|
|
| addFilterPeriod: | |
Filtro para seleccionar periodo de fechas mediante la selección de un periodo de una lista o por la introdución de la fecha de inicio y fin. Este filtro al ser añadido añade un filtro de tipo Select y dos filtros de tipo DatePicker ocupando 3 columnas. Esto es importante a la hora de su posicionamiento en la vista si deseamos que no queden cortadas las columnas en distintas lineas.
|
|
| addFilterSelect: | |
Filtro tipo selección de una lista de valores.
[
[ 'code' => 'code1', 'description' => 'desctiption1'],
[ 'code' => 'code2', 'description' => 'desctiption2'],
[ 'codeN' => 'codeN', 'description' => 'desctiptionN'],
]
La descripción se debe indicar ya traducida. Se puede utilizar el sistema de tradución de FacturaScripts llamando al método ToolBox()->i18n()->trans(“descripcion”). En caso de necesitar una lista de valores de una tabla se puede usar el modelo CodeModel incluido en el propio controlador. $countries = $this->codeModel->all('paises', 'codpais', 'nombre');
$this->addFilterSelect('ListFacturaCliente', 'codpais', 'country', 'codpais', $countries);
|
|
| addFilterSelectWhere: | |
Filtro tipo selección de una lista de valores.
[
['label' => 'only-active', 'where' => [ new DataBaseWhere('suspended', 'FALSE') ]],
['label' => 'only-suspended', 'where' => [ new DataBaseWhere('suspended', 'TRUE') ]],
['label' => 'all', 'where' => []]
]
|
|
Ejemplos de filtros¶
$this->addFilterCheckbox('ListCliente', 'debaja', 'De baja');
$this->addFilterDatePicker(ListArticulo, 'fecha', 'Fec. Alta');
$this->addFilterPeriod($viewName, 'fecha', 'date', 'fecha');
$this->addFilterNumber($viewName, 'min-total', 'amount', 'importe', '>=');
$this->addFilterNumber($viewName, 'max-total', 'amount', 'importe', '<=');
$countries = $this->codeModel->all('paises', 'codpais', 'nombre');
$this->addFilterSelect('ListFacturaCliente', 'codpais', 'country', 'codpais', $countries);
$this->addFilterAutocomplete($viewName, 'agent', 'agent', 'codagente', 'agentes', 'codagente', 'nombre');