RUP Componente Feedback: documentación e infraestructura para mostrar mensajes de usuario
1. 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 – Feedback
Fecha: 22/11/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
2. Componentes RUP – Feedback iii/9
Control de documentación
Título de documento: Componentes RUP – Feedback
Histórico de versiones
Código: Versión: Fecha: Resumen de cambios:
1.0.0 06/06/2011 Primera versión.
1.0.1 18/07/2011
Correcciones en los números de versión de ficheros,
texto en la creació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.
2.0.0 11/07/2012 Cambios de formato y correcciones ortográficas.
2.1.0 18/09/2012
Actualización de las versiones de las librerías
JavaScript subyacentes.
2.4.0 22/11/2013
Se distribuye la versión minimizada de los ficheros
javascript y de estilos de RUP.
Cambios producidos desde la última versión
Se distribuye la versión minimizada de los ficheros javascript y de estilos de RUP.
Control de difusión
Responsable: Ander Martínez
Aprobado por:
Firma: Fecha:
Distribución:
Referencias de archivo
Autor:
Nombre archivo:
4. Componentes RUP – Feedback 5/9
1. Introducción
La descripción del Componente Feedback visto desde el punto de vista de RUP es la siguiente:
Se informa al usuario de cómo interactuar con los elementos de la aplicación y del resultado de
cualquier acción que realice o cualquier problema que tenga y de cómo solucionarlo.
2. Ejemplo
Se presentan a continuación un ejemplo del componente:
3. Casos de uso
Se recomienda el uso del componente:
• Cuando el usuario tenga una necesidad de información ya sea por cambios en el sistema, ejecución
de procesos, realización de tareas o confirmación de acciones.
En concreto, los principales tipos de feedback que tenemos que considerar son los siguientes:
• Mensajes de sistema o informativos
• Mensajes de confirmación
• Mensajes de error y aviso
• Feedback de formularios y edición
• Estado de un proceso
• Mensajes previos / previsualización
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.feedback-x.y.z.js
Ruta theme: rup/basic-theme/
Fichero css del theme: theme.rup.feedback-x.y.z.css
5. Componentes RUP – Feedback 6/9
4.2. Dependencias
Por la naturaleza de desarrollo de los componentes (patrones) como plugins basados en la librería
JavaScript jQuery, es necesaria la inclusión del esta. La versión elegida para el desarrollo ha sido la
versión 1.8.0.
• jQuery 1.8.0: http://jquery.com/
La gestión de la ciertas partes visuales de los componentes, se han realizado medieante 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.feedback-x.y.z.js
• theme.rup.feedback-x.y.z.css
4.3. Versión minimizada
A partir de la versión v2.4.0 se distribuye la versión minimizada de los componentes RUP. Estos ficheros
contienen la versión compactada y minimizada de los ficheros javascript y de estilos necesarios para el
uso de todos los compontente RUP.
Los ficheros minimizados de RUP son los siguientes:
• rup/scripts/min/rup.min-x.y.z.js
• rup/basic-theme/rup.min-x.y.z.css
Estos ficheros son los que deben utilizarse por las aplicaciones. Las versiones individuales de cada uno
de los componentes solo deberán de emplearse en tareas de desarrollo o depuración.
6. Componentes RUP – Feedback 7/9
5. Invocación
Este componente se aplica sobre una capa definida que tendrá como objeto el mostrar los mensajes al
usuario. Será labor del desarrollador definir dicha capa en su página y definir un identificador que se utilizará
en la invocación del componente.
$("#id_capa").rup_feedback(properties);
Donde el parámetro “properties” es un objeto (var properties = {}) o bien directamente la declaración de lo
valores directamente. Sus posibles valores se detallan en el siguiente apartado.
6. Parámetros
A continuación se muestran los posibles parámetros de configuración que recibe el componente.
• type: tipo del feedback, lo que indicará que imagen de las definidas por defecto se mostrará
(a la izquierda del texto). Los valores posibles son: ok, alert y error. En caso de no definir
tipo alguno no se mostrará imagen alguna. Valor por defecto null.
• message: mensaje que se mostrará en el feedback. Si no se define simplemente se creará
el objeto donde se mostrarán los mensajes.
• imgClass: estilo personalizado para la imagen a mostrar en el feedback. En caso de
definirse, no se tendrá en cuenta el tipo indicado en el parámetro type ya que deben
prevalecer los estilos definidos por el desarrollador frente a los estilos por defecto del
componente. Valor por defecto null. Un ejemplo de este estilo podría ser el siguiente:
.feedbackImgPruebas {
background-image: url("../images/feedbackImgPruebas.png");
background-repeat: no-repeat;
background-position: 8px 12px;
padding-bottom:1em;
padding-left:4.5em;
padding-right:0.5em;
padding-top:1em;
}
• delay: tiempo (en milisegundos) de espera hasta que se inicia la animación para hacer
desaparecer la capa. En caso de no definirse la capa no desaparecerá y su gestión
dependerá del desarrollador. Valor por defecto null.
• fadeSpeed: velocidad (en milisegundos) a la que se realiza la degradación de la capa hasta
su desaparición. Valores superiores indican animaciones más lentas, no más rápidas.
Depende directamente de la declaración del parámetro delay ya que si no existe animación
no tiene sentido este parámetro y en caso de definirse el delay pero no el fadeSpeed se
tomará el valor por defecto 400. Internamente se invoca a la función fadeOut de jQuery.
Valor por defecto null.
• gotoTop: booleano que determina si cuando se muestre el feedback se debe desplazar la
página hasta la parte superior de la misma, ya que normalmente los mensajes se suelen
mostrar ahí. Valor por defecto true.
7. Componentes RUP – Feedback 8/9
• block: booleano que indica si la capa que contendrá el mensaje de feedback debe tener o
no un espacio fijo en la pantalla. Este parámetro establece el atributo de estilo (css) display
con los valores block (true) o none (false). Valor por defecto true.
• closeLink: booleano que indica si la capa de feedback tendrá un enlace para que el usuario
de la aplicación pueda cerrar la capa manualmente. Valor por defecto true.
Un ejemplo de una definición de un componente feedback podría ser la siguiente:
var properties = {
type: "ok",
delay: 500,
fadeSpeed: 600,
gotoTop: false,
block: false,
closeLink: true
}
$("#id_capa").rup_feedback (properties);
7. Funciones
A continuación se detallan las diferentes funciones que integran el componente feedback:
• destroy: elimina las modificaciones realizadas sobre la capa para convertirla en feedback volviendo
a ser una simple capa. La invocación se realizará de la siguiente manera:
$("#id_capa").rup_feedback("destroy");
• set (msg, type, imgClass): establece el texto (msg) a mostrar en el feedback, que podrá ser tanto
texto plano como html. En caso de sólo definirse el parámetro msg, se mostrará como imagen
aquella definida anteriormente ya sea de un tipo por defecto o de una imagen con estilo
personalizado (si es que se había definido). En caso de que se envíe el parámetro type informado
de modificará la capa para mostrar la imagen por defecto asociada al tipo, borrando algún posible
estilos personalizado establecido anteriormente. Por último para realizar el cambio a un estilo
personalizado se pasará como parámetro type null y como imgClass la clase con el estilo a
establecer. Se muestran unos ejemplos para facilitar la comprensión:
o Feedback simple (usando configuración anterior):
$("#id_capa").rup_feedback("set","Texto a mostrar");
o Feedback cambiando a imagen de un tipo por defecto (Ej. error):
$("#id_capa").rup_feedback("set", "...", "error");
o Feedback estableciendo un estilo personalizado:
$("#id_capa").rup_feedback("set", "...", null, "imgPropio");
• hide (delay, fadeSpeed): oculta la capa del feedback con una animación. Si no se definen los
parámetros se tomaran los definidos con anterioridad (creación del feedback por ejemplo) o si no los
valores por defecto (null, null) que implica una animación sin espera con una “velocidad” de 400 ms.
La invocación de la función se realizará de la siguiente manera:
8. Componentes RUP – Feedback 9/9
o Tomando valores anteriores o por defecto (si no se han definido):
$("#id_capa").rup_feedback("hide");
o Definiendo valores nuevos:
$("#id_capa").rup_feedback("hide", 500, 600);
• close: oculta la capa del feedback sin animación alguna. Esta función será invocada por el enlace
de cierre (parámetro closeLink) en caso de que se muestre. La invocación de la función se realizará
de la siguiente manera:
$("#id_capa").rup_feedback("close");
• show: muesta la capa del feedback. Esta función será invocada automáticamente cada vez que se
invoque la función set(…) La invocación de la función se realizará de la siguiente manera:
$("#id_capa").rup_feedback("show");
• option: permite cambiar las propiedades definidas en el feedback. Puede invocarase antes que la
funcion set(…) para modificar cualquiera de los parámetros del mensaje a mostar: icono, imagen
personalizada, tiempo de espera hasta desaparecer… La invocación de la función se realizará de la
siguiente manera:
o Feedback cambio propiedad simple:
$("#id_capa").rup_feedback("option","closeLink", false);
o Feedback cambio varias propiedades:
$("#id_capa").rup_feedback("option", properties);
8. Sobreescritura del theme
El componente feedback se presenta con una apariencia visual definida en el fichero de estilos
theme.rup.feedback-x.y.z.css.
Si se quiere modificar la apariencia del componente, se recomienda redefinir el/los estilos necesarios en un
fichero de estilos propio de la aplicación situado dentro del proyecto de estáticos
(codAppStatics/WebContent/codApp/styles).
Los estilos del componente se basan en los estilos básicos de los widgets de jQuery UI, con lo que los
cambios que se realicen sobre su fichero de estilos manualmente o mediante el uso de la herramienta
Theme Roller podrán tener repercusión sobre todos los componentes que compartan esos mismos estilos
(pudiendo ser el nivel de repercusión general o ajustado a un subconjunto de componentes).
A continuación se muestran unas capturas del componente con los estilos asociados dependiendo del uso
de imágenes. Los estilos que contengan la palabra “ui-“ son los propios de jQuery UI que en caso de ser
necesario serán sobrescritos y no se comentarán en este documento por no ser su ámbito.
Feedback con imagen por defecto (type: ok) con cierre:
9. Componentes RUP – Feedback 10/9
• .rup-feedback: estilo asociado a la capa del feedback
• .rup-feedback_image: estilo asociado a la imagen por defecto (valores generales ej. posición).
• .rup-feedback_image_ok: imagen según type. Varia entre: _ok, _alert, _error (url a imágenes).
• .rup-feedback_closeLink: div que contiene el cierre de la capa (enlace e imagen)
Feedback con imagen de estilo personalizado (type: ok) sin cierre:
• .rup-feedback: estilo asociado a la capa del feedback
• .feedbackImgPruebas: estilo personal para mostrar la imagen personalizada. Se define en la hoja de
estilos propia de la aplicación en este caso en x21a.css.
9. Integración con UDA
No aplica.