UDA-Componentes RUP. Tabla.v2.4.6

UDA – Utilidades de desarrollo de aplicaciones by EJIE is licensed under a Creative Commons Reconocimiento-NoComercial-CompartirIgual 3.0 Unported License.

UDA - Utilidades de Desarrollo de Aplicaciones

Componente RUP – Tabla

Fecha: 07/03/2016 Referencia:

EJIE S.A.

Mediterráneo, 14

Tel. 945 01 73 00*

Fax. 945 01 73 01

01010 Vitoria-Gasteiz

Posta-kutxatila / Apartado: 809

01080 Vitoria-Gasteiz

www.ejie.es

Componentes RUP – Tabla ii/57

Control de documentación

Título de documento: Componentes RUP – Tabla

Histórico de versiones

Código: Versión: Fecha: Resumen de cambios:

1.0.0 06/06/2011 Primera versión.

1.0.1 25/06/2011 Correcciones en las propiedades de configuración del componente.

1.0.2 18/07/2011 Actualización de las capturas de pantalla. Se han completado las descripciones de las propiedades de configuración del componente.

1.1.0 14/09/2011

Actualización de las versiones de las librerías JavaScript subyacentes.

Añadido el apartado Integración con UDA.

1.2.1 22/02/2012 Inclusión de gestión de eventos.

Diseño líquido (parámetro: fluidBaseLayer).

2.0.0 11/07/2012 Nuevos métodos públicos. Ajustes necesarios para adaptarse a las nuevas funcionalidades de la versión v2.0.0.

2.1.0 18/09/2012 Actualización de las versiones de las librerías JavaScript subyacentes.

2.4.0 22/11/2013

Documento actualizado en base al componente rup.table (deprecado el componente rup.grid).

Se distribuye la versión minimizada de los ficheros javascript y de estilos de RUP.

2.4.1 13/03/2014

Añadido el modulo de Reporting.

Actualizados los apartados de Menú contextual y toolbar.

2.4.2 27/06/2014 Nuevos métodos getActiveRowId y getActiveLineId

2.4.4 03/12/2014

Nuevos eventos rupTable_coreConfigFinished, rupTable_afterDeleteRow, rupTable_afterFormFillDataServerSide, rupTable_formEditCompareData, rupTable_serializeReportData añadidos.

Añadido nuevo método updateSavedData.

Nuevas propiedades fncSearchCriteria, defaultCompareData.

Componentes RUP – Tabla iii/57

2.4.5 10/04/2015

Nuevo plugin Multifilter. Posibilidad de gestionar (añadir, editar, eliminar…) diferentes filtros personalizados por el usuario para realizar filtrados sobre la tabla de resultados.

2.4.6 07/03/2015

Nuevas propiedades del core: excludeSummary y startOnPage.

Nueva propiedad del Multifilter: getDefaults.

Nueva propiedad del FormEdit: dialogOptions.

Cambios producidos desde la última versión

Nuevas propiedades del core: excludeSummary y startOnPage.

Nueva propiedad del Multifilter: getDefaults.

Nueva propiedad del FormEdit: dialogOptions.

Control de difusión

Responsable: Ander Martínez

Aprobado por:

Firma: Fecha:

Distribución:

Referencias de archivo

Autor:

Nombre archivo:

Localización:

Componentes RUP – Tabla iv/57

Contenido

Capítulo/sección Página

1. Introducción 8

2. Ejemplo 8

3. Casos de uso 8

4. Infraestructura 8

4.1. Ficheros 9

4.2. Dependencias 9

4.3. Versión minimizada 10

5. Invocación 11

5.1. Código HTML 11

5.2. Código Javascript 13

6. Plugins 14

6.1. Core 14

6.1.1. Propiedades 15

6.1.2. Métodos 17

6.1.3. Eventos 21

6.2. Menú contextual 22

6.2.1. Declaración y configuración 23


6.2.3. Ejemplo de uso 24

6.3. Feedback 25



6.3.3. Métodos 26

Componentes RUP – Tabla v/57

6.4. Filtrado 27



6.4.3. Métodos 28

6.4.4. Eventos 29

6.5. Multifiltrado 29


6.5.1.1. Archivos de configuración 30

6.5.1.2. Configuración del Controller 31


6.5.3. Métodos 33

6.5.4. Eventos 33

6.6. Diseño líquido 33



6.7. Edición en formulario 34



6.7.3. Funciones 36

6.7.4. Eventos 37

6.8. Edición en línea 39



6.8.3. Funciones 40

6.8.4. Eventos 41

6.9. Jerarquía 42


Componentes RUP – Tabla vi/57


6.9.3. Funciones 43

6.10. Maestro - detalle 43



6.10.3. Funciones 45

6.11. Multiselección 45




6.11.4. Eventos 47

6.12. Búsqueda 48




6.13. Toolbar 51



6.13.3. Ejemplo de uso 51

6.14. Reporting 52



6.14.3. Eventos 54

7. Sobreescritura del theme 54

8. Internacionalización (i18n) 55

9. Integración con UDA 55

9.1. Comunicación con la capa servidor 55

Componentes RUP – Tabla vii/57

9.2. Configuración de Spring 56

9.3. Métodos controller 56

Componentes RUP – Tabla 8/57

1. Introducción

La descripción del componente Tabla , visto desde el punto de vista de RUP, es la siguiente:

Se les presenta a los usuarios los datos tabulados para que la información se visualice de manera ágil y rápida, facilitando así su comprensión y manejo. Además, el componente implementa un nuevo patrón definido para facilitar la lógica necesaria en las acciones básicas, denominadas CRUD (create, read, update y delete), sobre una tabla.

2. Ejemplo

Se muestra a continuación una maquetación típica del componente:

3. Casos de uso

Se aconseja la utilización de este componente:

• Cuando se tenga que presentar a los usuarios filas de datos y se desee facilitar la búsqueda de datos.

• Cuando se realicen mantenimientos de tablas haciendo uso de las especificaciones establecidas en la guía de desarrollo de UDA.

4. Infraestructura

A continuación se comenta la infraestructura necesaria para el correcto funcionamiento del componente.


Únicamente se requiere la inclusión de los ficheros que implementan el componente (js y css) comentados en los apartados Ficheros y Dependencias.

4.1. Ficheros

Ruta Javascript: rup/scripts/

Fichero de plugin: rup.grid-x.y.z.js

Ruta theme: rup/basic-theme/

Fichero de estilos: theme.table-x.y.z.css (modificable por el desarrollador) y ui.jqgrid.css (fichero base de los estilos de la tabla)

Ruta fichero de recursos: rup/resources/rup.i18n_idioma.json

4.2. Dependencias

El desarrollo de los patrones como plugins basados en la librería JavaScript jQuery hace necesaria la inclusión de esta dependencia. La versión elegida para el desarrollo ha sido la versión 1.8.0. Un posible cambio de versión podría no ser trivial y la versión utilizada no debe seleccionarse arbitrariamente. La razón es que el cambio podría provocar errores de funcionamiento e incompatibilidad tanto con los propios patrones como con algunos plugins basados en jQuery.

• jQuery 1.8.0: http://jquery.com/

La gestión de ciertas partes visuales de los patrones, se han realizado mediante el plugin jQuery UI que se basa en jQuery y se utiliza para construir aplicaciones web altamente interactivas. Este plugin proporciona abstracciones de bajo nivel de interacción y animación, efectos avanzados de alto nivel, componentes personalizables (estilos) ente otros. La versión utilizada en el desarrollo ha sido la 1.8.23

• jQuery UI 1.8.23: http://jqueryui.com/

Los ficheros necesarios para el correcto funcionamiento del componente son:

• jquery-1.8.0.js

• jquery-ui-1.8.23.custom.js

• rup.base-x.y.z.js

• rup.table-x.y.z.js

• jQGrid 4.4.0: http://www.trirand.com/blog/

• Ejemplos online: http://www.trirand.com/blog/jqgrid/jqgrid.html


4.3. Versión minimizada

A partir de la versión v2.4.0 se distribuye la versión minimizada de los componentes RUP. Estos ficheros contienen la versión compactada y minimizada de los ficheros javascript y de estilos necesarios para el uso de todos los compontente RUP.

Los ficheros minimizados de RUP son los siguientes:

• rup/scripts/min/rup.min-x.y.z.js

• rup/basic-theme/rup.min-x.y.z.css

Estos ficheros son los que deben utilizarse por las aplicaciones. Las versiones individuales de cada uno de los componentes solo deberán de emplearse en tareas de desarrollo o depuración.


5. Invocación

El componente tabla necesita de una invocación de una llamada javascript sobre una estructura HTML existente.

Cada módulo del componente asocia funcionalidades y eventos a los diferentes objetos de la estructura HTML. De esto modo los componentes feedback, formulario de filtrado, formulario de detalle o multiselección entre otros, deberán de construirse sobre objetos HTML.

En el componente table se ha optado por minimizar el código HTML que se genera al vuelo mediante javascript. Esto permite una serie de mejoras.

• Mayor velocidad de renderizado de la pantalla. El código HTML generado mediante javascript es significativamente más lento, sobre todo en navegadores antiguos.

• Se facilitan las modificaciones y ajustes sobre las diferentes partes del componente ya que se tiene acceso a la mayoría de las mismas directamente desde la jsp.

Para facilitar aún más y simplificar el código necesario a la hora de invocar y configurar el componente, se ha definido una nomenclatura estándar a la hora de indicar los identificadores de los diferentes objetos HTML. De este modo no será necesario indicarle al componente todos los objetos HTML sobre los que debe definir cada una de las funcionalidades.

5.1. Código HTML

Para simplificar la nomenclatura nodos los identificadores de los objetos HTML se derivan a partir del identificador base del componente table.

Para lograr una configuración mínima del componente js se deberá de implementar el siguiente código HTML en la jsp de la pantalla, cuidando los identificadores de cada elemento.

Para el ejemplo supongamos que el componente RUP table se invoca sobre el elemento base con identificador table.

Partiendo de esto, el resto de identificadores se derivarán a partir de la norma:

table_<componente>

Este sería un ejemplo del código HTML que se debería de incluir en la jsp:

<div id =" table_div" class ="rup-table-container" > <div id =" table_feedback" ></ div > <div id =" table_toolbar" ></ div > <div id =" table_filter_div" class ="rup-table-filter" > <form id =" table_filter_form" > <div id =" table_filter_toolbar" class ="formulario_legend" ></ div > <fieldset id =" table_filter_fieldset" class ="rup-table-filter-fieldset" >

 <div id ="table_ filter_buttonSet" class ="right_buttons" >


<input id =" table_filter_filterButton" type ="button" class ="ui-button ui-widget ui-state-default ui-corner-all" value =' <spring:message code ="filter" /> ' /> <a id =" table_filter_cleanLink" href ="javascript:void(0)" class ="rup-enlaceCancelar" ><spring:message code ="clear" /></ a> </ div > </ fieldset > </ form > </ div > <div id =" table_grid_div" >  <table id =" table" ></ table >  <div id =" table_pager" ></ div > </ div > </ div >

La funcionalidad asociada a cada identificador sería:

• table_div : Capa contenedora del componente table. Contendrá todos los módulos del mismo excepto el formulario de detalle.

• table_feedback : Elemento sobre el que se creará el feedback.

• table_toolbar : Elemento sobre el que se creará la botonera que contendrá las acciones a realizar sobre los registrs.

• table_filter_div : Capa que contiene el formulario de filtrado.

• table_filter_form : Formulario de filtrado. Los campos incluidos en este formulario se utilizarán como valores de filtrado de los registros.

• table_filter_toolbar : Capa que contendrá los controles de operación del fomulario de filrado (plegar, desplegar, resumen de criterios de filtrado,..)

• table_filter_fieldset : Fieldset que contendrá los campos del formulario de filtrado.

• filter_buttonSet : Botonera del formulario de filtrado.

• table_filter_filterButton : Botón que realiza el filtrado de los registros de la tabla.

• table_filter_cleanLink : Enlace que realiza la limpieza de los campos del formulario.

• table_grid_div : Capa que contiene la tabla propiamente dicha.

• table : Componente HTML sobre el que se inicializa el componente RUP table.

• table_pager : Paginador de la tabla.

En caso de querer utilizar la edición en formulario se deberá de incluir en la misma jsp el siguiente código HTML:

<div id =" table_detail_div" class ="rup-table-formEdit-detail" > <div id = " table_detail_navigation" ></ div > <div class ="ui-dialog-content ui-widget-content" > <form id =" table_detail_form" > <div id = " table_detail_feedback" ></ div >  </ form > </ div > <div class ="rup-table-buttonpane ui-widget-content ui-helper-c learfix" >


<div class ="ui-dialog-buttonset" > <button id =" table_detail_button_save" type ="button" > <spring:message code ="save" /> </ button > <button id =" table_detail_button_save_repeat" type ="button" > <spring:message code ="saveAndContinue" /> </ button > <a href ="javascript:void(0)" role ="button" id =" table_detail_link_cancel" class ="rup-enlaceCancelar" ><spring:message code ="cancel" /></ a> </ div > </ div > </ div >

La funcionalidad asociada a cada identificador sería:

• table_detail_div : Capa contenedora del formulario de detalle.

• table_detail_navigation : Capa donde se incluirán los controles de navegación y información de los registros.

• table_detail_form : Formulario que contendrá los campos que permitirán la edición de los registros.

• table_detail_feedback : Feedback del formulario de detalle.

• table_detail_button_save : Botón de guardado del registro.

• table_detail_button_save_repeat : Botón que permite guarder el registro y continuar el proceso de edición.

• table_detail_link_cancel : Enlace que permite cancelar el proceso de edición.

5.2. Código Javascript

La invocación del componente propiamente dicha se realizará desde el fichero js correspondiente a la página. Si se ha seguido la nomenclatura del apartado anterior se requerirá únicamente de una configuración mínima:

$( "#table" ).rup_table({ url: "../tableUrl" , colNames: [ "id" , "nombre" , "..."] ], colModel: [

{name: "id" , label: "id" }, {name: "nombre" , label: "nombre" }, {name: "..." , label: "..." }

], model: "Usuario" , usePlugins:[ "formEdit" , "feedback" , "toolbar" , "contextMenu" , "fluid" , "filter" ,


"search" ], primaryKey: "id" ,

});

El uso y configuración de los diferentes plugins de la tabla se especifica en el siguiente apartado.

6. Plugins

El componente table se ha implementado siguiendo una arquitectura modular. De este modo se consigue:

• Integrar las diferentes funcionalidades como plugins independientes logrando una nula interdependencia entre ellas.

• Facilitar y simplificar el mantenimiento y la aplicación de correctivos en el componente.

• Simplificar la extensión y sobreescritura de los métodos de determinados plugins.

• Permitir la creación de nuevas funcionalidades e incluirlas en el componente de manera sencilla e inocua para el resto de funcionalidades existentes.

El uso de los diferentes plugins se determina en la declaración del componente. Mediante la propiedad usePlugins se determina los que se desean utilizar.

La configuración de cada uno de los plugins se indica mediante propiedades de configuración con el mismo nombre que el plugin correspondiente.

Un ejemplo sería el siguiente:

$( "#idComponente" ).rup_table({

url: "../jqGridUsuario" , usePlugins:[ "formEdit" , "feedback" , "toolbar" , "contextMenu" ], formEdit:{ // Propiedades de configuración del plugin formEdit }, contextMenu:{ // Propiedades de configuración del plugin contextM enu }

});

A continuación se va a detallar cada uno de los componentes existentes incluidos en el componente:

6.1. Core

El modulo core es el común al resto de plugins. Contiene las propiedades de configuración imprescindibles para el correcto funcionamiento del componente.


Es también el encargado de inicializar correctamente el resto de módulos de acuerdo a la configuración especificada. Proporciona también eventos y métodos comunes.

6.1.1. Propiedades

• altRows : Determina si se aplica o no el pijama en las filas de la tabla (por defecto true).

• altclass : Estilo que se aplica a las filas impares para mostrar el efecto (por defecto rup-grid_oddRow)

• datatype :: Formato de dato esperado para representar los registros de la tabla (por defecto json)

• height : Determina la altura de la tabla (por defecto auto).

• jsonReader : Parámetros de configuración que determinan el modo en el que se va a procesar el json de retorno del servidor (por defecto {repeatitems: false }).

• resizable : Determina si la tabla puede ser redimensionada mediante el ratón (por defecto false).

• rowNum : Número de registros por página que se van a mostrar en la tabla (por defecto 10).

• rowList : Lista de posibles valores para el número de elementos por página que se van a mostrar en el combo de selección correspondiente (por defecto [10,20,30].

• sortable : Determina si se permite variar el orden de las columnas arrastrándolas (por defecto true).

• viewrecords : Indica si se debe mostrar el rango de elementos que se están visualizando en la tabla (por defecto true).

• loadOnStartUp : Determina si se debe realizar automáticamente la búsqueda al cargar la página (por defecto true).

• multiplePkToken : Separador que se utiliza en los casos en los que la clave primaria sea múltiple. Se creará una columna que contenga un identificador único resultante de la concatenación de las claves primarias realizada mediante el separador aquí indicado (por defecto ~).

• operations: Mediante esta propiedad se definen las posibles operaciones a realizar sobre los registros mostrados en la tabla. Debido al carácter global de estas operaciones se toman en cuenta por otros componentes (toolbar, menú contextual) a la hora de mostrar sus controles. Las operaciones se definen mediante un objeto json en el cual el nombre de la propiedad será el identificador de la propiedad. Cada operación definida consta de las siguientes propiedades:

o name: Texto a mostrar al usuario a la hora de visualizar la operación.

o icon: Clase CSS correspondiente al icono que se quiere visualizar junto a la operación.


o enabled: Función que determina si el botón se debe mostrar habilitado o deshabilitado. Esto se determina devolviendo true/false desde la función de callback aquí indicada.

o callback: Función de callback que será ejecutada cuando el usuario realice una acción sobre la operación.

core:{ operations:{ "operacion1" : { name: "Operación 1" , icon: "rup-icon rup-icon-new" , enabled: function (){ return true ; }, callback: function (key, options){ alert( "Operación 1" ); } }, "operacion2" : { name: "Operación 2" , icon: "rup-icon rup-icon-new" , enabled: function (){ return true ; }, callback: function (key, options){ alert( "Operación 1" ); } } } },

• showOperations: Permite habilitar/deshabilitar las operaciones definidas por defecto por otros módulos.

core:{ showOperations:{ add: false ; clone: false ; } }

• startOnPage: Permite especificar el número de página inicial que se mostrará al cargar la página. Por defecto 1.

El resto de propiedades de configuración del compon ente se especifican con más detalle en la documentación del plugin subyacente jqGrid .


6.1.2. Métodos

• getColModel(): Devuelve la propiedad colModel del jqGrid.

$( "#idComponente" ).rup_table( "getColModel");

• getGridParam(pName): Devuelve el valor del parámetro del grid especificado.

o pName: Nombre del parámetro que se desea obtener.

$( "#idComponente" ).rup_table( "getGridParam","nombreParametro");

• gridResize(options): Permite redimensionar la tabla de acuerdo a los parámetros indicados.

o options: Parámetros para configurar la altura y anchura del redimensionado.

$( "#idComponente" ).rup_table( "gridResize",{});

• getSelectedRows(): Devuelve un array con los identificadores de los registros seleccionados.

$( "#idComponente" ).rup_table( "getSelectedRows");

• getSelectedLines(): Devuelve un array con los números de líneas de los registros seleccionados.

$( "#idComponente" ).rup_table( "getSelectedLines");

• reloadGrid(async): Lanza la recarga de la tabla.

o async: Indica si la llamada debe ser asíncrona o síncrona.

$( "#idComponente" ).rup_table( "reloadGrid", true );

• resetForm($form): Resetea el formulario indicado.

o $form: Objeto jQuery que referencia el formulario que se desea resetear.


$( "#idComponente" ).rup_table( "resetForm", $( "#idFormulario" ) );

• setGridParam(newParams): Asigna a uno o varios parámetros del grid los valores indicados.

o newParams: Objeto que contiene los parámetros y sus valores.

$( "#idComponente" ).rup_table( "setGridParam", {param1:value1, param2:value2} );

• showServerValidationFieldErrors($form, errors): Muestra en los campos del formulario los errores de validación indicados.

o $form: Objeto jQuery que referencia el formulario que se desea resetear.

o errors: Objeto json que contiene los errores de validación que se han dado para cada campo.

$( "#idComponente" ).rup_table( "showServerValidationFieldErrors ",

$( "#idFormulario" ), {} );

• clearHighlightedRowAsSelected($row): Elimina el resaltado de la línea especificada de la tabla.

o $row: Objeto jQuery que referencia a la línea de la tabla.

$( "#idComponente" ).rup_table( "clearHighlightedRowAsSelected",

$( "#idFila" ) );

• highlightRowAsSelected($row): Resalta la línea especificada de la tabla.

o $row: Objeto jQuery que referencia a la línea de la tabla.

$( "#idComponente" ).rup_table( "highlightRowAsSelected", $( "#idFila" ) );

• updateDetailPagination(currentRowNumArg, totalRowNu mArg): Actualiza el valor de los datos que se muestran en la barra de paginación.

o currentRowNumArg: Número actual de los registros que se están mostrando.

o totalRowNumArg: Número total de los registros que se muestran en la tabla.

$( "#idComponente" ).rup_table( "updateDetailPagination", "1-10", "586" );


• addRowData(rowid, data, position, srcrowid): Añade una nueva línea a la tabla. Esta operación no realiza una inserción del registro en el sistema de persistencia, sino que únicamente añade una nueva fila de modo visual.

o rowId: Identificador de la fila.

o data: Objeto json que contiene los valores de cada columna de la nueva línea.

o position: fisrt o last. Determina la posición donde se va a insertar el registro.

o srcrowid: En el caso de indicarse se insertará la nueva línea en la posición relativa al registro que identifica y el valor del parámetro position.

$( "#idComponente" ).rup_table( "addRowData", "10", {campo1:valor1,campo2:valor2});

• delRowData(rowid) : Elimina de la tabla un registro determinado. El registro no se elimina del sistema de persistencia. Solo se elimina de manera visual.

o rowid: Identificador del registro que se desea eliminar.

$( "#idComponente" ).rup_table( "delRowData", "10");

• setRowData(rowid, data, cssp): Actualiza los valores de las columnas de un registro determinado. La actualización de loa datos se realiza solo de manera visual. Los nuevos datos no se persisten.

o rowid: Identificador del registro que se desea actualizar.

o data: Objeto json que contiene los valores de cada columna de la nueva línea.

o cssp: En caso de especificarse, se añadirán a la línea las class de estilos aquí indicadas.

$( "#idComponente" ).rup_table( "setRowData", "10", {campo1:valor1,campo2:valor2});

• getRowData(rowid): Devuelve un objeto json con los valores de los campos del registro indicado.

o rowid: Identificador del registro del que se quieren recuperar los datos.

$( "#idComponente" ).rup_table( "getRowData", "10");

• getDataIDs(): Devuelve un array con los identificadores de los registros que se muestran actualmente en la página de la tabla.

$( "#idComponente" ).rup_table( "getDataIDs");


• clearGridData(clearfooter): Limpia los registros mostrados en la tabla.

o clearfooter: En caso de indicarse como true se elimina la información del pié de la tabla.

$( "#idComponente" ).rup_table( "clearGridData", false );

• getCol(rowid, colName): Devuelve el valor de la columna de la fila indicada.

o rowid: Identificador de la fila.

o colName: Nombre de la columna.

$( "#idComponente" ).rup_table( "getCol", "10", "nombre");

• getSerializedForm(form, skipEmpty): Devuelve un objeto json que contiene la serialización del formulario.

o form: Formulario que se desea serializar.

o skipEmpty: En caso de indicarse true se omiten los campos que no contienen valor.

$( "#idComponente" ).rup_table( "getSerializedForm", $( "#idFormulario" ) , false );

• getActiveRowId(): Devuelve el identificador del registro activo de la tabla. El registro activo dependiendo de la configuración de la tabla se corresponde al siguiente:

o Selección simple: Identificador del elemento seleccionado.

o Multiselección: Identificador del elemento seleccionado entre el conjunto de registros seleccionados sobre el que se va a realizar la acción principal. Por defecto este registro se resalta con un icono.

$( "#idComponente" ).rup_table( "getActiveRowId");

• getActiveLineId(): Devuelve número de línea del registro activo de la tabla. El registro activo dependiendo de la configuración de la tabla se corresponde al siguiente:

o Selección simple: Número de línea del elemento seleccionado.

o Multiselección: Número de línea del elemento seleccionado entre el conjunto de registros seleccionados sobre el que se va a realizar la acción principal. Por defecto este registro se resalta con un icono.

$( "#idComponente" ).rup_table( "getActiveLineId");


• updateSavedData (fnc): Permite modificar el objeto interno _savedData que se utiliza en el control de cambios en el modo de edición en formulario y edición en línea:

o fnc: Función de callback desde la que se puede modificar el objeto _savedData.

$( "#idComponente" ).rup_table( "updateSavedData", function(savedData){ } );

6.1.3. Eventos

A continuación se especifican los nuevos eventos im plementados en el componente. Para ver mas en detalle los proporcionados por el plugin subyacente, acceda a la documentación de jqGrid .

• rupTable_checkOutOfGrid: Evento que se produce al detectarse que el usuario interactua con un elemento externo a la tabla.

o event: Objeto que contiene las propiedades del evento.

o $originalTarget: Objeto jQuery que referencia el elemento del dom con el que ha interactuado el usuario.

$( "#idComponente" ).on( "rupTable_checkOutOfGrid" , function (event, $originalTarget){ });

• rupTable_serializeGridData: Este evento se lanza durante el proceso de serialización de la información que va a ser enviada para obtener los registros que se van a mostrar en la tabla.


o data: Información serializada que va a ser enviada. Se puede modificar o agregar nuevos campos para completarla.

$( "#idComponente" ).on( "rupTable_serializeGridData" , function (event, data){ });

• rupTable_beforeProcessing: Evento que se lanza antes de que se procese la información recibida del servidor.


o data: Información recibida del servidor.


o st: Mensaje de status de la petición.

o xhr: Objeto xhr recibido.

$( "#idComponente" ).on( "rupTable_beforeProcessing" , function (event, data, st, xhr){ });

• rupTableClearHighlightedRowAsSelected : Se produce cuando se elimina el resaltado de un registro de la tabla.


o $row: Objeto jQuery que identifica la línea que se ha procesado.

$( "#idComponente" ).on( "rupTableClearHighlightedRowAsSelected

" , function (event, $row){ });

• rupTableHighlightedRowAsSelected: Se produce cuando se añade el resaltado a un registro de la tabla.


o $row: Objeto jQuery que identifica la línea que se ha procesado.

$( "#idComponente" ).on( "rupTableHighlightedRowAsSelected

" , function (event, $row){ });

• rupTable_coreConfigFinished: Evento que se lanza después de que el componente haya finalizado con el proceso de configuración e inicialización.

$( "#idComponente" ).on( "rupTable_coreConfigFinished" , function (event){ });

6.2. Menú contextual

El modulo menu contextual (contextMenu) permite mostrar un menú con acciones relacionadas con el lugar del componente sobre el que se muestra. Por defecto permite realizar sobre los registros de la tabla, las mismas acciones principales que se muestran en la botonera.


6.2.1. Declaración y configuración

El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “contextMenu”. La configuración del plugin se especifica en la propiedad contextMenu.


url: "../jqGridUsuario" , usePlugins:[ "contextMenu" ], contextMenu:{ // Propiedades de configuración del plugin contextM enu }

});

6.2.2. Propiedades

• createDefaultRowOperations : Propiedad que indica si el componente va a mostrar las operaciones por defecto como opciones dentro del menú contextual. (por defecto a true).

• showOperations : Permite indicar que operaciones definidas de manera global van a ser mostradas como opciones en el menú contextual. Cada operación puede tomar uno de los siguientes valores:

o true: Valor por defecto. Se mostrará la operación como opción del menú contextual.

o false: La operación no se mostrará como opción del menú contextual.

o array: La operación solo se mostrará como opción en aquellas columnas cuyo identificador se especifique entre los elementos del array.

• colNames : Mediante un array se puede configurar las columnas para las cuales se va a mostrar el

• items : Se especifica la configuración de los diferentes items que se van a mostrar en el menú contextual para los registros.


$( '#idComponente ).rup_table({ usePlugins:[ "contextMenu" ],

contextMenu:{ items : { "edit" : {name: "Clickable" , icon: "edit" , disabled: false }, "cut" : {name: "Disabled" , icon: "cut" , disabled: true } } }

});

La configuración de cada uno de los items que se mu estran en el menú contextual, se detalla en la guía de uso del patrón Menú Contextual.

6.2.3. Ejemplo de uso

A continuación se va a mostrar un ejemplo de definición de un caso complejo de las opciones del menú contextual:

$( "#idComponente" ).rup_table({ usePlugins:[ "contextMenu" ], core:{ operations:{ "operacion1" : { name: "Operación 1" , icon: "rup-icon rup-icon-new" , enabled: function (){ return true ; }, callback: function (key, options){ alert( "Operación 1" ); } }, "operacion2" : { name: "Operación 2" , icon: "rup-icon rup-icon-new" , enabled: function (){ return true ; }, callback: function (key, options){ alert( "Operación 1" ); } } } }, contextMenu:{ colNames:[ "nombre" , "apellido1" , "apellido2" , "ejie" , "fechaAlta" ], items: { "sep1" : "---------" , "opContextual1" : {name: "Op. contextual 1" , icon: "edit" , disabled: false , colNames:[ "fechaAlta" , "fechaBaja" , "rol" ]}, "opContextual2" : {name: "Op. contextual 2" , icon: "cut" , disabled: true } }, showOperations:{ operacion1: false , operacion2: [ "nombre" , "apellido1" ] } }

});


A partir del siguiente código se genera lo siguiente:

• Dos operaciones globales (operacion1 y operacion2 ) que serán utilizadas por la toolbar y el menú contextual entre otros.

• Se definen mediante la propiedad items, otras dos opciones extra a ser mostradas como opciones en el menú contextual. Estas opciones serían las identificadas por opContextual1 y

opContextual2 .

• Los valores indicados en la propiedad colNames determinan que las opciones sobre las que son se especifican columnas concretas donde ser visualizadas, van a ser mostradas en las aquí indicadas.

contextMenu:{ colNames:[ "nombre" , "apellido1" , "apellido2" , "ejie" , "fechaAlta" ],

• Se determina que la operacion1 no se va a mostrar en el menú contextual y que la operacion2 se va a visualizar solo en las columnas nombre y apellido1 .

showOperations:{ operacion1: false , operacion2: [ "nombre" , "apellido1" ] }

• La opción opContextual1 solo se mostrará en las columnas fechaAlta , fechaBaja y rol.

items: { "sep1" : "---------" , "opContextual1" : {name: "Op. contextual 1" , icon: "edit" , disabled: false , colNames:[ "fechaAlta" , "fechaBaja" , "rol" ]}, "opContextual2" : {name: "Op. contextual 2" , icon: "cut" , disabled: true } },

6.3. Feedback

Permite configurar un área para informar al usuario de cómo interactuar con el componente. Mediante el componente feedback se mostraran al usuario mensajes de confirmación, avisos y errores que faciliten y mejoren la interacción del usuario con la aplicación.



El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “feedback”. La configuración del plugin se especifica en la propiedad feedback.


url: "../jqGridUsuario" , usePlugins:[ "feedback" ], feedback:{ // Propiedades de configuración del plugin feedback }

});

6.3.2. Propiedades

• id : Nombre del identificador a utilizar en el feedback. Se utiliza en caso de no querer utilizar el por defecto.

• config : Determina la configuración por defecto del feedback.

• okFeedbackConfig : Determina la configuración del feedback en los casos de mensajes de tipo OK.

• errorFeedbackConfig : Determina la configuración del feedback en los casos de mensajes de tipo ERROR.

• alertFeedbackConfig : Determina la configuración del feedback en los casos de mensajes de tipo ALERT.

• internalFeedbackConfig : Determina la configuración del feedback interno de la tabla.

6.3.3. Métodos

• showFeedback($feedback, msg, type, options) : Muestra el feedback indicado con la configuración especificada.

o $feedback: Objeto jQuery que referencia al componente feedback.

o msg: Mensaje a mostrar en el feedback

o type: Clase de feedback a mostrar.

o options: Propiedades de configuración del feedback

$( "#idTable" ).rup_table( "showFeedback" , $( "#idFeedback" ), "Texto..." , "ok" ), {};


6.4. Filtrado

Gestiona las operaciones de filtrado de datos sobre el origen de datos que utiliza el componente.


El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “filter”. La configuración del plugin se especifica en la propiedad filter.


url: "../jqGridUsuario" , usePlugins:[ "filter" ], filter:{ // Propiedades de configuración del plugin filter }

});

6.4.2. Propiedades

• showHidden : Determina si el formulario de filtrado se debe de mostrar inicialmente oculto o no.

• url : Url que se va a utilizar para realizar las peticiones de filtrado de la tabla. En caso de no especificarse una concreta, se utilizará por defecto una construida a partir de la url base. (urlBase + /filter).

• transitionConfig : Configuración del efecto de la animación de mostrar/ocultar el formulario de filtrado.

• fncSearchCriteria : Permite especificar una función de callback en la cual es posible modificar la cadena de texto con la que se muestra el resumen de los parámetros de filtrado.

$( "#idComponente" ).rup_table({ url: "../jqGridUsuario" , usePlugins:[ "filter" ], filter:{


fncSearchString: function(searchString){ //... } // Propiedades de configuración del plugin filter }

});

• excludeSummary: Permite excluir del resumen del filtro los campos especificados. Se debe usar el name del elemento a evitar.

$( "#idComponente" ).rup_table({ url: "../jqGridUsuario" , usePlugins:[ "filter" ], filter:{ excludeSummary:[“nameDelElemento”], // Propiedades de configuración del plugin filter } });

6.4.3. Métodos

• cleanFilterForm(): Limpia los campos del formulario de filtrado

$( "#idComponente" ).rup_table( "cleanFilterForm" );

• filter(async): Realiza el filtrado de acuerdo a los datos existentes en el formulario de filtrado.

o async: Indica si la llamada debe realizarse en modo asíncrono (true) o síncrono (false).

$( "#idComponente" ).rup_table( "filter" );

• getFilterParams: Devuelve los parámetros de filtrado empleados en el filtrado.

$( "#idComponente" ).rup_table( "getFilterParams" );

• hideFilterForm: Oculta el formulario de filtrado.

$( "#idComponente" ).rup_table( "hideFilterForm" );

• showFilterForm : Muestra el formulario de filtrado.

$( "#idComponente" ).rup_table( "showFilterForm" );


• toggleFilterForm : Alterna el estado del formulario de filtrado entre visible y oculto.

$( "#idComponente" ).rup_table( "toggleFilterForm" );

• showSearchCriteria : actualiza el resumen de los criterios de filtrado a partir de los valores existentes en el formulario.

$( "#idComponente" ).rup_table( "toggleFilterForm" );

6.4.4. Eventos

• rupTable_beforeFilter: Se lanza antes de producirse la petición de filtrado.

$("# idComponente ").on(" rupTable_beforeFilter ", function(){ });

• rupTable_filter_beforeClean: El botón de limpiar el formulario, limpia y filtra el formulario. Este evento se lanza después de limpiar el formulario del filtro pero antes de filtrar con el formulario limpio.

$("# idComponente ").on(" rupTable_beforeClean ", function(){ });

6.5. Multifiltrado

Permite la gestión de múltiples filtros para el componente rup_table.



El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “multtifilter”. La configuración del plugin se especifica en la propiedad multifilter. Es condición indispensable para trabajar con el multifilter, haber habilitado el plugin “filter”.


url: "../jqGridUsuario" , usePlugins:[ "multifilter" ], multifilter:{ // Propiedades de configuración del plugin multifil ter }

});

Para trabajar con el multifilter hay que habilitar en la base de datos una tabla con los siguientes campos.

Para el campo FILTER_ID hay que crear una secuencia autonumérica. Los nombres que se den tanto a la tabla como a las columnas no tienen por qué corresponder con las propuestas ya que se puede configurar en el archivo de configuración rup-config.xml

El tamaño de los campos es orientativo, se puede asignar el tamaño deseado dependiendo del proyecto.

6.5.1.1. Archivos de configuración

En el archivo de configuración rup-config.xml hay que configurar el nombre de las columnas de la tabla de Filtro implementada, como también el nombre de la misma. Se especifica así mismo el nombre de la secuencia creada. [spring/rup-config.xml]




<bean id ="x21aFilterDao" class ="com.ejie.x38.rup.jqgrid.filter.dao.FilterDaoImpl" > <property name="filterDataSource" ref ="dataSource" /> <property name="db_filterTableName" value ="FILTER_TABLE" /> <property name="col_filterId" value ="FILTER_ID" /> <property name="col_filterSelector" value ="FILTER_SELECTOR" /> <property name="col_filterName" value ="FILTER_NAME" /> <property name="col_filterUser" value ="FILTER_USER" /> <property name="col_filterValue" value ="FILTER_VALUE" /> <property name="col_filterDefault" value ="FILTER_DEFAULT" /> <property name="filterSeq" value ="FILTER_SEQ" /> </ bean >

<!—Inyección de dependencias del FilterService --> <bean id ="x21aFilterService" class ="com.ejie.x38.rup.jqgrid.filter.service.FilterServi ceImpl" > <property name="filterDao" ref ="x21aFilterDao" />

</ bean >

Para que Jackson pueda serializar y deserializar el objeto Filter se debe añadir la siguiente línea al archivo de configuración de Jackson.

[spring/jackson-config.xml]

<entry key ="#{T(com.ejie.x38.rup.jqgrid.filter.model.Filter)}" value-

ref ="customSerializer" />

6.5.1.2. Configuración del Controller

Para poder acceder al service encargado de gestionar el multifiltro, en el controller que gestiona la pantalla hay que añadir los siguientes métodos configurando el mapping de la url si fuera necesario.

Se ha de declarar una variable de tipo com.ejie.x38.rup.jqgrid.filter.service.FilterService con la anotación @Autowired para que spring pueda gestionar la inyección de dependencias.

//añade o actualiza un filtro

@RequestMapping (value = "/multiFilter/add" , method = RequestMethod. POST) public @ResponseBody Filter filterAdd( @RequestJsonBody (param= "filtro" ) Filter filtro ){ JQGridUsuarioController. logger.info( "[POST - jqGrid] : add filter" ); return filterService .insert( filtro ); }

//borra un filtro @RequestMapping (value = "/multiFilter/delete" , method = RequestMethod. POST) public @ResponseBody Filter filterDelete( @RequestJsonBody (param= "filtro" ) Filter filtro ) { JQGridUsuarioController. logger.info( "[POST - jqGrid] : delete filter" ); return filterService .delete( filtro ); } //Obtien todos los filtros @RequestMapping (value = "/multiFilter/getAll" , method = RequestMethod. GET)


public @ResponseBody List<Filter> filterGetAll( @RequestParam (value = "filterSelector" , required = true ) String filterSelector , @RequestParam(value = "user" , required = true ) String filterUser ) { JQGridUsuarioController. logger.info( "[get - jqGrid] : GetAll filter" ); return filterService .getAllFilters( filterSelector , filterUser );

} // Obtención del filtro por defecto

@RequestMapping (value = "/multiFilter/getDefault" , method = RequestMethod. GET) public @ResponseBody Filter filterGetDefault( @RequestParam(value = "filterSelector" , required = true ) String filterSelector , @RequestParam(value = "user" , required = true ) String filterUser ) { JQGridUsuarioJerarquiaController. logger.info( "[get - jqGrid] : getDefault filter" ); return filterService .getDefault( filterSelector , filterUser );

}

El objeto filtro que se envía en los métodos delete y add tiene la siguiente estructura:

{ filtro: {

filterSelector: settings.id, //identificativo del filtro filterName: multifilterSettings.$comboLabel.val() , //nombre del filtro filterValue: dataFormJson, //Json con los valores del filtro filterDefault: multifilterSettings.$defaultCheck. is(':checked'), //checkbox por defecto filterUser: usuario //usuario del filtro } }

El atributo filterValue contiene los valores de un Filtro serializados en un json con el siguiente formato:

{”name del objteto HTML del formulario”: “valor del objeto”}

Ejemplo:

{"procedimientos":{"pkProcedimientoT49":"453"},"cod igoExpedienteT01":"asdasd","tituloExpedienteT01":"78970644","titular":{"nombreParticipaci onT71_label":"Nerea","nombreParticipacionT71":"Nerea","cifParticipacionT71_label":"789274 42K","cifParticipacionT71":"78977442K"},"notasT01":"sdasd","tablonT10":"N","fases":{"idFa seT08":"300"},"estados":{"estadoIdT09":"3000100"},"expiredWaits":"on","estudiodocumentaci onT01":"on","certificadosConErrorT100":"on","expCerrados":"on","familias":{"grupoFamiliaI dT48":"7"}}

6.5.2. Propiedades

• idFilter : Permite asignar un identificador al filtro. Debe ser único para toda la aplicación. En caso de no asignar un id, se asigna el selector del rup_table.


• labelSize : Permite especificar el tamaño máximo permitido para el nombre del filtro. Es una propiedad obligatoria.

• userFilter : En caso de que la aplicación donde se tiene que implementar el multifiltro no implemente la variable LOGGED_USER, para conservar el usuario identificado, con este parámetro permite asignar un identificador de usuario alternativo.

• getDefault : Determina si el multifiltro debe de cargar el filtro por defecto al cargar la página. Por defecto true.

6.5.3. Métodos

• addFilter(filtro) : Función que añade un filtro al multifiltro

$( "#table" ).rup_table( "addFilter" ,filtro);

• deleteFilter(filtro): Elimina un filtro del multifiltro.

$( "#table" ).rup_table( "deleteFilter" ,filtro);

6.5.4. Eventos

• rupTable_multifilter_beforeAdd: Evento lanzado justo antes de añadir un filtro.

$( "#table" ).on( "rupTable_multifilter_beforeAdd" , function (event,xhr,options){ });

• rupTable_multifilter_fillForm: Evento ejecutado cuando se rellenar el formulario del filtro. Cada vez que se cancela, limpia o se selecciona un filtro se lanza este evento..

$( "#table" ).on( "rupTable_multifilter_fillForm" , function (event,xhr,data){ });

6.6. Diseño líquido

Aplica al componente un diseño líquido de modo que se adapte al ancho de la capa en la que está contenido.



El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “fluid”. La configuración del plugin se especifica en la propiedad fluid.


url: "../jqGridUsuario" , usePlugins:[ "fluid" ], fluid:{ // Propiedades de configuración del plugin fluid }

});

6.6.2. Propiedades

• baseLayer : Identificador de la capa que contiene al componente. Se tomará como base para redimensionar las diferentes partes de la tabla. En caso de no indicarse se tomará por defecto una generada con el patrón identificadorTabla+”_div”.

• maxWidth : Determina la anchura máxima a la que se va a redimensionar la capa.

• minWidth : Determina la anchura mínima a la que se va a redimensionar la capa.

• fluidOffset : Desplazamiento que se aplica a la capa redimensionada.

6.7. Edición en formulario

Permite la edición de los registros de la tabla utilizando un formulario de detalle. El formulario se muestra dentro de un diálogo y ofrece las siguientes funcionalidades:

• Añadir un nuevo registro o modificar uno ya existente.

• Cancelar la inserción o edición de un registro.

• Navegar entre los registros mostrados en la tabla para permitir operar de manera mas ágil sobre los diferentes elementos.



El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “formEdit”. La configuración del plugin se especifica en la propiedad formEdit.


url: "../jqGridUsuario" , usePlugins:[ "formEdit" ], formEdit:{ // Propiedades de configuración del plugin formEdit }

});

6.7.2. Propiedades

Las posibles propiedades que se pueden indicar en c ada una de las siguientes propiedades, se especifican con más detalle en la documentación del plugin subyacente jqGrid .

• addEditOptions : Propiedades de configuración comunes a las acciones de edición e inserción de un registro.

• addOptions : Propiedades de configuración exclusivas de la acción de inserción de un registro. Sobrescriben las indicadas en la propiedad addEditOptions.

• editOptions : Propiedades de configuración exclusivas de la acción de edición de un registro. Sobrescriben las indicadas en la propiedad addEditOptions.


• deleteOptions : Propiedades de configuración de la acción de borrado de un registro.

• detailOptions : Propiedades de configuración de la acción de mostrar un registro mediante el formulario de detalle.

• defaultCompareData : Determina si se debe de realizar la comparación por defecto en el control de cambios del formulario de edición. Por defecto a true.

• dialogOptions: Permite especificar opciones de configuración para el diálogo que contiene el formulario de detalle. Las opciones de configuración se pueden consultar en la guía de desarrollo del componente RUP Diálogo.

formEdit:{ dialogOptions:{ specificLocation:"departamentosIniciativa_d iv" } }

6.7.3. Funciones

• deleteElement(rowId, deleteOptions): Elimina el registro correspondiente al identificador indicado y utilizando las opciones de borrado especificadas.

o rowId: Identificador del registro que se desea eliminar.

o deleteOptions: Opciones de configuración de la operación de borrado.

$( "#idComponente" ).rup_table( "deleteElement" , rowId, deleteOptions);

• editElement(rowId, editOptions ): Edita el registro correspondiente al identificador indicado y utilizando las opciones de edición especificadas.

o rowId: Identificador del registro que se desea editar.

o editOptions: Opciones de configuración de la operación de edición.

$( "#idComponente" ).rup_table( "editElement" , rowId, editOptions);

• newElement(addEvent): Muestra el formulario de detalle para permitir al usuario insertar un nuevo registro.

o addEvent: Determina si se debe lanzar (true) o no (false) el evento rupTable_beforeAddRow.

$( "#idComponente" ).rup_table( "newElement", addEvent);

• cloneElement(rowId, cloneOptions, cloneEvent): Clona el registro correspondiente al identificador indicado y utilizando las opciones de clonado especificadas.

o rowId: Identificador del registro que se desea clonar.


o cloneOptions: Opciones de configuración de la operación de clonado.

o cloneEvent: Determina si se debe lanzar (true) o no (false) el evento rupTable_beforeCloneRow.

$( "#idComponente" ).rup_table( "cloneElement" , rowId, cloneOptions, cloneEvent);

• hideFormErrors($form): Oculta los mensajes de error del formulario indicado.

o $form: Formulario del que se desea ocultar los mensajes de error.

$( "#idComponente" ).rup_table( "hideFormErrors" , $form);

6.7.4. Eventos

A continuación se especifican los nuevos eventos im plementados en el componente. Para ver mas en detalle los proporcionados por el plugin subyacente, acceda a la documentación de jqGrid .

• rupTable_beforeDeleteRow : Evento que se lanza justo antes de procesarse la petición de borrado de un registro. En caso de devolver false se detiene la ejecución del borrado.

$( "#idComponente" ).on( "rupTable_beforeDeleteRow" , function (deleteOptions, selectedRow){ });

• rupTable_beforeEditRow : Evento que se lanza justo antes de procesarse la petición de modificación de un registro. En caso de devolver false se detiene la ejecución de la operación.

$( "#idComponente" ).on( "rupTable_beforeEditRow" , function (deleteOptions, selectedRow){ });

• rupTable_deleteAfterSubmit : Evento que se lanza justo después de realizarse la petición de borrado de un registro.

$( "#idComponente" ).on( "rupTable_deleteAfterSubmit" , function (){ });

• rupTableAfterDelete: Evento que indica que se ha realizado correctamente el borrado de un elemento.

o data: Objeto que contiene la información retornada desde el servidor.

o textStatus: Texto que describe el estado http de la respuesta.


o xhr: Objeto XMLHttpRequest de la petición AJAX de borrado.

$( "#idComponente" ).on( "rupTableAfterDelete" , function (data, textStatus, xhr){ });

• rupTable_beforeAddRow : Evento lanzado antes de ejecutarse el método de inserción de un registro. En caso de retornar false se cancelará la inserción.

o addOptions: Opciones de configuración de la acción de insertar un elemento.

$( "#idComponente" ).on( "rupTable_beforeAddRow" , function (addOptions){ });

• rupTable_beforeCloneRow : Evento lanzado antes de ejecutarse el método de clonado de un registro. En caso de retornar false se cancelará el clonado.

o cloneOptions: Opciones de configuración de la acción de clonar un elemento.

o selectedRow: Identificador de la fila correspondiente al registro que se desea clonar.

$( "#idComponente" ).on( "rupTable_beforeCloneRow" , function (cloneOptions, selectedRow){ });

• rupTable_afterDeleteRow : Evento lanzado después de que ha finalizado correctamente el proceso de eliminar un registro..

$( "#idComponente" ).on( "rupTable_beforeCloneRow" , function (event){ });

• rupTable_afterFormFillDataServerSide : Evento lanzado después de que ha finalizado correctamente el proceso de carga de datos en el formulario de edición a partir de una petición al servidor de aplicaciones.

o xhr: Objeto enviado como respuesta desde el servidor.

o $detailFormToPopulate: Referencia al formulario de detalle.

o ajaxOptions: Opciones de configuración de la petición AJAX.

$( "#idComponente" ).on( "rupTable_afterFormFillDataServerSide" , function (event, savedData, newData){ });

• rupTable_formEditCompareData : Permite asociar manejadores de eventos para ejecutar código que indique al proceso de control de cambios si se han producido modificaciones o no.

o savedData: Objeto que contiene los valores iniciales del formulario a partir de la serialización del mismo.

o newData: Objeto que contiene los valores actuales del formulario a partir de la serialización del mismo.


$( "#idComponente" ).on( "rupTable_formEditCompareData " , function (event, savedData, newData){

/* Se realizan las comprobaciones necesarias para determinar si se han producido

cambios en el formulario de detalle */

event.isDifferent = true; // En caso de que se hayan producido cambios.

event.isDifferent = false; // En caso de que no hayan producido cambios.

});

6.8. Edición en línea

Permite la edición de los registros de la tabla mostrando los campos de edición sobre la propia línea del registro.


El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “inlineEdit”. La configuración del plugin se especifica en la propiedad inlineEdit.


url: "../jqGridUsuario" , usePlugins:[ "inlineEdit" ], inlineEdit:{ // Propiedades de configuración del plugin inlineEd it }

});


6.8.2. Propiedades

Las posibles propiedades que se pueden indicar en c ada una de las siguientes propiedades, se especifican con más detalle en la documentación del plugin subyacente jqGrid .

• addEditOptions : Propiedades de configuración comunes a las acciones de edición e inserción de un registro.

• addOptions : Propiedades de configuración exclusivas de la acción de inserción de un registro. Sobrescriben las indicadas en la propiedad addEditOptions.

• editOptions : Propiedades de configuración exclusivas de la acción de edición de un registro. Sobrescriben las indicadas en la propiedad addEditOptions.

• deleteOptions : Propiedades de configuración de la acción de borrado de un registro.

6.8.3. Funciones

• addRow(addOptions): Añade una nueva línea en blanco al mantenimiento para permitir introducir los datos del nuevo registro.

o addOptions: Opciones de configuración de la acción de inserción.

$( "#idComponente" ).rup_table( "addRow" , addOptions);

• cloneRow(rowId, cloneOptions): Clona un registro determinado. Añade una nueva línea con el contenido del registro a partir del cual se desea clonar.

o rowId: Identificador del registro a partir del cual se desea realizar el clonado.

o cloneOptions: Opciones de configuración de la acción de clonado.

$( "#idComponente" ).rup_table( "cloneRow" , rowId, cloneOptions);

• editRow(rowId, editOptions): Pone el registro indicado en modo edición para permitir la edición de sus datos.

o rowId: Identificador del registro que se desea editar.

o editOptions: Opciones de configuración de la acción de modificación.

$( "#idComponente" ).rup_table( "editRow" , rowId, editOptions);

• deleteRow(rowId, deleteOptions): Elimina el registro indicado.

o rowId: Identificador del registro que se desea eliminar.

o deleteOptions: Opciones de configuración de la acción de borrado.


$( "#idComponente" ).rup_table( "deleteRow" , rowId, deleteOptions);

• saveRow(rowId, saveOptions): Guarda el registro modificado. Se almacenan los datos introducidos en la línea en modo edición.

o rowId: Identificador de la línea que se desea guardar.

o saveOptions:Opciones de configuración de la acción de guaradado.

$( "#idComponente" ).rup_table( "saveRow" , rowId, saveOptions);

• restoreRow(rowId): Restaura la fila indicada al estado anterior a habilitarse el modo edición.

o rowId: Identificador de la línea que se desea guardar.

$( "#idComponente" ).rup_table( "restoreRow" , rowId);

6.8.4. Eventos

A continuación se especifican los nuevos eventos im plementados en el componente. Para ver más en detalle los proporcionados por el plugin subyacente, acceda a la documentación de jqGrid .

• rupTable_deleteAfterSubmit : Evento que se lanza justo después de realizarse la petición de borrado de un registro.

$( "#idComponente" ).on( "rupTable_deleteAfterSubmit" , function (){ });

• rupTableAfterDelete : Evento que indica que se ha realizado correctamente el borrado de un elemento.

o data: Objeto que contiene la información retornada desde el servidor.

o textStatus: Texto que describe el estado http de la respuesta.

o xhr: Objeto XMLHttpRequest de la petición AJAX de borrado.

$( "#idComponente" ).on( "rupTableAfterDelete" , function (data, textStatus, xhr){ });


6.9. Jerarquía

El objetivo principal del módulo Jerarquía es la presentación de un conjunto de datos (tabla) ordenados jerárquicamente en base a una relación existente entre ellos.


El uso del plugin en el componente, se realiza incluyendo en el array de la propiedad usePlugins el valor “jerarquia”. La configuración del plugin se especifica en la propiedad jerarquia.

$( "#idComponenteMaestro" ).rup_table({

url: "../jqGridUsuarioMaestro" , }); $( "#idComponenteDetalle" ).rup_table({

url: "../jqGridUsuarioDetalle" , usePlugins:[ "jerarquia" ], jerarquia:{ // Propiedades de configuración del plugin jeararqu ia }

});

6.9.2. Propiedades


• token : Carácter separador utilizado para concatenar diferentes identificadores de los registros mostrados en la jerarquía. (por defecto “/”).

• icons : Estilos utilizados para cada uno de los elementos visuales de la jerarquía.

o plus: Icono para expandir el nodo.

o minus: Icono para contraer el nodo.

o leaf: Icono correspondiente a un nodo hoja.

o filter: Icono para indicar que el nodo satisface los parámetros de filtrado.

• parentNodesTooltip : Determina si se debe de mostrar un tooltip para cada nodo, en el cual se representa la jerarquía que ocupa respecto a los padres.

• parentNodesTooltipFnc : Función de callback que permite personalizar el tooltip a mostrar.

• contextMenu : Determina si se muestra el menú contextual para cada nodo.

6.9.3. Funciones

• reset : Colapsa los nodos que han sido expandidos.

$( "#idComponente" ).rup_table( "reset" );

6.10. Maestro - detalle

Permite relacionar dos tablas de modo que tengan una relación maestro-detalle. De este modo, los resultados de la tabla detalle se muestran a partir del seleccionado en la tabla maestro.



El uso del plugin en el componente, se realiza incluyendo en el array de la propiedad usePlugins el valor “masterDetail”. La configuración del plugin se especifica en la propiedad masterDetail.

$( "#idComponenteMaestro" ).rup_table({

url: "../jqGridUsuarioMaestro" , }); $( "#idComponenteDetalle" ).rup_table({

url: "../jqGridUsuarioDetalle" , usePlugins:[ "masterDetail" ], masterDetail:{ // Propiedades de configuración del plugin masterDe tail master: "#idComponenteMaestro" }

});

6.10.2. Propiedades

• master: Selector jQuery que referencia al componente maestro.

• masterPrimaryKey: Clave primaria del componente maestro.


6.10.3. Funciones

• getMasterTablePkObject : Devuelve un objeto json con la clave primaria del registro correspondiente de la tabla maestra.

$( "#idComponente" ).rup_table( "getMasterTablePkObject" );

6.11. Multiselección

Permite realizar una selección múltiple de los registros que se muestran en la tabla.


El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “multiselection”. La configuración del plugin se especifica en la propiedad multiselection.


url: "../jqGridUsuario" , usePlugins:[ "multiselection" ], multiselection:{ // Propiedades de configuración del plugin multisel ection }


});

6.11.2. Propiedades

• headerContextMenu _enabled: Habilita el menú contextual que se muestra en el check de multiselección en la cabecera de la tabla.

• headerContextMenu : Propiedades de configuración del menú contextual de la cabecera de la tabla.

• rowContextMenu_enabled : Habilita el menú contextual que se muestra en los checks correspondientes a cada registro.

• rowContextMenu : Propiedades de configuración de los menús contextuales asociados a cada registro.

6.11.3. Funciones

• getSelectedIds(): Devuelve un array con los identificadores de los registros seleccionados.

$( "#idComponente" ).rup_table( "getSelectedIds" );

• setSelection(selectedRows, status, reorderSelection ): Selecciona o deselecciona los registros indicados.

o selectedRows: Identificador o array de identificadores de los registros que se desea seleccionar o deseleccionar.

o status: En caso de ser true se seleccionarán los registros indicados. En caso de ser false se deseleccionarán.

o reorderSelection: Determina (true/false) si se debe realizar una reordenación de los elementos seleccionados en la siguiente petición.

$( "#idComponente" ).rup_table( "setSelection", ["3","7"], true );

• clearHighlightedEditableRows(): Se elimina el resaltado de las filas que se muestran como editables.

$( "#idComponente" ).rup_table( "clearHighlightedEditableRows" );

• highlightFirstEditableRow(): Resalta como editable el primer registro seleccionado de la página.

$( "#idComponente" ).rup_table( "highlightFirstEditableRow" );


• highlightEditableRow(): Resalta como editable el registro correspondiente.

$( "#idComponente" ).rup_table( "highlightEditableRow" );

• resetSelecion(): Resetea la selección realizada sobre los registros de la tabla.

$( "#idComponente" ).rup_table( "resetSelecion" );

• selectAllRows(): Se seleccionan todos los registros de la página mostrada en la tabla.

$( "#idComponente" ).rup_table( "selectAllRows" );

• selectRemainingRows(): Se seleccionan los registros restantes de la página que no han sido seleccionados previamente.

$( "#idComponente" ).rup_table( "selectRemainingRows" );

• deselectAllRows(): Se deseleccionan todos los registros de la página mostrada en la tabla.

$( "#idComponente" ).rup_table( "deselectAllRows" );

• deselectRemainingRows(): Se deseleccionan los registros restantes de la página que no han sido deseleccionados previamente.

$( "#idComponente" ).rup_table( "deselectRemainingRows" );

• updateSelectedRowNumber(): Actualiza el contador de la tabla que indica los registros seleccionados.

$( "#idComponente" ).rup_table( "updateSelectedRowNumber" );

6.11.4. Eventos


• rupTable_multiselectionUpdated : Indica que se ha actualizado el componente gestor de la multiselección.

$( "#idComponente" ).on( "rupTable _multiselectionUpdated" , function (event){ });

• rupTableSelectedRowNumberUpdated: Indica que se ha actualizado el número de elementos seleccionados.

$( "#idComponente" ).on( " rupTableSelectedRowNumberUpdated" , function (event){ });

6.12. Búsqueda

Permite al usuario realizar una búsqueda entre el conjunto de resultados que se le muestran. Mediante una serie de criterios de búsqueda permite al usuario posicionarse entre los diferentes registros que se ajustan a dichos criterios.


El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “search”. La configuración del plugin se especifica en la propiedad search.


url: "../jqGridUsuario" , usePlugins:[ "search" ], search:{ // Propiedades de configuración del plugin search }

});


6.12.2. Propiedades

• validate : Mediante esta propiedad es posible especificar reglas de validación que se especifican en la guía de uso del componente RUP validation.

El resto de propiedades de configuración del compon ente se especifican con más detalle en la documentación del plugin subyacente jqGrid .

6.12.3. Funciones

• toggleSearchForm (): Muestra/Oculta el formulario de búsqueda.

$( "#idComponente" ).rup_table( "toggleSearchForm" );

• createSearchToolbar(): Genera la barra de controles para gestionar la búsqueda.

$( "#idComponente" ).rup_table( "createSearchToolbar" );

• createSearchRow(settings): Genera la línea de busqueda de acuerdo a las propiedades de configuración especificadas.

o settings: Opciones de configuración indicadas en la incialización del componente.

$( "#idComponente" ).rup_table( "createSearchRow", settings );

• navigateToMatchedRow(matchedRow): Navega hasta el elemento indicado que se ajusta a los criterios de búsqueda indicados.

o matchedRow: Línea a la cual se quiere navegar.

$( "#idComponente" ).rup_table( "navigateToMatchedRow", matchedRow);

• search(): Lanza la operación de búsqueda.

$( "#idComponente" ).rup_table( "search" );


• goToFirstMatched(paramPage): Navega hasta el primer elemento que se ajusta a los criterios de búsqueda. En caso de no existir elementos adecuados en la página actual se navega hasta el primer elemento.

o paramPage: En caso de indicarse una página se utilizará en vez de la página actual.

$( "#idComponente" ).rup_table( "goToFirstMatched" );

• cleanSearch(): Limpia los criterios de búsqueda introducidos por el usuario.

$( "#idComponente" ).rup_table( "cleanSearch" );

• clearHighlightedMatchedRows(): Elimina el resaltado de los registros que se ajustan a los criterios de busqueda.

$( "#idComponente" ).rup_table( "clearHighlightedMatchedRows" );

• highlightMatchedRowsInPage(): Resalta los registros que se ajustan a los criterios de búsqueda.

$( "#idComponente" ).rup_table( "highlightMatchedRowsInPage" );

• highlightMatchedRow($row): Resalta como ocurrencia de la búsqueda la línea especificada.

o $row: Objeto jQuery que referencia la línea de la tabla que se quiere resaltar.

$( "#idComponente" ).rup_table( "highlightMatchedRow", $( "#idRow" ));

• updateSearchPagination(): Actualiza los valores de la navegación entre registros.

$( "#idComponente" ).rup_table( "updateSearchPagination" );

• getSearchCurrentRowCount(selectedRowId): Devuelve, para una linea determinada, la posición en que se encuentra dentro del total de registros que se ajustan a los criterios de búsqueda

o selectedRowId: Identificador del registro.

$( "#idComponente" ).rup_table( "getSearchCurrentRowCount", "05" );


6.13. Toolbar

Genera una botonera asociada a la tabla con la finalidad de agrupar los controles que permiten realizar acciones sobre los registros de la misma.


El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “toolbar”. La configuración del plugin se especifica en la propiedad toolbar.


url: "../jqGridUsuario" , usePlugins:[ "toolbar" ], toolbar:{ // Propiedades de configuración del plugin toolbar }

});

6.13.2. Propiedades

• id : En caso de que se vaya a utilizar un identificador diferente al esperado por defecto, se deberá de indicar mediante esta propiedad.

• createDefaultToolButtons : Determina (true/false) si se deben visualizar los botones correspondientes a las operaciones por defecto del componente.

• showOperations : Permite indicar que operaciones definidas de manera global van a ser mostradas como botones. Cada operación puede tomar uno de los siguientes valores:

o true: Valor por defecto. Se mostrará la operación como opción en la botonera.

o false: La operación no se mostrará como opción en la botonera.

• buttons : Permite definir nuevos botones que se mostrarán en la toolbar. Los nuevos botones se especificarán del mismo modo que se describe en el componente rup_toolbar.

6.13.3. Ejemplo de uso

A continuación se va a mostrar un ejemplo de definición de un caso complejo de las opciones del toolbar:

$( "#idComponente" ).rup_table({ usePlugins:[ "toolbar" ], core:{ operations:{ "operacion1" : { name: "Operación 1" , icon: "rup-icon rup-icon-new" , enabled: function (){ return true ; }, callback: function (key, options){


alert( "Operación 1" ); } }, "operacion2" : { name: "Operación 2" , icon: "rup-icon rup-icon-new" , enabled: function (){ return true ; }, callback: function (key, options){ alert( "Operación 1" ); } } } }, toolbar:{ showOperations:{ operacion2: false }, buttons:[ {i18nCaption: "cancelar" , css: "cancelar" , click: function (){}}, {i18nCaption: "buscar" , css: "buscar" , click: function (){}} ] }

});

A partir del código anterior se genera lo siguiente:

• Dos operaciones globales (operacion1 y operacion2 ) que serán utilizadas por la toolbar y el menú contextual entre otros.

• Se definen mediante la propiedad buttons, otras dos opciones extra a ser mostradas como opciones en la botonera. Estas opciones serían las identificadas por cancelar y buscar .

buttons:[

{i18nCaption: "cancelar" , css: "cancelar" , click: function (){}}, {i18nCaption: "buscar" , css: "buscar" , click: function (){}}

]

• Se especifica que la operacion2 no será mostrada en la botonera.

showOperations:{

operacion2: false },

6.14. Reporting

Genera los controles necesarios para permitir al usuario la exportación de los datos mostrados en la tabla.



El uso del plugin en el componente se realiza incluyendo en el array de la propiedad usePlugins el valor “report”. La configuración del plugin se especifica en la propiedad toolbar.


url: "../jqGridUsuario" , usePlugins:[ "report" ], report:{ // Propiedades de configuración del plugin report }

});

6.14.2. Propiedades

• columns : Permite especificar mediante un array, los identificadores de las columnas que van a ser mostradas en el informe.

• buttons : Esta propiedad permite especificar los controles mediante los cuales se van a exportar los datos en los diferentes formatos.


url: "../jqGridUsuario" , usePlugins:[ "report" ], report:{ buttons:[ {id: "reports" , i18nCaption: "Informes" , right: true , buttons:[ { i18nCaption: "CSV" , css: "csv" , url: "../jqGridUsuario/csvReport" }, { i18nCaption: "XLS" , css: "xls" , url: "../jqGridUsuario/xlsReport"


}, { i18nCaption: "XLXS" , css: "xls" , url: "../jqGridUsuario/xlsxReport" }, { i18nCaption: "ODS" , css: "ods" , url: "../jqGridUsuario/odsReport" }, { i18nCaption: "PDF" , css: "pdf" , url: "../jqGridUsuario/pdfReport" }, { i18nCaption: "PDF_inLine" , css: "pdf" , url: "../jqGridUsuario/pdfReport" , isInline: true } ]} ] }

});

La configuración avanzada se detalla en la guía de uso del patrón Report, así como la implementación necesaria en el lado de servidor.

6.14.3. Eventos

• rupTable_serializeReportData : Permite asociar un manejador al evento que se produce en el momento en el que se construye el objeto que se envía al servidor para solicitar la generación del informe. Permite la modificación del objeto postData para añadir, modificar o eliminar los parámetros que van a ser enviados.

$( "#idComponente" ).on( "rupTable_serializeReportData" , function (event, postData){ });

7. Sobreescritura del theme

El componente tabla se presenta con una apariencia visual definida en el fichero de estilos theme.rup.table-x.y.z.css.

Si se quiere modificar la apariencia del componente, se recomienda redefinir el/los estilos necesarios en un fichero de estilos propio de la aplicación situado dentro del proyecto de estáticos (codAppStatics/WebContent/codApp/styles).

Los estilos del componente se basan en los estilos básicos de los widgets de jQuery UI, con lo que los cambios que se realicen sobre su fichero de estilos manualmente o mediante el uso de la herramienta Theme Roller podrán tener repercusión sobre todos los componentes que compartan esos mismos estilos (pudiendo ser el nivel de repercusión general o ajustado a un subconjunto de componentes).


8. Internacionalización (i18n)

La gestión de los literales de la tabla se realiza a través de ficheros json lo que flexibiliza el desarrollo. Para acceder a los literales se hará uso del objeto base RUP, mediante éste se accederá al objeto json correspondiente según el idioma obteniendo tanto los literales como los propios mensajes.

Los literales definidos para el contenido de la tabla son texto simple. Para este componente los literales utilizados están en la parte global de la internacionalización dentro de los resources de rup.

El objeto de internacionalización de la tabla se encuentra accesible del siguiente modo:

$.rup.i18n.base.rup_table

9. Integración con UDA

La interacción entre la capa de presentación y el servidor de aplicaciones que requiere el componente, hace uso de una serie de clases y configuraciones para facilitar su gestión.

El componente ha sido implementado de manera que sea fácilmente extensible mediante plugins. Debido a esto es posible dotar al componente de funcionalidades extra que se ajusten a las necesidades de nuestra aplicación. Dependiendo del tipo de nueva funcionalidad que se necesite es muy posible que la información que se transfiera se incremente. Para facilitar este proceso y flexibilizar el proceso de extensibilidad del componente se ha implementado una serie de componentes que se presupondrá que son utilizadas a la hora de explicar su funcionamiento.

9.1. Comunicación con la capa servidor

La comunicación entre el componente y la capa servidor se realiza principalmente mediante en envío y recepción de objetos JSON.

Para facilitar los procesos de serialización y deserialización entre los objetos JSON y Java se proporcionan las siguientes clases Java:

• com.ejie.x38.dto.JQGridRequestDto : Clase encargada de almacenar la información del JSON enviado por el componente. Después del proceso de deserialización este será el objeto resultante que se obtendrá a partir del objeto JSON enviado.

• com.ejie.x38.dto.JQGridResponseDto : Clase encargada de almacenar las propiedades que después del proceso de serialización, se convertirán en propiedades del objeto JSON que deberá de ser enviado al componente.


9.2. Configuración de Spring

Es necesario incluir la siguiente configuración en los ficheros de configuración de Spring:

En el fichero mvc-config.xml se deberá de especificar el uso de un Argument Resolver para gestión

[mvc-config.xml]

<bean id ="requestMappingHandlerAdapter" class ="org.springframework.web.servlet.mvc.method.annotat ion.RequestMappingHandlerAdapter" >

 <property name="customArgumentResolvers">

<list > <bean class ="com.ejie.x38.control.view.RequestFormEntityMethodArgumentResolver"/>

</ list > </ property >

</ bean >

9.3. Métodos controller

Estos son los métodos generados en el Controller para gestionar las peticiones de las diferentes operaciones del componente table:

• Filtrado @RequestMapping (value = "/filter" , method = RequestMethod. POST) public @ResponseBody JQGridResponseDto<Usuario> filter( @RequestJsonBody (param= "filter" ) Usuario filterUsuario, @RequestJsonBody JQGridRequestDto jqGridRequestDto) { JQGridUsuarioController. logger .info( "[POST - jqGrid] : Obtener Usuarios" ); return jqGridUsuarioService .filter(filterUsuario, jqGridRequestDto, false ); }

• Búsqueda

@RequestMapping (value = "/search" , method = RequestMethod. POST) public @ResponseBody List<TableRowDto<Usuario>> search( @RequestJsonBody (param= "filter" ) Usuario filterUsuario, @RequestJsonBody (param= "search" ) Usuario searchUsuario, @RequestJsonBody JQGridRequestDto jqGridRequestDto){ JQGridUsuarioController. logger .info( "[POST - search] : Buscar Usuarios" ); return jqGridUsuarioService .search(filterUsuario, searchUsuario, jqGridRequest Dto, false ); }

• Borrado múltiple


@RequestMapping (value = "/deleteAll" , method = RequestMethod. POST) @ResponseStatus (value=HttpStatus. OK) public @ResponseBody List<String> removeMultiple( @RequestJsonBody (param= "filter" ) Usuario filterUsuario, @RequestJsonBody JQGridRequestDto jqGridRequestDto) { JQGridUsuarioController. logger .info( "[POST - removeMultiple] : Eliminar multiples usuarios" ); this . jqGridUsuarioService .removeMultiple(filterUsuario, jqGridRequestDto, false ); JQGridUsuarioController. logger .info( "All entities correctly deleted!" ); return jqGridRequestDto.getMultiselection().getSelectedId s(); }

• Filtrado jerarquía @RequestMapping (value = "/jerarquia/filter" , method = RequestMethod. POST) public @ResponseBody JQGridResponseDto< JerarquiaDto< Usuario>> jerarqu ia( @RequestJsonBody (param= "filter" ) Usuario filterUsuario, @RequestJsonBody JQGridRequestDto jqGridRequestDto) { JQGridUsuarioController. logger .info( "[POST - jerarquia] : Obtener Usuarios Jerarquia" ); return this . jqGridUsuarioService .jerarquia(filterUsuario, jqGridRequestDto, false ); }

• Obtención hijos jerarquía @RequestMapping (value = "/jerarquiaChildren" , method = RequestMethod. POST) public @ResponseBody JQGridResponseDto<JerarquiaDto<Usuario>> jerarquia Children ( @RequestJsonBody (param= "filter" ) Usuario filterUsuario, @RequestJsonBody JQGridRequestDto jqGridRequestDto){ JQGridUsuarioController. logger .info( "[GET - jqGrid] : Obtener Jerarquia - Hijos" ); return this . jqGridUsuarioService .jerarquiaChildren(filterUsuario, jqGridRequestDto); }

Technology

UDA-Componentes RUP. Tabla.v2.4.6