1

Manual de Generador de Formularios de Template Saga

www.sagasoluciones.com [email protected] C/ Salado 11 Local 10. 41010 Sevilla T. + 34 954 45 72 75 F. + 34 954 45 75 72

Manual de Generador de Formularios

CONTROL DEL DOCUMENTO

Realizado 28/09/2010 Sergio Raposo Vargas Director Técnico

Revisado

Control de Modificaciones

Revisión Nº 1

Fecha 28/09/2010

2 SAGA Soluciones Tecnológicas

Autor/res Sergio Raposo Vargas

Descripción Redacción inicial

Manual de Generador de Formularios

Índice de Contenido 1.

INTRODUCCIÓN ............................................................................................................. 4

2.

ANOTACIONES ............................................................................................................. 5 2.1.

ATRIBUTOS COMUNES ___________________________________________________ 5

2.2.

INPUTTEXT ___________________________________________________________ 5

2.3.

PASSWORDTEXT _______________________________________________________ 6

2.4.

HIDDEN ______________________________________________________________ 6

2.5.

TEXTAREA ___________________________________________________________ 6

2.6.

SELECT______________________________________________________________ 7

2.7.

RADIO_______________________________________________________________ 7

2.8.

CHECKBOX ___________________________________________________________ 8

2.9.

SIMPLECHECKBOX _____________________________________________________ 8

2.10. W YSIWYG ____________________________________________________________ 8 2.11. FILE ________________________________________________________________ 9 2.12. CALENDAR __________________________________________________________ 10 2.13. AUTOCOMPLETEINPUTTEXT ______________________________________________ 11

3.

CLASES JAVA IMPLICADAS ...........................................................................................12 3.1.

CREACIÓN DEL BEAN ___________________________________________________ 12

3.2.

CLASE FORMGENERATOR _______________________________________________ 12

3.1.

CLASE PERSONALIZADA _________________________________________________ 12

3.2.

PRINTFORM _________________________________________________________ 14

4.

NUESTRA JSP..............................................................................................................15

3 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

1. Introducción El generador de formulario es un módulo adicional de Template Saga que se planteo para resolver el problema de los formularios a medida que, según las necesidades del cliente, era necesario realizar en nuestros proyectos. Con el tiempo, el desarrollo de un formulario a medida implicaba un trabajo bastante repetitivo que consistía en: -

Crear la jsp que mostrara el formulario y que se recargara automáticamente con los valores para la edición del recurso. Validar los valores introducidos y mostrar los errores de validación en el formulario. Recoger los datos enviados y guardarlos en un objeto bean para su posterior tratamiento. Añadir la funcionalidad al formulario necesaria en cada caso.

Una vez el formulario estaba hecho había una función de mantenimiento que era bastante costosa ya que añadir o borrar un campo del formulario implicaba tocar en demasiados sitios y muchas veces provocaba que este proceso fuera lento y a veces derivaba en errores en la aplicación. Por todo esto se planteo la opción de desarrollar un módulo que nos permitiera generar de una forma simple y rápida formularios a medida y que el trabajo repetitivo nos lo evitásemos, haciendo que el mantenimiento fuera también mucho más rápido. Para ello se planteo la opción de usar anotaciones de java (característica disponible desde java 5). Para ello se generaron una serie de anotaciones que, colocadas en los atributos de una Clase Bean nos permitiera generar automáticamente el formulario, y que este mismo objeto se rellenara automáticamente al enviarse el formulario. Con este módulo, la creación de un formulario pasaba por: -

Definir la clase Bean y aplicarle las anotaciones correspondientes a cada atributo. Definir una clase principal la cual nos permitirá implementar la funcionalidad y la validación de los campos.

4 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

2. Anotaciones 2.1.

Atributos comunes

Existen una serie de atributos comunes a todas las anotaciones que son: -

-

-

-

-

label: Este campo establecerá la etiqueta de nuestro campo. Se puede definir una key del fichero de idiomas. El sistema en primer lugar comprobará si existe una key con el valor indicado, en caso contrario se mostrará directamente el valor. Este campo es obligatorio. mandatory: (true-false) Indicará si el campo se marcará como obligatorio o no, es decir, si le marcará el ‘*’ al lado del label del campo indicándole al usuario que es obligatorio. Este campo no es obligatorio. help: Este campo hará que se muestre un icono de ayuda contextual al lado del label del campo. Al igual que el label, en primer lugar buscará si existe una key en el fichero de idiomas con el valor indicado, en caso contrario mostrará el valor directamente. Este campo no es obligatorio. getFieldSet: Este atributo nos agrupará dentro de un mismo fieldset todos los atributos que tenga el mismo valor configurado. El título del fieldset será obtenido del fichero de idiomas aplicando el valor como key o el mismo valor si no existe dicha key. Es necesario que todos los campos que tengan que estar dentro del mismo fieldset estén juntos. Este campo no es obligatorio. readOnly: este atributo establecerá si el campo será de solo lectura o si podremos escribir en él. No es obligatorio y por defecto será un campo editable.

En la definición de las anotaciones ignoraremos estos atributos y nos centraremos en los que difieren del resto.

2.2.

InputText

Esta anotación creará un recurso de tipo input type=text. Dispone de la siguiente configuración personalizada: -

-

multiple: Si se marca como true esta campo se marcará como un campo múltiple, es decir, dispondremos de botones + y – para crear y borrar elementos. Por defecto este atributo es false y no es obligatorio. urlValidationAjax: Este atributo lo usaremos cuando queramos validar un campo mediante ajax. Por ejemplo, en un formulario de registro puede ser útil para indicar si un nombre de usuario está ocupado, o si una contraseña no pasa los niveles de seguridad exigidos. El valor del atributo debe ser la url a la que se le llamará por ajax para la validación de la información. Los parámetros enviados serán: o action = validationajax o field = nombre del campo o value = valor introducido en el campo

5 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

La url a la que llama debe estar preparada para devolver un objeto json con 2 campos -

ok: será true si la validación es correcta y false en caso contrario msg: contendrá el mensaje a mostrar independiente de que la validación sea correcta o no.

Ejemplo: @InputText(mandatory=true,label="registroinstalador.email", help="registroinstalador.email", urlValidationAjax="ajaxValidator.html") private String email;

2.3.

PasswordText

Esta anotación creará un recurso de tipo input type=password. Ejemplo: @PasswordText(mandatory=true,label="registroinstalador.password", help="registroinstalador.password") private String password;

2.4.

Hidden

En este caso, usaremos la anotación Hidden para crear un campo oculto: input type=hidden Esta anotación no tiene configuración adicional ya que no es necesario. Lo podremos usar para asignarle valores mediante javascript, o por defecto dándoselo en el constructor por defecto. Ejemplo @Hidden() private String codigopostal;

2.5.

TextArea

La anotación TextArea nos creará en nuestro formulario un campo de tipo textArea. La configuración que se le pueda aplicar es: -

cols: atributo en el que se le indicará el número de columnas del textArea. Por defecto será 50 rows: atributo en el que se le indicará el número de filas que tendrá el textArea. Por defecto será 8.

Ejemplo: 6 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

@TextArea(label="registroinstalador.descripcionempresa", rows=10, cols=80, help="registroinstalador.descripcionempresa") private String descripcionEmpresa;

2.6.

Select

La anotación Select generará un desplegable en nuestro formulario el cual nos permitirá seleccionar entre varias opciones. La configuración adicional que posee este campo es: -

method: en este atributo hay que indicar el nombre del método que generará la lista de opciones que tendremos disponibles. Este método deberá devolver un objeto de tipo Map con los valores de la lista. La clave del map será el valor del campo option y el valor será la etiqueta del option. Ej: data.put(“opcion1”,”Opción 1 que se ve”) -> Opcion 1 que se ve.

Ejemplo: @Select(mandatory=true,label="registroinstalador.comunidad", help="registroinstalador.comunidad",method="getComunidades") private String comunidad; public HashMap getComunidades(){ HashMap data = new HashMap(); data.put("sevilla","Sevilla"); data.put("huelva","Huelva"); data.put("cadiz","Cádiz"); return data; }

2.7.

Radio

La anotación Radio generará un campo de tipo radiobutton en nuestro formulario el cual nos permitirá seleccionar una opción de entra una lista de opciones. La configuración adicional que posee este campo es: -

method: en este atributo hay que indicar el nombre del método que generará la lista de opciones que tendremos disponibles. Este método deberá devolver un objeto de tipo Map con los valores de la lista. La clave del map será el valor del campo option y el valor será la etiqueta del option. Ej: data.put(“opcion1”,”Opción 1 que se ve”) -> Opcion 1 que se ve.

Ejemplo: @Radio(mandatory=true,label="registrousuariofinal.tratamiento", method = "getOpcionesTratamiento", help="registrousuariofinal.tratamiento") private String tratamiento; public HashMap getOpcionesTratamiento(){ HashMap data = new HashMap(); data.put("sr",”SR.”);

7 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

data.put("sra",”Sra.”); return data; }

2.8.

CheckBox

La anotación CheckBox generará un campo de tipo checkbox en nuestro formulario el cual nos permitirá seleccionar una o varias opciones de entra una lista de opciones. La configuración adicional que posee este campo es: -

method: en este atributo hay que indicar el nombre del método que generará la lista de opciones que tendremos disponibles. Este método deberá devolver un objeto de tipo Map con los valores de la lista. La clave del map será el valor del campo option y el valor será la etiqueta del option. Ej: data.put(“opcion1”,”Opción 1 que se ve”) -> Opcion 1 que se ve.

Ejemplo: @CheckBox(mandatory=true,label="registroinstalador.actividad", method = "getActividades", help="registroinstalador.actividad") private List actividad; public HashMap getActividades (){ HashMap data = new HashMap(); data.put("a1",”Actividad 1”); data.put("a2",”Actividad 2”); return data; }

2.9.

SimpleCheckBox

En el caso del SimpleCheckBox, a diferencia del CheckBox, tan solo mostraremos una opción, es decir, se planteará una casilla y el usuario podrá activar o desactivarla. Este tipo de campo es útil para el caso que tengamos un campo booleano, es decir, tan solo admita valores true o false. Por ejemplo lo podemos usar para las casillas de validación de licencias o condiciones de uso muy comunes en los formularios de envío de información personal. En este caso no hay configuración adicional. Ejemplo: @SimpleCheckBox(label="registrousuariofinal.avisolopd", help="registrousuariofinal.avisolopd") private Boolean avisoLOPD;

2.10.

Wysiwyg

8 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

La anotación Wysiwyg nos creará un campo de edición de texto enriquecido basado en FCKEditor. Este campo es configurable mediante los siguientes atributos: •

•

• •

toolBar: En este atributo configuraremos las herramientas disponibles que se mostrarán en el editor. Por defecto tomará el valor “Tipico”. Los posibles valores son: o Default: Añade todas las herramientas más comunes del FCKEditor, incluido las galerías de OpenCms. o Intermedio: Añade las herramientas más comunes que un usuario editor necesita para editar su texto a medida. No muestra las herramientas propias de OpenCms o Tipico: Mantiene todas las herramientas de edición de contenidos que pueden ser necesaria quitando las que más pueden afectar al diseño de una web como el selector de colores y otras herramientas parecidas. o Normal: Deja un editor con las herramientas más normales que se usan en la edición de texto simple. o Basic: Deja un editor básico en el que apenas se disponen de herramientas para la edición del texto. o Otros: Para añadir nuevas configuraciones hay que editar el fichero /system/workplace/resources/editors/fckeditor/fckconfig.js y agregar la configuración que se desee. skin: El skin nos permite cambiar la apariencia del editor. Por defecto toma el valor “office2003”. Los posibles valores son: o default: usa el skin por defecto de FCKEditor o office2003: usa un skin parecido al que podemos ver en el Office 2003 o opencms: aplica el estilo de los editores internos de OpenCms o silver: Aplica un estilo particular con colores plateados. cols: Indica el número de columnas que tendrá la zona de edición. Por defecto será 50. rows: Indica el número de filas que tendrá el editor. Por defecto será 8.

Ejemplo: @Wisywyg(toolBar="Normal", skin=”default”, label="noticia.descripcion", help="noticia.descripcion",mandatory=true) private String descripcion;

2.11.

File

Esta anotación crea un campo de subida de ficheros en nuestro formulario. El botón de subida es el correspondiente al input type=file, y muestra el clásico botón de examinar. Esta anotación tiene una serie de atributos de configuración que nos permiten personalizar el campo que son: •

attrPath: Este atributo lo usaremos cuando el formulario se va a usar para la edición de un contenido, por ejemplo, cuando el campo de subida se refiere a una imagen y estamos editando, nos ayudará a mostrar la imagen que actualmente está subida. En este caso, si es una imagen (extensiones gif, png y jpg) se muestra la imagen, y si es un fichero se mostrará un enlace a la descarga del mismo. Por lo tanto, este campo deberá apuntar a otro campo

9 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

• •

del formulario en el cual guardaremos el path. Lo normal es que el campo al que apunte sea un campo hidden y que en el constructor de la clase se le de el valor correspondiente. attrUuid: El uso es similar al attrPath, pero en lugar de guardar la ruta del recurso, guardaremos el uuid. El resto del funcionamiento es el mismo. attrConservar: Este campo pintará en el formulario, siempre que el campo no sea obligatorio, una opción de conservar fichero adjunto o no. Para entender este campo debemos pensar en un formulario de edición de contenido, por ejemplo, en el caso de editar una noticia que por cualquier motivo el usuario desea borrar la imagen subida con anterioridad y no subir una imagen nueva. En este caso, se le presenta una casilla en la que el usuario podrá marcar como “no conservar” en cucho caso se borraría el fichero del formulario. Para qué funcione correctamente tendremos que asignarle un valor al campo donde se guardará la elección del usuario. En ese caso, a la hora de recoger la información y añadir la funcionalidad al mismo, habrá que leer este campo para saber si debemos mantener o borrar el archivo adjunto.

Ejemplos: @File(label="noticia.image",mandatory=true, attrPath="pathImage") private FileItem image; @Hidden(label="pathImage") private String pathImage; @File(label="noticia.documento", help="noticia.documento ", attrUuid="uuidDocumento") private FileItem documento; @Hidden(label="uuidDocumento") private String uuidDocumento;

2.12.

Calendar

La anotación Calendar nos permite crear campos en nuestro formulario para la selección de fechas. Usa el componente javascript jscalendar. En este caso podremos configurar el estilo del formulario aplicándole una css u otra mediante el atributo css. Por defecto tomará el valor calendar-blue. Los posibles valores son: • • • • • • • • • •

calendar-blue calendar-brown calendar-green calendar-opencms calendar-system calendar-tas calendar-win2k-1 calendar-win2k-2 calendar-win2k-cold-1 calendar-win2k-cold-2

Ejemplo: 10 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

@Calendar(label="noticia.fecha",mandatory=true) private String fecha;

2.13.

AutocompleteInputText

El autocomplete es un campo similar al inputText con la única diferencia que al escribir sobre el campo aparecerán una lista con valores candidatos. Por ejemplo, podemos aplicarle este campo a un campo de inserción de un código postal, de forma que conforme el usuario teclee un valor se le muestre las opciones candidatas al valor introducido. Para que funcione este campo es necesario implementar una página aparte donde se procede a realizar la consulta y a mostrar los posibles valores candidatos. En el caso de nuestro ejemplo haremos una consulta a la BBDD para extraer todos los códigos postales que empiezan por los valores introducidos. Para implementar esta opción se ha usado el plugin autocomplete de jquery por lo que podemos consultar la documentación oficial para conocer más sobre este componente (http://bassistance.de/jqueryplugins/jquery-plugin-autocomplete/). Para personalizar este campo podremos usar los siguientes atributos: •

• •

url: atributo en el que indicaremos la ruta del recurso donde haremos la consulta. Normalmente se usa una ruta relativa para evitar problemas, relativa a la url del formulario. Esta nueva página recibirá un parámetro “q” con el valor introducido por el usuario en cada momento. Debe generar una página con la lista de posibles candidatos, de forma que cada opción ocupe una línea. La línea a su vez tendrá el siguiente formato: label | valor En el resto de atributos podremos tratar tanto el label como el valor con los siguientes atributos. Options: Con este atributo podemos configurar las distintas opciones que nos ofrece el plugin. Result: Con este atributo podemos manipular los resultados obtenidos con la consulta según nuestras necesidades.

Ejemplo: @AutocompleteInputText(mandatory=true,label="registrousuariofinal.codigopostal",url ="getcp.html", options="minChars:2,mustMatch:true,max:20,formatResult: function(data) {if (data){var campos=data[1].split('@');return campos[0];}return '';}", result="if (data){var campos=data[1].split('@');$(\"#codigopostal\").val(campos[0]);$(\"#localidad\").val (campos[1]);$(\"#provincia\").val(campos[2]);}", help="registrousuariofinal.codigopostal") private String codigopostalautocomplete;

11 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

3. Clases java implicadas

3.1.

Creación del Bean

La clase bean es la clase donde aplicaremos las anotaciones antes comentadas y donde estableceremos todos los campos de nuestro formulario. Los objetos de esta clase serán donde almacenaremos la información redactada por los usuarios y con la que podremos trabajar a la hora de implementar la funcionalidad deseada. Uno de los aspectos importantes a tener en cuenta es que el orden con el que establezcamos los atributos será el orden que posteriormente se aplicará a la hora de generar el formulario. Como toda clase bean, es necesario dispones de los métodos getters y setters de cada campo, métodos que nos permitirán actualizar y obtener los valores.

3.2.

Clase FormGenerator

Template Saga posee una clase que es la encargada de generar el formulario en base a nuestra configuración. En este caso, la clase responsable de hacer este recorrido es FormGenerator. Además, esta clase contendrá todos los métodos comunes que tienen los generadores de cada anotación.

3.1.

Clase personalizada

Para poder implementar la funcionalidad asociada a nuestro formulario, deberemos crear una clase propia. Lo más importante en este caso es hace rque nuestra clase extienda la clase: AbstractFormBeanSimple Esta clase abstracta nos dará implementados una serie de métodos y atributos que nos será útil a la hora de gestionar nuestro formulario. Las características principales de esta clase son: • •

Atributos propios de jsp: request, response, context y CmsJspActionElement. Lista de errores: Esta clase ofrece 2 atributos donde guardar los posibles errores de validación o ejecución que se produzcan. Estos son: o List errors: se mostrará por encima del formulario como un error general del formulario. Es una lista por tanto si queremos mostrar más de uno tan solo debemos agregar más entradas en la lista.

12 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

•

o Map errorMap: en este objeto Map almacenaremos como clave el nombre de un campo y como valor el String que describe el error que se ha producido. Gracias a este mapa podremos mostrar errores personalizados en cada campo, es decir, dentro del propio campo donde se ha producido el error de validación. Método proccessForm: Este método es el que se debe invocar en la jsp cuando se envía el formulario y que realiza todo el proceso. El proceso se divide en tres fases: 1. Se procesa el bean que almacena los parámetros, este proceso nos devuelve errores de conversión. 2. En caso de que no haya errores de conversión se procede con la validación 3. Si no hay errores de validación se ejecuta el método executeAction() que realiza las operaciones necesarias sobre los datos

Para poder extender de esta clase lo haremos de la siguiente forma: public class NombreNuestraClaseDeFormulario extends AbstractFormBeanSimple{ … }

Una vez visto lo que nos ofrece la clase abstracta, veamos qué métodos tenemos que implementar obligatoriamente en nuestra clase: Constructor Debemos implementar un constructor tal que: public RegistroInstaladorForm(PageContext context, HttpServletRequest req,HttpServletResponse res) { super(context, req, res); ... }

En este caso si fuera necesario inicializar algún dato más podremos hacerlo donde están los puntos suspensivos (…) executeAction En este método debemos implementar la funcionalidad propia de nuestro formulario, es decir, implementaremos la lógica de negocio. Una vez llegado el formulario a este método se da por hecho que los datos que llegan han sido validados previamente por lo que no tendremos que volver a validarlos. getParameterBean Este método devuelve el objeto que almacena los datos del formulario. Cada formulario debe tener un objeto bean asociado. En nuestra clase deberemos mantener como atributo este objeto, que será lo que devolveremos en este método. 13 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

getRequesProcesor Este método retorna la clase encargada de procesar el bean que almacena los datos del formulario. La implementación para procesar el bean con los parámetros del request es la siguiente: public BeanProcesor getRequesProcesor(){ return new RequestBeanMapper(getRequest(),new ConversionErrorMessageBundle("com.saga.proyecto.workplace")); }

El procesador del request puede ser de dos tipos: MultipartRequestProccessor o DefaultRequestProccessor, según si el formulario contiene un campo file, o no. validate Esta función es la encargada de validar la información introducida por el usuario. Tendrá que validar desde que todos los campos marcados como obligatorios hayan sido rellenos hasta que el formato de cada campo es correcto según las reglas establecidas en cada caso. En el momento de que se detecto un error de validación deberemos darlo de alta en las listas de errores: getErrors().add(“Descripción del error”); getErrorMap().put("campo",”Descripción del error”);

3.2.

PrintForm

La clase PrintForm es una clase de Template Saga situada en el paquete: com.saga.opencms.templatesaga.formulario.print Con esta clase nos ayudara a procesar el formulario y a pintar los campos configurados mediante anotaciones en nuestro bean. Los métodos principales son: • • • • • •

print(): devuelve el código html del formulario completo. printPartial(): Devuelve el html del formulario sin la etiqueta form y sin los botones de envio. process(): Lee los campos del bean y monta el formulario isSend(): Devuelve true si el formulario se ha enviado y false en caso contrario setMessage(messages): Método con el que podemos configurar el fichero de mensajes que vamos a utilizar para mostrar el formulario. El locale utilizado será el configurado por defecto en la carpeta de OpenCms. getMsg(key): Devuelve el valor de la key enviada por parámetro. Previamente es necesario haber indicado el fichero de idiomas que vamos a utilizar.

14 SAGA Soluciones Tecnológicas

Manual de Generador de Formularios

4. Nuestra jsp Por último, para terminar con el trabajo de generación de un formulario tenemos que crear la jsp que mostrará el formulario. En nuestro caso esta jsp será muy simple, tan solo tendremos que instanciar un objeto de nuestra clase, y de la clase PrintForm de Template Saga. Con el método form.isSend(request) podremos saber si el formulario se ha enviado o no, en el caso que no se haya enviado pintamos el formulario con form.print, y en caso contrario procesamos el formulario con el método processForm().



16 SAGA Soluciones Tecnológicas