uda-componentes rup. mantenimiento (v2.1.1 deprecado)

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

Componentes RUP – Mantenimiento

Fecha: 09/01/2013 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 – Mantenimiento ii/33

Control de documentación

Título de documento: Componentes RUP – Mantenimiento

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.

Añadida la propiedad de configuración showMultiselectAlerts.

1.1.1 30/09/2011 Añadidos los métodos públicos getMode, isEditing, isAdding

1.2.0 14/12/2011 Añadidos ejemplos de uso de otros componentes RUP en el formulario de detalle.

1.2.1 21/02/2012

Upload de ficheros en el formulario de detalle.

Gestión de botones por defecto y añadido de nuevos.

Nuevos métodos públicos, que devuelven las funcionalidades de los botones por defecto.

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.1.1 09/01/2013 Nuevo método getSerializedForm

Nueva propiedad lazyLoadDetailForm,

Componentes RUP – Mantenimiento iii/33

filterExclude.

Nuevo evento onAfterLazyDetailLoad.

Cambios producidos desde la última versión

Nuevo método getSerializedForm

Nuevas propiedades lazyLoadDetailForm, filterExclude.

Nuevo evento onAfterLazyDetailLoad.

Control de difusión

Responsable: Ander Martínez

Aprobado por:

Firma: Fecha:

Distribución:

Referencias de archivo

Autor:

Nombre archivo:

Localización:

Componentes RUP – Mantenimiento iv/33

Contenido

Capítulo/sección Página

1. Introducción 6

2. Ejemplo 6

3. Casos de uso 6

4. Infraestructura 7

4.1. Ficheros 7

4.2. Dependencias 7

5. Definición del componente 8

5.1. Propiedades 8

5.2. Métodos 11

5.3. Eventos 12

6. Funcionalidades 13

6.1. Creación automática del formulario de detalle 13

6.2. Añade los botones del formulario de detalle 14

6.3. Añade el área de paginación al formulario de detalle 15

6.4. Añade los botones del formulario de búsqueda 15

6.5. Creación de la botonera y adición de los botones por defecto 16

6.6. Obtener los datos del servidor para recargar el formulario de detalle 16

6.7. Posibilidad de crear mantenimientos con multiselección 16

6.8. Edición en línea 17

6.9. Validaciones automáticas 18

6.10. Mantenimientos maestro detalle 19

7. Sobreescritura del theme 22

8. Internacionalización (i18n) 23

Componentes RUP – Mantenimiento v/33

9. Integración con UDA 24

9.1. Upload de ficheros 26

10. Interacción con otros componentes RUP 30

Componentes RUP – Mantenimiento 6/33

1. Introducción

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

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 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.maint-x.y.z.js

Ruta theme: rup/basic-theme/

Fichero de estilos: theme.maint-x.y.z.css

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

4.2. Dependencias

El desarrollo de los componentes 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 componentes como con algunos plugins basados en jQuery.

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

La gestión de ciertas partes visuales de los componentes, 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

• jquery-ui-1.8.23.custom.css

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

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

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

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


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

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

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

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

5. Definición del componente

5.1. Propiedades

Para poder definir un mantenimiento se deberán rellenar las siguientes propiedades del componente adecuando el mantenimiento a sus necesidades de implementación:

• jQueryGrid: Referencia al grid donde se mostrarán los datos en de forma tabular. Es el nombre del elemento HTML usado para crear el componente tabla.

• imgPath: (Por defecto RUP + "/basic-theme/images"). Ruta donde están las imágenes de la tabla.

• detailDiv: (Por defecto “null”). Id del campo del formulario de detalle.

• searchForm: (Por defecto “null”) Id del campo del formulario de búsquedas.

• fluid: (Por defecto “true”). Determina si el mantenimiento va a mostrar un diseño líquido, es decir, si va a redimensionarse dependiendo del tamaño de la capa padre que lo contiene.

• fluidOffset : (Por defecto “20”). Determina el desplazamiento de anchura que realiza el mantenimiento respecto del ancho total.

• detailForm: (Por defecto “null”) Id del campo del formulario de detalle. Si no se modifica, el mantenimiento generará de forma automática el formulario de detalle.

• showFeedback : Indica si se mostrarán los mensajes sobre las acciones realizadas.

• filterExclude : Permite indicar mediante un array de strings, los identificadores de los campos del formulario que deben excluirse del resumen mostrado al ocultarlo. Ejemplo de uso:

filterExclude: [ "nombre_search" , "apellido1_search" ]

• feedback: Id de la capa donde se mostrarán los mensajes generados por el mantenimiento.

• lazyLoadDetailForm : Determina si la creación e inicialización del formulario de detalle debe demorase hasta el momento en el que sea requerido su uso. Valor por defecto, false.

• loadOnStartUp : Indica si se cargará la tabla a la hora de arrancar la página.

• primaryKey: Clave primaria del mantenimiento

• showMessages: (Por defecto “false”). Indica si se van a mostrar los mensajes de OK si las acciones de añadir, modificar o borrar se han realizado con éxito.


• validationMode: (Por defecto "individual"). Validación de los campos del formulario de forma individual a la hora de perder el foco. También puede ser por formulario (valor “form”).

• modelObject: Esta propiedad indica sobre qué entidad se realizán las operaciones CRUD (create, read, update, delete).

• detailButtons: (Por defecto $.rup.maint.detailButtons.SAVE_REPEAT) Propiedad que indica la tipología de botones que se crearán en el formulario de detalle. Sus posibles valores son:

$.rup.maint.detailButtons.SAVE_REPEAT: Se crearán tres botones, el de guardar (realiza la acción de guardar y cierra el diálogo del detalle), el de guardar y repetir (que realiza la acción de guardar pero no cierra el diálogo de detalle) y el de cancelar (que cierra el diálogo de detalle siempre y cuando no se hayan realizado cambios en el formulario).

$.rup.maint.detailButtons.SAVE: Se crearán dos botones, el de guardar (realiza la acción de guardar y cierra el diálogo del detalle y el de cancelar (que cierra el diálogo de detalle siempre y cuando no se hayan realizado cambios en el formulario).

• rupCheckStyle : (Por defecto “true”) Indica si se mostrarán no conformidades de estilo por defecto.

• detailServer : (Por defecto “true”) Indica si el mantenimiento accederá al servidor para obtener los datos a mostrar en el detalle. Se usará la propiedad primaryKey para acceder a la entidad.

• parent : (Por defecto “null”) Esta propiedad indica cuál es el mantenimiento padre. Se indicará el id del mantenimiento y cuando el padre cambie el mantenimiento hijo se refrescará automáticamente.

• showMultiselectAlerts : (Por defecto “true”) En el caso de un mantenimiento multiselección, determina si se muestran al usuario los avisos de la pérdida de la selección de elementos al realizar ciertas operaciones. Por ejemplo, en el caso de realizar una ordenación de los registros por el contenido de una columna del mantenimiento, se mostrará un mensaje de confirmación de la acción indicando de que se va a perder la selección de elementos actual.

• toolbar : Estructura compuesta que alberga toda la configuración asociada al componente toolbar (botonera) del mantenimiento. Los distintos parámetros que se pueden especificar dentro de la estructura, son los siguientes:

toolbar:{

id: (Por defecto indefinido) Id especifico de una toolbar externa, que contendrá los botones, tanto los de por defecto como los adicionales, del mantenimiento.

autoAjustToolbar: (Por defecto “true”) Indica si se va a ajustar el tamaño de la toolbar al tamaño de la tabla.

createDefaultToolButtons: (Por defecto “true”) Indica si se va a crear algún botón por defecto en la toolbar, bien sea una creada por el desarrollador o bien la generada automáticamente por el componente.

defaultAdd: (Por defecto “true”) Según el tipo de mantenimiento sobre el que se pueda aplicar, indica la creación, por defecto, del botón add (añadir) .

defaultEdit: (Por defecto “true”) Según el tipo de mantenimiento sobre el que se pueda aplicar, indica la creación, por defecto, del botón edit (editar).


defaultCancel: (Por defecto “true”) Según el tipo de mantenimiento sobre el que se pueda aplicar, indica la creación, por defecto, del botón cancel (cancelar).

defaultDelete: (Por defecto “true”) Según el tipo de mantenimiento sobre el que se pueda aplicar, indica la creación, por defecto, del botón delete (eliminar).

defaultFilter: (Por defecto “true”) Según el tipo de mantenimiento sobre el que se pueda aplicar, indica la creación, por defecto, del botón filter (filtrar).

newButtons: (Por defecto indefinido) Estructura compuesta que permite definir los nuevos botones que se incorporan a la toolbar del mantenimiento.

newButtons: [{

obj: {

i18nCaption: Texto que mostrará el botón,

css: Estilo a aplicar. Se utilizará para mostrar imágenes a la izquierda del botón.

},

json_i18n: Indica el identificador del objeto json para la resolución de los literales del componente,

click: Función javascript que se ejecutará cuando se pulse el botón.

},{

. . . }]

Un ejemplo de uso, de la estructura toolbar en la definición de un mantenimiento, podría ser el siguiente:

toolbar: { //No creamos el botón de filtro por defecto defaultFilter: false, newButtons: [{

obj: { i18nCaption: "actualizar" , css: "rup-maint_filter"

}, json_i18n: $.rup.i18n.app.simpelMaint, click: function(){

$( "#simple" ).rup_maint( "getFilterBootonDefaultFunction" ).call(); }

} ] }

• validation : Propiedad que recibe la configuración de las reglas de validación que van a ser aplicadas a los campos del formulario de detalle.

• validationFilter : (Por defecto ”true”). Determina si se mantienen las cabeceras de compatibilidad para el componente de validación posterior a la v2.0.0 de UDA.

• validationUrl : (Por defecto ‘$.rup.CTX_PATH+"validate"’). Contiene la url que va a utilizar el componente de validación en servidor.


5.2. Métodos

Como se puede ver en el ejemplo anterior, el API a utilizar para realizar las invocaciones a los métodos públicos de los que dispone el componente es:

$( "#maint" ).rup_maint( "newElement" );

$(selector).rup_maint (método, [parámetros]);

Se ha seguido el mismo formato que usa jQuery UI: el primer parámetro es el método que se quiere invocar y el resto de parámetros, la parametrización que recibe el método.

Los métodos públicos a disposición del desarrollador para ser invocados son los siguientes:

• newElement: Muestra el formulario de adición y pone el mantenimiento en modo alta.

• editElement : (id, noChangeMode) Edita la fila que recibe como parámetro. Si recibe como segundo parámetro un true no realizará el cambio de modo a edit.

• deleteElement: (id) Elimina la fila del id que recibe como parámetro.

• toggleSearchForm : (capa, filterCriteriaLoad). Apertura/Cierre del formulario de búsqueda. El parámetro capa determina el identificador del div que se va a mostrar/ocultar. El parámetro filterCriteriaLoad (true/false) determina si se deben tener en cuenta los valores precargados en los campos del formulario de búsqueda.

• search : Lanza la búsqueda del mantenimiento obteniendo los datos del formulario de búsqueda.

• toggleGrid : Oculta o muestra la tabla de resultados junto con la paginación.

• cleanSearchForm: Limpia el formulario de búsqueda y dependiendo la propiedad del mantenimiento loadOnStartUp relanzará la carga de la tabla o la limpieza del mismo.

• saveMaint (saveAndRepeat): Realiza el guardado del mantenimiento, bien realizando un alta o bien modificando el registro actual, todo ello haciendo uso del modo del mismo.

• getPrimaryKey : Obtiene la clave primaria del mantenimiento.

• getMode : Devuelve el modo en el que está actuando el mantenimiento sobre los registros:

o edit: En caso de estar modificando el registro.

o new: En caso de estar insertando un nuevo registro.

• isEditing : Retorna true o false, dependiendo si el mantenimiento está en modo edición o no.

• isAdding : Retorna true o false, dependiendo si el mantenimiento está en modo inserción o no.


• getToolbarObject : Devuelve el objeto (objeto JQuery) que alberga la toolbar del mantenimiento.

• getAddBootonDefaultFunction : Devuelve la función, por defecto, que se ejecuta al presionar el botón add (añadir).

• getCancelBootonDefaultFunction : Devuelve la función, por defecto, que se ejecuta al presionar el botón cancel (cancelar).

• getEditBootonDefaultFunction : Devuelve la función, por defecto, que se ejecuta al presionar el botón edit (editar).

• getDeleteBootonDefaultFunction : Devuelve la función, por defecto, que se ejecuta al presionar el botón delete (borrar).

• getFilterBootonDefaultFunction : Devuelve la función, por defecto, que se ejecuta al presionar el botón filter (filtrar).

• getSerializedForm : Devuelve la serialización del formulario pasado como parámetro.

5.3. Eventos

A continuación se detallan los eventos expuestos a los desarrolladores mediante los que podrán extender las funcionalidades del mantenimiento para adecuarlo a las necesidades particulares de cada aplicación:

• onbeforeDetailShow : Evento que se lanza antes de enseñar el formulario de edición.

• onafterDetailShow : Evento que se lanza después de mostrar el formulario de edición y de que el componente haya realizado todas sus acciones.

• ondblClickRow (rowid, iRow, iCol, e): Evento que se lanza después de realizar un doble click sobre una fila de la tabla de resultados. La función asociada al evento se ejecuta previamente a la función propia del componente. En caso de que se desee evitar la ejecución del evento por defecto del componente, la función deberá realizar un return false.

o rowid: Identificador de la fila.

o iRow: Index de la fila.

o iCol: Index de la columna.

o e: Objeto evento.

• onAfterLazyDetailLoad : Evento que se lanza en el momento en que se requiere de la creación del formulario de detalle para ser utilizado. El evento únicamente se lanza en el caso de que se haga uso de la opción de configuración lazyLoadDetailForm. En la función de callback asociada al capturador del evento, se puede incluir el código javascript utilizado para inicializar los componentes existentes en el fomulario de detalle.


6. Funcionalidades

A continuación se detallan las funcionalidades que aporta el componente mantenimiento de forma genérica sin que el desarrollador tenga que desarrollar ningún código, solo parametrizando las propiedades del componente.

6.1. Creación automática del formulario de detalle

Como se ha comentado anteriormente en el apartado de descripción de las propiedades del componente mantenimiento, haciendo uso de la propiedad “detailForm” puede crearse el formulario de forma automática sin que el desarrollador tenga que dibujar los controles en la jsp el propio mantenimiento se encargará de dibujar los controles en el formulario haciendo uso de las propiedades establecidas en la configuración de la tabla, más concretamente en las propiedades del colModel. A continuación se detallan cuales son las propiedades que se usan para crear ese formulario de forma dinámica:

• editable : Propiedad para indicar al mantenimiento que la columna deberá crearse en el formulario de detalle. Si se especifica un valor false, no se mostrará la columna en el detalle.

• edittype : Propiedad que determina el tipo de control a crear en el detalle, si no se establece esta propiedad se creará un input. Los posibles valores son:

o text: Construye un campo de texto

o textarea: Construye un textarea

o select: Construye una combo

o checkbox: Construye un check

o password: Construye un campo para introducir claves

o button: Introduce un botón


o image: Introduce una imagen

o file: Introduce un campo de tipo fichero

o hidden: Introduce un campo de tipo hidden

• rupType : Esta propiedad es un añadido a las propiedades de una columna de la tabla donde indicamos el tipo de componente que se creará sobre ese elemento. Es decir, si rupType es “datepicker” el mantenimiento creará un rup_date sobre ese campo haciendo uso de las editRules que más abajo se especifican.

• hidden : Esta propiedad indica si se mostrará o no la columna en la tabla.

• editOptions : Array de propiedades relacionadas con el tipo (edittype) que se establezca para esa columna, es decir, contiene información acerca de la colmuna que se va a editar. Este array es importante que contenga propiedades validas para el tipo (edittype) seleccionado.

Por ejemplo, si se establece una columna de tipo text los valores de esta propiedad podrían ser todos los valores posibles de un input: size, maxlength… Si fuera necesario que un campo del formulario de detalle fuera visible pero no modificable se podría incluir la propiedad readonly:’readonly’.

• editRules : Array de propiedades para la validación de campos que se crearán en el detalle por ejemplo:

o required: Si esta propiedad es true se indica que ese campo es obligatorio.

o validate: Si el valor de esta propiedad es true indica que ese campo se validará a la hora de salir del mismo (en el onchange) si la propiedad general del mantenimiento “validationMode ” contiene su valor por defecto.

• formoptions : Conjunto de propiedades de las que solo se usa el “label” para poder establecer el label asociado a cada control creado en el detalle. En caso de que no se establezca esta propiedad se usará el colName del índice actual del colModel.

{name: 'status' , index: 'status' , width: '10%' , align: 'left' , editable: true, formoptions: {label: 'Estado' }, editRules: {required: true, validate: true}, editoptions: {size: 10, value: { 'N' : 'Pendiente' , 'S' : 'Enviado' }}, edittype: 'select' },

6.2. Añade los botones del formulario de detalle

Otra de las funcionalidades del componente es que, ya se cree el formulario de detalle de forma automática o bien lo defina el desarrollador, el componente insertará los botones por defecto definidos para él. Por lo que los desarrolladores no tendrán que pintar los botones básicos, solo indicando en la propiedad “detailButtons” el tipo de botonera quiere usar el componente lo añadirá.


6.3. Añade el área de paginación al formulario de d etalle

Además de añadir los botones de acción del detalle, el componente también añade los botones de paginación del detalle junto con el número de elementos seleccionados o por los que se va a paginar con la intención de facilitar la navegación entre registros. Este es otro elemento que los desarrolladores no tendrán que crear incluso cuando utilicen su propio formulario de detalle. La activación y desactivación de los botones es automática junto con el incremento de la paginación de elementos.

En los mantenimientos de tipo multiselección, la navegación se realizará sobre todos los elementos seleccionados ya sean de la página actual o de otras páginas.

En los mantenimientos donde no exista la selección de elementos, la paginación se realizará por todos los elementos de los que disponga la tabla. Es decir, cuando se llegue al fin de la página actual de la tabla paginará de forma automática para poder obtener el primer registro de la página siguiente.

6.4. Añade los botones del formulario de búsqueda

El formulario de búsqueda del mantenimiento es diseñado por los desarrolladores añadiendo los controles por lo que quieran realizar el filtrado, pero será el propio componente mantenimiento el encargado tanto de crear los botones de acción como de realizar la búsqueda enviando los valores del formulario al servidor para posteriormente realizar la carga de la tabla con los criterios seleccionados.

Estos botones de acción que se crean son:

• Botón de buscar : Obtiene los valores del formulario de búsqueda y los envía al servidor para poder realizar la carga de la tabla con los datos filtrados por los criterios introducidos.

• Botón de limpiar : Limpia los valores del formulario y de búsqueda borrando en la tabla y en caso de que éste tenga la propiedad loadOnStartUp con valor true relanzará la carga de la tabla sin criterio alguno.

También ofrece la posibilidad de colapsar el formulario de búsqueda añadiendo los criterios de búsqueda establecidos junto al texto “Criterios de búsqueda”


6.5. Creación de la botonera y adición de los boton es por defecto

El propio desarrollador puede crear una botonera personal y después asociársela al componente mediante la propiedad toolbar, comentada en el punto de descripción de las propiedades parametrizables del componente. Una vez asociada la botonera, el componente es capaz de añadirle los botones establecidos por defecto, siempre y cuando la propiedad createDefaultToolButtons esté a true; en caso contrario el mantenimiento no los añadirá. Los botones por defecto son los siguientes:

• Nuevo: La acción de nuevo registro muestra el diálogo de detalle preparado para poder dar de alta un nuevo registro en la entidad activando el modo en ALTA y lanzando los eventos de muestra del detalle. Internamente invoca al método newElement del componente.

• Editar: La acción de editar permite la edición del registro de la entidad seleccionada en la tabla mostrando el diálogo de detalle y cargando en los controles del mismo los valores correspondientes de dos formas posibles:

o Usando los valores existentes en la tabla; en este caso la propiedad detailServer estará a false.

o Accediendo al servidor para obtener los datos necesarios para completar el detalle; en este caso la propiedad detailServer estará a true.

• Borrar: La acción de borrar realiza el borrado de todos los elementos seleccionados mostrando siempre un mensaje de confirmación antes de realizar el borrado para que el usuario confirme la acción de borrar los registros. El propio componente distingue qué servicio REST invocar si la tabla es multiselección (servicio deleteAll) o no (servicio delete).

• Filtrar: La acción de filtrar realiza el toggle del formulario de búsqueda (lo oculta o colapsa) añadiendo al título del fieldset (Criterios de búsqueda) los criterios por los que se quiere filtrar.

6.6. Obtener los datos del servidor para recargar e l formulario de detalle

Como se ha mencionado anteriormente el mantenimiento a la hora de editar los registros seleccionados puede ir al servidor a obtener la entidad completa y mostrarla en formulario de detalle. Esta funcionalidad se realiza a través de la propiedad detailServer la cual en los mantenimientos que no son de selección múltiple se puede activar o desactivar para obtener o no la entidad del servidor. Pero en los casos en los que la tabla es de tipo multiselección, el componente mantenimiento accederá siempre al servidor a obtener los datos completos de la entidad.

6.7. Posibilidad de crear mantenimientos con multis elección

La creación de mantenimientos de tipo multiselección es otra de las posibilidades que ofrece el componente mantenimiento basándose en el componente tabla. Esta funcionalidad implica ciertos comportamientos específicos:

• A la hora de editar un mantenimiento multiselección, el componente es capaz de navegar solo por los registros seleccionados en el diálogo de detalle.


• A la hora de realizar un borrado, se eliminan todos los elementos seleccionados, tanto los de la página actual como los de otras páginas donde se hayan seleccionado registros.

Para poder realizar estas acciones el componente guarda una estructura arbórea con los registros seleccionados de cada página junto con sus claves primarias para poder realizar las acciones de una forma más rápida, ya que todas las acciones se realizan siempre a través de ellas.

También se ha tenido en cuenta la posibilidad de que el usuario seleccione todos los registros de la página actual con un único check situado en la cabecera de la columna de los check. A la hora de seleccionar este selectAll se muestra un aviso informando al usuario que sólo se seleccionarán los registros de la página actual.

Unido a esto último, al seleccionar todos los registros de la página mediante el check, aparecerá un mensaje que permitirá al usuario seleccionar el conjunto completo de registros de la entidad con la que se está trabajando, es decir, todos los registros que cumplan los criterios de búsqueda independientemente de la página en la que se encuentren.

6.8. Edición en línea

Otra de las funcionalidades que ofrece el mantenimiento es la posibilidad de editar los registros en la propia tabla sin necesidad de usar un formulario ni diálogo de detalle. Los datos que necesita el mantenimiento son los mismos que cuando se usa para la creación del detalle (descritos anteriormente). Además de esas propiedades se debe activar la propiedad editable. Las acciones que realizará el mantenimiento son las mismas que con un formulario de detalle incluyendo la posibilidad de usar los eventos específicos del componente tabla para poder realizar acciones especificas en ellos. Para más información, consultar los eventos del documento del componente tabla.


6.9. Validaciones automáticas

Como ya se ha comentado en puntos anteriores, el mantenimiento por defecto realiza la validación del formulario a la hora de guardar los datos del detalle, ya sea alta o modificación de un registro. Estas validaciones se realizan en el servidor. Es decir, las validaciones están implementadas en el modelo no en el cliente, y se realizan a través de anotaciones en las propiedades de la entidad (para más información sobre las anotaciones véase la Guía de Desarrollo de UDA).

Además de las validaciones globales del formulario, el mantenimiento puede realizar validaciones individuales si los desarrolladores lo necesitan. Estas validaciones individuales se realizan exactamente como las validaciones globales de formulario, contra la entidad, pero la petición se realiza en el cambio de campo y pérdida de foco (evento onchange) y contra un servlet de x38 encargado de realizar la validación.

Para aplicar las validaciones a los campos se puede realizar de dos formas dependiendo de cómo se parametrice el mantenimiento:

• Si el mantenimiento se crea con el formulario automático, hay que añadir en cada columna que quiera que se valide de forma individual una propiedad validate con valor true dentro del conjunto de propiedades editRules.


editRules: {required: true, validate: true}

• En el caso de que el desarrollador genere el formulario de detalle tendrá que añadir el valor validableElem en el class cada campo que quiera validar de forma individual.

class ="formulario_linea_input validableElem"

Si alguna validación falla, el mantenimiento se encarga de mostrarla en el área de feedback del formulario del detalle informando del error ocurrido.

6.10. Mantenimientos maestro detalle

Otra funcionalidad que permite el mantenimiento es modelar la relación maestro detalle entre dos entidades relacionadas. La relación se establece mediante la propiedad parent del mantenimiento (como se ha explicado en el apartado de las propiedades) indicando que el proceso superior es el padre del mantenimiento inferior enlazando las acciones del padre con las del hijo y viceversa (interactuando con el gestor de cambios, recarga de la tabla, etcétera).

La forma de realizar este tipo de mantenimientos es la siguiente:

Se declaran los dos mantenimientos de forma separada y la propiedad parent del mantenimiento detalle se informa con el identificador del mantenimiento maestro.

$( "#comarca" ).rup_maint({ jQueryGrid: "GRID_comarca" , primaryKey: "code" , modelObject: "Comarca" , detailButtons: $.rup.maint.detailButtons.SAVE, searchForm: "searchForm" , showMessages: true


}); $( "#localidad" ).rup_maint({ jQueryGrid: "GRID_localidad" , primaryKey: "code;comarca.codeComarca" , modelObject: "Localidad" , detailButtons: $.rup.maint.detailButtons.SAVE, searchForm: "searchFormDetalle" , showMessages: true, parent:"comarca"

});


7. Sobreescritura del theme

Los estilos que se pueden sobrescribir en este componente son escasos ya que fundamentalmente es un componente que hace uso de otros componentes, pero aun así existen algunos estilos que se pueden sobrescribir para modificar su aspecto visual.

• Imágenes de los botones:

.rup-maint_new { background : #929292 url('images/rup.nuevo.png') no-repeat !important ; width : 14px ; } .rup-maint_edit { background : #929292 url("images/rup.editar.png") no-repeat !important ; width : 14px ; } .rup-maint_delete { background : #929292 url("images/rup.eliminar.png") no-repeat !important ; width : 14px ; } .rup-maint_filter { background : #929292 url("images/rup.filtrar.png") no-repeat !important ; width : 16px ; }

• Los links de la paginación de detalle:

.rup-maint_linkPaginacionDetalle {

background : none ; border : none ; clear : none ; cursor : pointer ; float : right ; text-decoration : underline ; color : #0052C7 ; font-size : 0.88em ; padding-right : 1.3em ;

}


8. Internacionalización (i18n)

La gestión de los literales 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 utilizados para este componente están en la parte global de la internacionalización dentro de los resources de rup. A continuación se muestran los literales necesarios:

"rup_maint": { "detailTitle":"Modificar registro", "deletedOK":"El elemento se ha borrado correctament e.", "insertOK":"El elemento se ha añadido correctamente .", "modifyOK":"El elemento se ha modificado correctame nte.", "insertError":"Error al insertar el elemento.", "validateError":"Se han producido los siguientes er rores: <br/>", "last":"Último", "first":"Primero", "next":"Siguiente", "previous":"Anterior", "elements":"Elementos", "element(s)":"Elemento(s)", "new":"Añadir", "edit":"Editar", "delete":"Eliminar", "filter":"Filtrar", "cancel":"Cancelar", "searchOptions":"Criterios de búsqueda:", "noGrid":"No es posible crear un mantenimiento sin un grid.", "numResult":"Número de resultados", "de":"de", "changes": "Control de cambios", "saveAndContinue": "Se perderán los cambios en los datos modificados, ¿desea continuar?", "checkSelectedElems": "Se van a deseleccionar los e lementos seleccionados, ¿desea continuar?", "checkAddedSelectedElems":"Los elementos añadidos e n la pagina actual van a ser deseleccionados, ¿desea continuar?", "selectAll": "Ha seleccionado todos los registros d e la página actual.", "selected": "Registros seleccionados.", "deleteAll": "¿Está seguro que desea eliminar todos los registros seleccionados?", "titleDelAll": "Eliminar los registros", "noReg":"Seleccione un registro.", "emptyChanges": "No se han realizado cambios.", "invalidRowId": "El identificador de la fila no es válido. No se puede completar la acción", "toolbarNewButtonError": "Error al crear un nuevo b otón. <br/>Las tres variables de todo nuevo botón deben estar informadas."

}

El acceso a cualquier tipo de literal se debe realizar de la siguiente forma (teniendo en cuenta que es un objeto json):

$.rup.i18n.rup_maint.#literal#


9. Integración con UDA

La obtención de los datos a visualizar en el mantenimiento se hace vía peticiones AJAX al servidor de aplicaciones, donde el controller correspondiente tratará la petición, obtendrá los datos y los devolverá para presentarlos en el formato que el componente necesita.

Un ejemplo sería la implementación del método getAll de un controller:

@RequestMapping(method = RequestMethod. GET, headers={"JQGridModel=true"}) public @ResponseBody JQGridJSONModel getAllJQGrid(

@ModelAttribute Alumno filterAlumno, @ModelAttribute Pagination pagination) {

List<Alumno> alumnos = this. alumnoService .findAll(filterAlumno, pagination); Long recordNum = this. alumnoService .findAllCount(filterAlumno); AlumnoController. logger .info( "[GET - jqGrid] : Obtener Alumnos" ); return new JQGridJSONModel(pagination, recordNum, alumnos);

} Para poder identificar que la petición AJAX proviene del componente mantenimiento se añade en la misma una cabecera con el siguiente aspecto

JQGridModel true

La ejecución del método del controller correspondiente se determina mediante dicha cabecera. Para identificarla, se define del siguiente modo en el mapeo del método. @RequestMapping(method = RequestMethod. GET, headers={"JQGridModel=true"})

UDA proporciona la clase com.ejie.x38.dto.Pagination en la librería de utilidades comunes para facilitar la transferencia de la información de la paginación desde el controller hasta las capas de negocio y de acceso a datos. Los valores de los atributos del objeto se obtendrán de los parámetros de paginación del componente que envía en la request.

Pagination pagination = new Pagination(); pagination.setPage(Long. valueOf (request.getParameter( "page" ))); pagination.setRows(Long. valueOf (request.getParameter( "rows" ))); pagination.setSort(request.getParameter( "sidx" )); pagination.setAscDsc(request.getParameter( "sord" )); Para facilitar la inicialización del objeto, se puede utilizar la anotación @ModelAttrbute de spring del siguente modo: public @ResponseBody JQGridJSONModel getAllJQGrid(

@ModelAttribute Alumno filterAlumno, @ModelAttribute Pagination pagination) {


Una vez se ha obtenido la información que se debe visualizar en el mantenimiento, el componente requiere que le sea enviado desde el servidor de aplicaciones una estructura json específica que contenga los datos necesarios. Este objeto json sigue la siguiente estructura:

{"page":"1", "rows":[{"id":"3","nombre":"BLSMASER","apellido1": "Beatriz",…}, {"id":"4","nombre":"BO00093L","apellido1":" Ana Isabel",…], "total":"168", "records":1671}

Donde cada una de las propiedades tiene el siguiente significado:

• page : Número de página en la que debe de posicionarse el componente.

• rows : Array que contiene un objeto json por cada uno de los registros que se muestran en el mantenimiento. Cada objeto json contiene por cada columna un par clave-valor que indica el nombre de la columna y el valor que se va a visualizar.

• total : Número total de páginas que debe de presentar el mantenimiento.

• records : Número total de registros que debe de presentar el mantenimiento.

Para facilitar la generación de esta estructura json, UDA proporciona la clase com.ejie.x38.dto.JQGridJSONModel . Esta clase dispone de los atributos correspondientes a las propiedades de los objetos json que requiere el componente. De este modo, se facilita la serialización del objeto en la estructura json adecuada. Un ejemplo de su uso sería el siguiente:

JQGridJSONModel data = new JQGridJSONModel(pagination, recordNum, alumnos);

El mantenimiento realiza las operaciones típicas sobre una entidad: Recuperar, Crear, Actualizar y Eliminar, (en inglés CRUD). Para ello, el componente hace uso de las operaciones http POST, GET, PUT y DELETE. Los métodos generados por UDA en el controller correspondientes a estas operaciones son los siguientes:

• Recuperar : Se generan dos métodos. El método getAll utilizado para realizar la búsqueda de registros en base a los parámetros de filtrado introducidos por el usuario.

@RequestMapping (method = RequestMethod. GET) public @ResponseBody List<Alumno> getAll( @ModelAttribute Alumno filterAlumno) { }

El método getById, recupera el elemento correspondiente al identificador indicado en la url mediante la que se realiza la petición.

@RequestMapping (value = "/{id}" , method = RequestMethod. GET) public @ResponseBody Usuario getById( @PathVariable String id) { }


• Crear : Para esta operación se genera el método add, que se encarga de realizar las llamadas oportunas a la capa de negocio para persistir la información enviada por POST.

@RequestMapping (method = RequestMethod. POST) public @ResponseBody Usuario add( @RequestBody Usuario usuario) { }

• Actualizar : La operación de modificación se realiza mediante el método edit, que se encarga de realizar las llamadas oportunas a la capa de negocio para persistir la información enviada mediante la operación PUT.

@RequestMapping (method = RequestMethod. PUT) public @ResponseBody Usuario edit( @RequestBody Usuario usuario,

HttpServletResponse response) { }

• Eliminar : En el caso del borrado de elementos, puede realizarse la eliminación de un único registro o el de varios de manera simultánea. El borrado individual se realiza mediante el método remove, que recibe mediante la operación http DELETE, el identificador del elemento que debe de eliminarse.

@RequestMapping (value = "/{id}" , method = RequestMethod. DELETE) public void remove( @PathVariable String id,

HttpServletResponse response) { }

En el caso de un borrado múltiple, el método removeMultiple recibirá por POST la lista de los identificadores de los elementos que se deben eliminar.

@RequestMapping (value = "/deleteAll" , method = RequestMethod. POST) public void removeMultiple( @RequestBody ArrayList<ArrayList<String>> usuarioIds, HttpServletResponse response) { }

9.1. Upload de ficheros

El componente mantenimiento permite incluir campos file en el formulario de detalle para realizar subida de ficheros.

El campo file puede ser incluido en el formulario de detalle de dos maneras diferentes: autogenerado, de acuerdo a la configuración realizada en el colModel del componente, o creando el input directamente en caso de proveer al mantenimiento de un formulario de detalle propio.

En el caso de que el formulario de detalle sea generado por el propio mantenimiento a partir de las propiedades de configuración del colModel se debería de indicar del siguiente modo:


colModel: [{

name: "imagenPerfil" , label: "imagenPerfil" , index: "imagenPerfil" , width: "150" , editable: true, edittype:"file" }]

Esta configuración generará el siguiente campo file:

<input id ="detailForm_perfilUsuario_imagenPerfil" class ="formulario_linea_input" type ="file" name="imagenPerfil"/ >

Este código html puede valer como ejemplo del que se debería de incluir en caso de utilizar un formulario de detalle propio.

Una vez creado el control file, el siguiente paso será realizar la configuración necesaria para gestionar correctamente la subida de ficheros. En primer lugar se debe comprobar que existe en la configuración de Spring (fichero mvc-config.xml) la siguiente definición:

<bean id ="multipartResolver" class ="com.ejie.x38.util.UdaMultipartResolver" > </ bean >

Esto permitirá a Spring gestionar los envíos de ficheros de tipo multipart/form-data. Desde UDA se proporciona una implementación de MultipartResolver para permitir el envío de peticiones multipart mediante el método http PUT.

Databinding

Al enviar la información en un formato diferente a json no entra en juego el componente Jackson para realizar el databinding ni el componente de validación de datos.

Para realizar el databinding de los parámetros enviados en la request entre los parámetros del método del controller deberemos indicar cuál va a ser el bean sobre el que se va a realizar el binding. Esto lo indicamos mediante la anotación @ModelAttribute que permite a Spring identificar el bean que va a utilizar para asignar a sus atributos los valores de los parámetros con el mismo nombre que han sido enviados en la request.

public @ResponseBody PerfilUsuario add( @ModelAttribute PerfilUsuario perfilUsuario, HttpServletResponse response) { }

El binding del fichero enviado se puede realizar de dos modos:


• Sobre una propiedad del bean:

Se mapea directamente el contenido del fichero sobre un atributo del bean del mismo nombre que el nombre del parámetro de la request en el que se envía el fichero. El atributo del bean debe ser de tipo byte[] .

public class PerfilUsuario implements java.io.Serializable { private byte[] imagenPerfil ;

// Resto de propiedades y metodos }

El parámetro enviado en la request debe tener el mismo nombre que la propiedad del bean:

Content-Disposition: form-data; name="imagenPerfil" ; filename="Invierno.jpg" Content-Type: image/jpeg

Para que Spring sea capaz de realizar correctamente la asignación del contenido del fichero en el parámetro del bean, se debe realizar la siguiente configuración en el controller:

@InitBinder protected void initBinder(HttpServletRequest request, ServletRequestDataBinder binder) throws ServletException {

// Binding para los tipos de datos byte[] binder.registerCustomEditor( byte[]. class,

new ByteArrayMultipartFileEditor());

// Binding para los tipos de datos Date binder.registerCustomEditor(Date. class, new

CustomDateEditor(DateTimeManager. getDateTimeFormat (LocaleContextHolder. getLocale ()), true));

}

Mediante este método anotado con @InitBinder realizaremos la configuración del binder. Esta configuración es necesaria para indicar el uso de la clase ByteArrayMultipartFileEditor al realizar el databinding de un fichero sobre una propiedad de tipo byte[] .

Del mismo modo, indicaremos una nueva entrada de configuración para que el binder sea capaz de gestionar correctamente la asociación de parámetros de la request sobre propiedades de tipo Date. Mediante esta configuración la asociación de los datos se realizará de acuerdo al formato de fecha correspondiente para el idioma actual.


• Sobre un parámetro del método del controller:

Se dispone de otra alternativa para realizar el databinding del fichero enviado al servidor. En este caso en vez de mapearse sobre un atributo del bean, se realiza sobre un parámetro del método del controller. La declaración del método del controller sería la siguiente:

@RequestMapping(method = RequestMethod. POST) public @ResponseBody PerfilUsuario edit( @ModelAttribute PerfilUsuario perfilUsuario, @RequestParam(value="imagenPerfil",required=false) MultipartFile

imagenPerfil) { }

La declaración del parámetro anotado mediante @RequestParam indicará a Spring que debe realizar el binding del parámetro de la request con nombre imagenPerfil.


10. Interacción con otros componentes RUP

En este apartado se van a mostrar ejemplos para indicar como se debe especificar el uso de los diferentes componentes RUP en el formulario de detalle.

Los ejemplos plantean la creación de un componente para una columna especificada en el colModel. Como norma general para todos los componentes rup, el tipo de componente se especifica en la propiedad rupType, mientras que las propiedades de configuración correspondientes se especificarán en la propiedad editoptions.

colModel: [{ name: "nombre_de_columna" ,

rupType: "tipo_de_componente_RUP" , editoptions: { // Opciones de configuración del componente },

}]

Tanto para el componente hora como para el componente fecha se han creado unos formatter predefinidos para facilitar el formateo de las fechas:

• RupDate: "d/m/Y" • RupDateTime: "d/m/Y H:i" • RupDateTimeSec: "d/m/Y H:i:s" • RupTime: "H:i" • RupTimeSec: "H:i:s"

En los ejemplos de creación de los componentes fecha y hora se puede apreciar su uso.

• Autocomplete:

Creación de un autocomplete remoto. El tipo de componente se especifica en la propiedad rupType. Las propiedades de configuración del componente autocomplete se indican en la propiedad editoptions del colModel.

colModel: [{ name: "usuario.id" , jsonmap: "usuario.id" , label: "idUsuario" , index: "idUsuario" , editable: true, rupType: "autocomplete", formatter: "rup_combo" , editoptions: { source : "../usuario" , sourceParam : {label: "nombre" , value: "id" , style: "css" },


valueName: " usuario.id ", labelName: "usuario.apellido1" }

}]

• Combo:

Creación de un combo remoto. El tipo de componente se especifica en la propiedad rupType. Las propiedades de configuración del componente combo se indican en la propiedad editoptions del colModel.

colModel: [{ name: "usuario.id" , jsonmap: "usuario.id" , label: "idUsuario" , index: "idUsuario" , editable: true, rupType: "combo" formatter: "rup_combo" , editoptions: { source : "../usuario" , blank sourceParam : {label: "desc" +$.rup_utils.capitalizedLang(),

value: "code" , style: "css" }, blank: "" }

}]

• Fecha:

Creación de un componente fecha. El tipo de componente se especifica en la propiedad rupType. Las propiedades de configuración del componente fecha se indican en la propiedad editoptions del colModel.

En la propiedad formatOptions se indica el uso de un formatter predefinido de RUP.

colModel: [{ name: "usuario.fechaAlta" , jsonmap: "usuario.fechaAlta" , label: "fechaAlta" , index: "fechaAlta" , editable: true, rupType: "date" formatter: "date" , formatoptions:{newformat: "RupDateTime" }, editoptions: { datetimepicker: true, showButtonPanel : true, showOtherMonths : true, noWeekend : true, showSecond: false, timeFormat: 'hh:mm' }

}]


Tanto para el componente hora como para el componente fecha.

• Time:

Creación de un componente hora. El tipo de componente se especifica en la propiedad rupType. Las propiedades de configuración del componente hora se indican en la propiedad editoptions del colModel.

En la propiedad formatOptions se indica el uso de un formatter predefinido de RUP

colModel: [{ name: "usuario.horaAlta" , jsonmap: "usuario.horaAlta" , label: " horaAlta" , index: " horaAlta" , editable: true, rupType: "time" formatter: "rup_time" , formatoptions:{newformat: "RupTime" }, editoptions: { datetimepicker: true, showButtonPanel : true, showOtherMonths : true, noWeekend : true, showSecond: false, timeFormat: 'hh:mm' }

}]

• Validación:

El mantenimiento permite el uso del componente RUP validación para realizar la validación de los campos del formulario de detalle. La configuración de dicho componente se realiza mediante la propiedad validation del mantenimiento.

$( "#mantenimiento" ).rup_maint({ jQueryGrid: "GRID_alumno" , ... ... validation:{ messages:{ "password_confirm":$.rup.i18n.app.alumno.password_confirm, "email_confirm":$.rup.i18n.app.alumno.email_confirm }, rules:{ "nombre":{required:true}, "password_confirm":{equalTo:"#password"}, "email_confirm":{equalTo:"#email"} } }, ... ... }

uda-componentes rup. mantenimiento (v2.1.1 deprecado)

Technology