Manual de Usuario Componentes de Menús

Transcripción

1 Manual de Usuario Componentes de Menús Versión 1.4 Área de Aplicaciones Especiales y Arquitectura de Software

2 Hoja de Control Título Documento de Referencia Responsable Manual de usuario Componentes de Menú NORMATIVA ATLAS Área de Aplicaciones Especiales y Arquitectura de Software Versión 1.4 Fecha Versión 26/10/2012 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio 1.0 Versión inicial del documento 1.1 Actualizadas capturas de las diferentes tipos de plantillas. 1.2 Se modifica el nombre del Area Ampliada la descripción del atributo perfil Corregidos errores en los atributos del menú horizontal. Área de Integración y Arquitectura de Aplicaciones Área de Integración y Arquitectura de Aplicaciones Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software Área de Aplicaciones Especiales y Arquitectura de Software 25/05/ /02/ /09/ /01/ /08/ de 25

3 Índice 1. INTRODUCCIÓN AUDIENCIA OBJETIVO CONOCIMIENTOS PREVIOS DESCRIPCIÓN INSTALACIÓN Y CONFIGURACIÓN INSTALACIÓN CONFIGURACIÓN Paso 1: Edición del fichero de opciones del menú USO PASO 1: SELECCIÓN DE LA PLANTILLA PASO 2: CREACIÓN DEL FICHERO XHTML BASADO EN LA PLANTILLA PASO 3: INSERCIÓN DE LA ETIQUETA DE MENÚ HORIZONTAL PASO 4: INSERCIÓN DE LA ETIQUETA DE MENÚ VERTICAL PASO 5: INSERCIÓN DE LA ETIQUETA DE MENÚ VISUAL RECOMENDACIONES Y BUENAS PRÁCTICAS EJEMPLO DE USO PREGUNTAS MÁS FRECUENTES ENLACES RELACIONADOS de 25

4 1. INTRODUCCIÓN Este documento contiene el manual de uso de los componentes visuales de Menú del Framework Atlas. Actualmente se incluyen tres componentes claramente diferenciados, uno para el menú horizontal (en la parte superior de la página), otro para el menú vertical (en la zona izquierda de la página), y otro para el menú visual (en la zona central de la página, con imágenes para cada opción de menú). Dichos componentes pueden combinarse, de manera que sólo se muestre uno de ellos, dos, o incluso los tres. En este documento se incluye información sobre cómo utilizar dichos componentes en una aplicación Web, así como información acerca de la configuración de los parámetros fundamentales de estos componentes AUDIENCIA OBJETIVO Este documento está orientado a toda aquella persona que esté desarrollando una aplicación Web basada en el Framework Atlas y necesite utilizar los componentes de menús en su aplicación Web CONOCIMIENTOS PREVIOS Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: Java Server Faces (JSF) Facelets Spring Framework Hibernate Para saber más sobre dichas tecnologías, consultar el apartado de este documento, Enlaces Relacionados. 4 de 25

5 2. DESCRIPCIÓN Se dispone de tres componentes visuales, uno para el menú horizontal, otro para el vertical y otro para el visual. Estos componentes pueden combinarse en la pantalla, de manera que cuando se pulse sobre una opción de uno de los menús, se actualicen los otros con la nueva opción seleccionada. Para combinar varios menús en la misma página, estos recuperan de la request el id seleccionado y cambian su estado para actualizarse. El contenido del menú se define dinámicamente en un fichero de configuración XML que contiene todos los elementos de menú de la aplicación. A continuación se muestra un ejemplo de los menús horizontal, vertical y visual combinados en la misma pantalla: 3. INSTALACIÓN Y CONFIGURACIÓN En este apartado se incluye información sobre la instalación y la configuración de los componentes de Menú que vienen incluidos en el framework Atlas INSTALACIÓN Los componentes de menú ya vienen instalados en el arquetipo Web, incluidos en el módulo de componentes visuales. Por este motivo no es necesaria una instalación adicional si se parte del arquetipo CONFIGURACIÓN 5 de 25

6 Para configurar los componentes de menú para poder ser utilizados es necesario seguir los pasos descritos a continuación: Paso 1: Edición del fichero de opciones del menú El contenido del menú se obtiene dinámicamente de un fichero de configuración XML que contiene todos los elementos de menú de la aplicación. En el arquetipo de aplicaciones Web viene incluido este fichero, que se encuentra en la ruta src/main/resources/menu.xml del módulo web del arquetipo. El fichero contiene todos los elementos de menú de la aplicación, cada componente de menú (horizontal, vertical o visual) puede decidir qué grupo de estos elementos mostrará, a través de los atributos de la etiqueta que se describe en la sección de uso del componente. Un ejemplo de un fichero de menú XML es el siguiente: menu.xml <?xml version="1.0" encoding="utf-8"?> <!-- edited with XMLSPY v2004 rel. 3 U ( by ICM (Comunidad de Madrid) --> <menu xmlns:xsi=" xsi:nonamespaceschemalocation="menu_aplicacion.xsd"> <elemento id="1" nombre="home" nombre_navegacion="inicio" url="/secure/index.jsf" perfil="role_1"> </elemento> <elemento id="3" nombre="menu1" nombre_navegacion="menu1" url=""> <elemento id="3_1" nombre="submenu1" nombre_navegacion="submenu1" url="/secure/index.jsf"> </elemento> <elemento id="3_2" nombre="submenu2" nombre_navegacion="submenu2" url="/secure/index.jsf"> </elemento> </elemento> <elemento id="4" nombre="información del usuario" nombre_navegacion="infousuario" url="/secure/infousuario.jsf"> </elemento> </menu> En la siguiente tabla se describe cada uno de los atributos de los elementos del menú: Nombre atributo Obligatorio Descripción id SI Identificador de la opción. En subopciones de menú, el id debe empezar por el id de la opción, seguido de un guión bajo y el id de la subopción. 6 de 25

7 nombre SI Nombre a mostrar en el menú nombre_navegacion SI Nombre a mostrar en el rastro de migas url SI URL asociada a esa opción de menú. perfil NO Perfiles de usuario que pueden ver esa opción de menú (si son varios deben aparecer separados por punto y coma). 4. USO Una vez editado el fichero de definición del menú, puede procederse a su utilización. Para ello, en el arquetipo web se incluyen una serie de plantillas para todas las posibles combinaciones de menús (horizontal sólo, horizontal con vertical, etc.). Además de estas plantillas, existen tres componentes jsf que pueden utilizarse a través de etiquetas que incrustan el menú adecuado en la página. A continuación se describen los pasos necesarios para utilizar los menús, primero seleccionando la plantilla y luego incrustando las etiquetas adecuadas Paso 1: Selección de la Plantilla Para utilizar los menús, lo primero que hay que hacer es decidir cuál va a ser el layout o plantilla de nuestra página (cuáles de los tres menús disponibles se van a utilizar). Los ficheros de plantillas están en el arquetipo en el directorio src/main/webapp/web-inf/layout, y son los siguientes: 7 de 25

8 - hc.xhtml: (Horizontal+Contenido). Incluye un menú horizontal, y en el resto de la página se muestra el contenido. Ejemplo: 8 de 25

9 - hvc.xhtml: (Horizontal+Vertical+Contenido). Incluye un menú horizontal, uno vertical y en el resto de la página se muestra el contenido. Ejemplo: 9 de 25

10 - hv.xhtml: (Horizontal+Visual). Incluye un menú horizontal, y en el resto de la página se muestra el menú visual. Ejemplo: 10 de 25

11 - hvv.xhtml: (Horizontal+Vertical+Visual). Incluye un menú horizontal, menú vertical y en el resto de la página se muestra el menú visual. Ejemplo: 11 de 25

12 - vc.xhtml: (Vertical + Contenido). Incluye un menú vertical, y en el resto de la página se muestra el contenido. Ejemplo: 12 de 25

13 - vv.xhtml: (Vertical + Visual). Incluye un menú vertical, y en el resto de la página se muestra el menú visual. Ejemplo: 13 de 25

14 - c.xhtml: (Contenido). No incluye menús, muestra directamente el contenido de la página en la zona central. Ejemplo: 4.2. Paso 2: Creación del fichero xhtml basado en la plantilla Una vez seleccionada la plantilla, debemos crear nuestro fichero xhtml que utilice dicha plantilla, y defina los componentes que se desean insertar en cada zona de la plantilla. En el arquetipo web vienen varios ejemplos de ficheros que utilizan las plantillas, por ejemplo en la página index.xhtml se utiliza la plantilla vc.xhtml (Menú Vertical + Contenido): index.html 14 de 25

15 <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" xmlns:h=" xmlns:f=" xmlns:t=" xmlns:ui=" xmlns:atlas=" xmlns:a4j=" <ui:composition template="/web-inf/layout/vc.xhtml"> <ui:define name="titulo"> <ui:include src="/secure/titulo.xhtml" /> <ui:define name="rastromigas"> <ui:include src="/rastromigas/rastro.xhtml" /> <ui:define name="menuvertical"> <!-- Se hace referencia al fichero con el menú vertical --> <ui:include src="/menu/menu.xhtml" /> <ui:define name="content"> Aquí va el contenido </ui:composition> </html> Este fichero xhtml tiene que contener las siguientes zonas: 1) Definición del espacio de nombres de etiquetas de Atlas Es necesario establecer la definición del espacio de nombres para las etiquetas de componentes de Atlas. Esto nos permitirá utilizar las etiquetas que incrustan los componentes de menú en la página. Un ejemplo de cabecera de fichero xhtml es la siguiente: <?xml version="1.0" encoding="utf-8"?> Cabecera de fichero xhtml <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" xmlns:h=" xmlns:f=" xmlns:t=" xmlns:ui=" xmlns:atlas=" xmlns:a4j=" 15 de 25

16 2) Inclusión de la plantilla, y definición del contenido de cada zona En nuestro fichero xhtml es necesario incluir la plantilla a utilizar, así como definir los componentes que van a ir en cada una de las zonas. Por ejemplo, en la página principal del arquetipo web se incluye un menú vertical+contenido (plantilla vc.xhtml), donde la zona del menú vertical hace referencia a otro fichero (menu.xhtml), y el contenido se incluye tal cuál: Ejemplo.xhtml <ui:composition template="/web-inf/layout/vc.xhtml"> <ui:define name="titulo"> <ui:include src="/secure/titulo.xhtml" /> <ui:define name="rastromigas"> <ui:include src="/rastromigas/rastro.xhtml" /> <ui:define name="menuvertical"> <!-- Se hace referencia al fichero con el menú vertical --> <ui:include src="/menu/menu.xhtml" /> <ui:define name="content"> Aquí va el contenido </ui:composition> </html> Otro ejemplo para un menu horizontal, vertical y visual juntos sería el siguiente: Ejemplo.xhtml 16 de 25

17 <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" xml:lang="es" xmlns:ui=" xmlns:h=" xmlns:f=" xmlns:a4j=" xmlns:rich=" xmlns:c=" <ui:composition template="/web-inf/layout/hvv.xhtml"> <ui:define name="titulo"> <ui:include src="/secure/titulo.xhtml" /> <ui:define name="menuhorizontal"> <ui:include src="/secure/menuhorizontal/menuhorizontalheadersample.xhtml"/> <ui:define name="rastromigas"> <ui:include src="/rastromigas/rastromigasicm.xhtml"/> <ui:define name="menuvisual"> <ui:include src="/secure/menuvisual/menuvisualsample.xhtml"/> <ui:define name="menuvertical"> <ui:include src="/menu/menuicm.xhtml"/> </ui:composition> </html> En este fichero se hace referencia a otros xhtml en los que se definirá el contenido de cada una de las áreas de la plantilla. En algunas de ellas se deberá incluir cada uno de los tres componentes de menú, según se explica en el siguiente punto Paso 3: Inserción de la etiqueta de Menú Horizontal Una vez definida nuestra plantilla y fichero xhtml, debemos de definir el contenido de cada una de las zonas. Concretamente, si estamos utilizando una plantilla con menú horizontal, se utiliza la etiqueta menuhorizontal. A continuación se muestra un ejemplo de cómo se inserta esta etiqueta dentro de una pagina XHTML: Ejemplo.xhtml 17 de 25

18 <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" xml:lang="es" xmlns:ui=" xmlns:h=" xmlns:f=" xmlns:atlas=" <ui:composition> <f:loadbundle basename="msg/messages" var="bundle" /> <atlas:menuhorizontal id="menu" datamodel="#{menuhorizontalsamplebean.menuhorizontalgral}" menuelementoancho="7.5em" divid="cabecera" ulid="menuppal" menucode="menu_xml_file" elementoclass="elemento" menuclass="menuhorizontal"/> </ui:composition> </html> En la siguiente tabla se muestra el significado de cada uno de los atributos de la etiqueta: Nombre atributo Obligatorio Descripción datamodel SI EL (Expression Language) que indica el bean que da respaldo a este componente. Además debe ser del tipo MenuHorizontalBean y tener inicializada la propiedad atlasfacade. idelemento NO Identificador de elemento de menú XML cuyos hijos van a ser mostrados como elementos del menú horizontal. Un ejemplo de id (representando un nodo en el XML) válido es el siguiente: "3_2" lo que significa segundo elemento de la lista de hijos del tercer elemento, de los elementos que están al primer nivel. Si no se especifica se mostrará el primer nivel del menú. menucode NO Clave del fichero de pares clave-valor application.properties para identificar el fichero de menú cuyos elementos serán presentados por el componente de menú. El valor por defecto es MENU_XML_FILE. rendered NO Valor true false para seleccionar si este componente se va a mostrar. Por defecto es true. 18 de 25

19 styleclassselected NO Estilo css para la opción seleccionada. Su valor por defecto es menu_horiz_selected. divid NO Id para el div que engloba la lista de enlaces. ulid NO Id para el tag HTML ul con la lista de enlaces. submenus NO Valor true false para seleccionar si este componente va a filtrar los elementos del componente menú vertical por la opcion de menú horizontal seleccionada. Por defecto es false. En caso de que este valor sea true entonces a la request se le añade un parámetro submenuid con el id del elemento de menú seleccionado Paso 4: Inserción de la etiqueta de Menú Vertical Si estamos utilizando una plantilla con menú vertical, se utiliza la etiqueta menuvertical. A continuación se muestra un ejemplo de cómo se inserta esta etiqueta dentro de una pagina XHTML: Ejemplo.xhtml <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" xml:lang="es" xmlns:ui=" xmlns:h=" xmlns:f=" xmlns:atlas=" <ui:composition> <div id="menulateralseccion"> <div id="menu" class="menu_vert"> <atlas:menuvertical authorizationenabled="true"/> </div> </div> </ui:composition> </html> Este componente sirve para mostrar un conjunto de elementos de menú del fichero de menú XML de la aplicación con una dirección vertical. Tiene estructura jerárquica de árbol, con lo que se puede incluir distintos nodos que aparecerán agrupados por niveles. En la siguiente tabla se muesta el significado de cada uno de los atributos de la etiqueta: 19 de 25

20 Nombre atributo Obligatorio Descripción id NO Identificador del componente authorizationenabled NO Valor true false para establecer si este componente va a filtrar los elementos del menú dependiendo del perfil del usuario que se ha logado en el sistema. Por defecto es true menucode NO Clave del fichero de pares clave-valor application.properties para identificar el fichero de menú cuyos elementos serán presentados por el componente de menú. El valor por defecto es MENU_XML_FILE. nivelfinal NO Valor para el nivel hasta el que se quiere que se filtren los elementos de menú. nivelinicial NO Valor para el nivel a partir de cual se quiere que se filtren los elementos de menú. rendered NO Valor true false para seleccionar si este componente se va a mostrar. Por defecto es true submenuid NO Identificador por el cual filtrar los elementos del menú vertical. Es un identificador propio en el fichero de menú XML. Tiene prioridad sobre el valor puesto en este atributo el identificador que se estableció en la request con la misma semántica que este atributo, y que fue establecido por otro componente, como el menú Horizontal, en caso de que se haya establecido 4.5. Paso 5: Inserción de la etiqueta de Menú Visual Si estamos utilizando una plantilla con menú visual, se utiliza la etiqueta menuvisual. Este componente sirve para mostrar un conjunto de elementos de menú estructurado mediante una tabla. Se apoya en el componente de RichFaces datagrid. El aspecto del componente es el siguiente: 20 de 25

21 Figura Menú visual A continuación se muestra un ejemplo de cómo se inserta esta etiqueta dentro de una pagina XHTML: Ejemplo.xhtml <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " transitional.dtd"> <html xmlns=" xml:lang="es" xmlns:ui=" xmlns:h=" xmlns:f=" xmlns:c=" xmlns:fn=" xmlns:a4j=" xmlns:rich=" xmlns:atlas=" <ui:composition> <f:loadbundle basename="msg/messages" var="bundle" /> <h:form id="provinciasformbean"> <atlas:menuvisual id="indexvisual" datamodel="#{menuvisualsamplebean.menugeneral}" menucode="menu_xml_file" columns="3" tablamenuvisualclass="tabla_menuvisual" tituloclass="legend" txtelementoclass="label" imagenclass="imagen_mv" /> </h:form> </ui:composition> </html> En la siguiente tabla se muesta el significado de cada uno de los atributos de la etiqueta: 21 de 25

22 Nombre atributo Obligatorio Descripción id SI Identificador del componente datamodel SI EL ( Expression Language) que indica el bean que da respaldo a este componente. Además debe ser del tipo MenuHorizontalBean. El backing bean que contenga una instancia de este bean necesita inyectarle el objeto AtlasFacade en su método init columns NO Establece el número de columnas que se quiere establecer en la tabla principal del menú visual. El valor por defecto para este valor es 1 idelemento SI Identificador por el cual filtrar los elementos del Menú Visual Es un identificador propio en el fichero de menú XML. Los elementos que se mostrarán con este componente corresponde con los hijos de este elemento. imagenclass NO Estilo para las imágenes de cada celda del menú. menucode NO Clave del fichero de pares clave-valor application.properties para identificar el fichero de menú cuyos elementos serán presentados por el componente de menú. El valor por defecto es MENU_XML_FILE. rendered NO Valor true false para seleccionar si este componente se va a mostrar. Por defecto es true tablamenuvisualclass NO Estilo para la tabla principal del menú visual tituloclass NO Estilo del título para cada celda del menú. txtelementoclass NO Estilo para el texto de la descripcion de cada celda del menú RECOMENDACIONES Y BUENAS PRÁCTICAS Se debe de validar el XML de menú contra su esquema: menu_aplicacion.xsd, que es el esquema de menús existente en ICM, en su versión que admite elementos del tipo celda-menu. Estos elementos están diseñados para soportar componentes del tipo Menú Visual EJEMPLO DE USO 22 de 25

23 Se puede ver un ejemplo de los componentes de menú en la aplicación de demostración de componentes, bajo la siguiente secuencia de navegación: Inicio > Menú > Menú Horizontal / Vertical /. 23 de 25

24 5. PREGUNTAS MÁS FRECUENTES Pregunta: Dónde puedo encontrar información general sobre los componentes? Respuesta: En la aplicación de demostración de los componentes del Framework Atlas Pregunta: Qué interacción un componente de menú con el resto de elementos de Menú? Respuesta: Puesto que los enlaces que construye este componente tienen un parámetro id con el valor del elemento de menú correspondiente, cualquier otro componente de menú comprueba, cuando se produce una petición, este parámetro en el objeto Request y su valor. Entonces, determina cuál es la opción que se ha elegido y se proceden a representar con el elemento de menú seleccionado como destacado. Pregunta: Cómo se ha implementado el componente en su capa de presentación? Respuesta: Mediante un componente de Facelets. Los mensajes de error se extraen del contexto de Faces. Pregunta: Cómo puedo modificar los estilos del componente? Respuesta: Mediante los atributos de estilo del componente. Para más información consultar la tabla de atributos en la sección de Uso del componente. 24 de 25

25 6. ENLACES RELACIONADOS Producto Ajax4JSF Barbecue Commons BeanUtils Commons Configurations Facelets Hibernate Hibernate Annotations JAXB Jcaptcha JPA JSF JSFUnit Log4J MyFaces Core RichFaces Spring Spring Security Tomahawk Velocity URL commons.apache.org/beanutils/ jcaptcha.sourceforge.net/ de 25