Guía para personalizar un control RichFaces

No solo es importante contar con controles JSF potentes y robustos, la importancia de la apariencia visual es fundamental al construir aplicaciones web. El diseño de una aplicación JSF debe tener como objetivo crear una experiencia de usuario satisfactoria.

Es importante conocer a fondo las capacidades de cada control de interfaz para aprovechar todas las ventajas que proporcione y evitar así el retrabajo.

RichFaces proporciona un mecanismo muy potente de customización de controles: los skins.

Skins de RichFaces

RichFaces proporciona 8 combinaciones de colores pre-definidas (skins): DEFAULT, emeraldTown, blueSky, wine, japanCherry, ruby, classic y deepMarine. Pueden verse directamente en la página de Demo de controles RichFaces.

Para utilizar alguno de los skins de RichFaces es necesario indicar en el archivo web.xml el identificador del skin que se desee. Por ejemplo, para utilizar el color verde se añade en el web.xml lo siguiente:

<context-param>
    <param-name>org.richfaces.SKIN</param-name>
    <param-value>emeraldTown</param-value>
</context-param>

La mayor ventaja de utilizar un skin es que, sin una sola línea de maquetación CSS, es posible cambiar la estética de toda la aplicación, por ejemplo si se cambia el param-value indicado en el archivo web.xml de emeraldTown a japanCherry, la aplicación ya no será de color verde sino en tonos rosas y rojos.

Skin de MADEJA

El jar skinMadeja-1.0.jar es un archivo externo que permite que una aplicación JSF desarrollada con RichFaces tenga la combinación de colores MADEJA.

El objetivo de la creación de este skin, no es meramente estético, sino de mantenibilidad, ya que evitando estilos dispersos por toda la aplicación se reduce el tiempo invertido en cambiar la apariencia general de la aplicación y se propicia a generar una imagen uniforme en todas las aplicaciones de un determinado tipo.

Configuración del skin MADEJA

El jar skinMadeja-1.0.jar deberá ser incluido en la carpeta WEB-INF/lib de la aplicación.

En el archivo web.xml se debe indicar el nombre skinMadeja como se muestra a continuación:

<context-param>
  <param-name>org.richfaces.SKIN</param-name>
  <param-value></param-value>
 </context-param>

Si se requiere que la aplicación cambie de skin en caliente, deberá crearse un bean que gestione el nombre del skin en uso e indicarse en el param-value, por ejemplo #{skinBean.skin}.

El bean que gestiona el cambio del skin en caliente está configurado en el archivo faces-config.xml de la siguiente manera:

<managed-bean>
  <description>Bean que controla la combinacion de colores presentada</description>
  <managed-bean-name>skinBean</managed-bean-name>
  <managed-bean-class>es.juntadeandalucia.cice.jsf.SkinBean</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>
  <managed-property>
   <property-name>skin</property-name>
   <value>skinMadeja</value>
  </managed-property>
 </managed-bean>

Adicionalmente, debe indicarse en el archivo web.xml que RichFaces será el encargado de "maquetar" los controles JSF estándar, con el siguiente parámetro:

<context-param>
  <param-name>org.richfaces.CONTROL_SKINNING</param-name>
  <param-value>enable</param-value>
 </context-param>

Modificar el estilo mediante el archivo .properties

El archivo skinMadeja.properties que se encuentra en la ruta skinMadeja-1.0.jar/META-INF/skins se indican los nombres y valores de las propiedades que internamente RichFaces utiliza para maquetar sus componentes.

Contiene los atributos como colores, fuente, tamaño del texto y grosor de los bordes que pueden ser modificados, estos cambios serán aplicables de manera generalizada en todos los controles que utilicen esa propiedad. Por ejemplo, si es modificado el atributo tableBackgroundColor, todas las tablas tendrán por defecto el color indicado en el archivo skinMadeja.properties.

Se muestra a continuación un fragmento del archivo skinMadeja.skin.properties:

#Colores headers
headerBackgroundColor=#6C9FBE
headerGradientColor=#F2F7FF
headerTextColor=#FFFFFF
headerWeightFont=bold

#Color background
generalBackgroundColor=#F3F2F2

#Propiedades texto
generalTextColor=#000000
generalSizeFont=11px
generalFamilyFont=Arial, Verdana, sans-serif 
...

Por ejemplo, el control de calendario rich:calendar utiliza las propiedades panelBorderColor, generalSizeFont, generalFamilyFont, headerBackgroundColor indicadas en el archivo skinMadeja.skin.properties, como estilo de las diferentes partes que le conforman.

La documentación de RichFaces es muy completa en lo referente a la customización de cada control de interfaz. En cada uno de los controles existe un apartado Skin Parameters Redefinition que indica las propiedades del archivo .properties que se utiliza para el estilo de cada control.

Modificar el estilo redefiniendo la clase CSS del tipo rich-nombrecontrol-parte

En la documentación de RichFaces, en la sección Definition of Custom Style Classes de cada control, se muestran una o varias imágenes indicando los nombres de las clases CSS de cada parte que conforma el control de interfaz. La nomenclatura de las clases CSS es estándar, del tipo rich-nombrecontrol-parte. Por ejemplo, la imagen que se muestra a continuación:

El nombre de la clase CSS que identifica el estilo asignado al encabezado del calendario donde se muestra la etiqueta del mes es rich-calendar-header, esta clase CSS en el código HTML generado es la siguiente:

.rich-calendar-header{
    background-color:#EAF0F8;
    border-bottom-color:#C0C0C0;
    font-family:Arial,Verdana,sans-serif;
    font-size:11px;
}

Por lo que, en caso de requerir una apariencia distinta para el encabezado del mes, se debe redefinir la clase CSS rich-calendar-header.
Si se redefine en la hoja de estilos que utiliza toda la aplicación, entonces todos los componentes calendario de tipo rich:calendar cogeran ese estilo.

En caso de que solo se requiera modificar la apariencia visual del calendario de una página en particular, únicamente será necesario redefinir el estilo rich-calendar-header en esa página.

Modificar el estilo mediante las propiedades style y styleClass

Todos los controles de JSF tienen dos atributos para la maquetación del control de interfaz: style y styleClass Esta es la manera más sencilla de cambiar la apariencia visual de un control.

Con el atributo style se indica el estilo requerido en el formato CSS estándar del tipo propiedad:valor;. Por ejemplo:

<h:outputText value="Texto mini" style="font-size: 8;font-family: arial">
</h:outputText>

Con el atributo styleClass se indica la clase CSS que se desea aplicar al control de interfaz. Esta clase ha sido previamente definida en la hoja de estilos utilizada por la aplicación o en la misma página XHTML. Por ejemplo:

<rich:toolBar styleClass="barraHerramientasAmarilla">
</rich:toolBar>

Modificar el estilo mediante los atributos específicos de cada control

Existen controles que, al estar conformados por varias partes, proporcionan atributos específicos para dar estilo a cada una de sus partes.

Es decir, hay varios controles de RichFaces que, además de tener los atributos style y styleClass, tienen atributos específicos para cada parte del control de interfaz de usuario.

Por ejemplo, para un combo se puede especificar el nombre de la clase CSS para la apariencia cuando está deshabilitado o inactivo, también se puede especificar el nombre de la clase CSS para la apariencia de la lista desplegable o de cada uno de los elementos de esa lista. Todos estos atributos están disponibles en la documentación de RichFaces.

A continuación se muestran los atributos para modificar la apariencia visual del control rich:comboBox:

buttonClass
buttonDisabledClass
buttonInactiveClass
inputClass
inputInactiveClass
inputDisabledClass
itemClass
listClass

Por lo que el control podría customizarse indicándolo directamente en la página XHTML de la siguiente forma:

<rich:comboBox buttonClass="botonNaranja" inputClass="textoAzul"
 listClass="listaFondoGris" />

Así mismo el control rich:dataTable tiene los siguientes atributos para modificar la apariencia visual del encabezado, pie, filas y columnas de la tabla:

captionClass
columnClasses
footerClass
headerClass
rowClasses

Es importante conocer los atributos que el control de interfaz en si mismo ofrece para modificar la apariencia visual de sus diferentes partes. De esta manera, el cambio de algún detalle particular será mucho más sencillo. La lista de atributos disponibles por cada control se encuentra en la documentación de RichFaces, por lo que es recomendable consultarla previamente.

Modificar el estilo mediante XCSS

RichFaces utiliza el mecanismo de XCSS. Es una versión XML de las hojas de estilo CSS tradicionales, una orientación a objetos de las clases CSS para crear una estructura y reutilizar estilos.

Mediante las hojas XCSS es posible maquetar la aplicación de una manera mucho más compleja, utilizando los selectores de XCSS para el nombre de la clase que se desee modificar. Por ejemplo utilizando el selector rich-panel-header y definiendo que el atributo background-color sea el mismo que está indicado en el archivo .properties en la propiedad headerBackgroundColor, de la siguiente manera:

<u:selector name=".rich-panel-header">
    <u:style name="background-color"  skin="headerBackgroundColor" />
    <u:style name="color"             skin="headerTextColor" />
</u:selector>

Por lo que el estilo que se aplicará a los encabezados de los páneles será la siguiente:

.rich-panel-header {
    background-color: #6C9FBE;
    color: #FFFFFF;
}

Con XCSS es posible maquetar la aplicación de una manera mucho más compleja. Por ejemplo, el siguiente fragmento de la hoja calendar.xcss:

<u:selector name=".rich-calendar-month">
        <u:style name="background-position" value="0% 50%" />
        <u:style name="background-image">
            <f:resource f:key="org.richfaces.renderkit.html.CustomizeableGradient">
                <f:attribute name="valign" value="middle" />                
                <f:attribute name="gradientHeight" value="36px" />
                <f:attribute name="baseColor" skin="headerBackgroundColor" />
            </f:resource>
        </u:style>
    </u:selector>

En la documentación de RichFaces, en la sección Definition of Custom Style Classes de cada control, se muestran una o varias imágenes indicando los nombres de las clases CSS de cada parte que conforma el control de interfaz, este nombre será el que se debe utilizar como nombre del selector en las hojas XCSS.