« ADF Faces RC: How to programmatically add an event listener to a dynamically created component | Main | ADF Faces RC: refreshing a table UI from a contextual event »
Custom skins deployment strategies for MyFaces Trinidad and ADF Faces Rich Client
By frank.nimphius | February 6, 2008
The skinning article of the developer guide on MyFaces Trinidad is the best document to start with if you are interested in learning what skinning is and how to use skins. Skinning is a unique feature for JavaServer Faces in ADF Faces and MyFaces Trinidad to define a custom look and feel for web applications without changes required to the application sources. Because ADF Faces RC is based on MyFaces Trinidad, and because ADF Faces of JDeveloper 10.1.3 will be replaced with Trinidad in JDeveloper 11, the mentioned document is good to use for all skinners to start with. The term "skinner" is used to identify a person that builds custom skins for a web application - truly a rock star if he/she is doing her job right.
The developer guide explains one option to deploy custom skins with a Trinidad web application, which is to bundle the skin sources and configuration files with the application to deploy. This works in that the skinner creates a subdirectory under the public_html directory of the Viewlayer project to place CSS and image resources into. The WEB-INF directory then will have a trinidad-skin.xml file added that contains the skin name and CSS reference, as well as an entry in the trinidad-config.xml file that contains the name of the skin to use when running the application.
A better deployment solution for a custom skin is only mentioned in the developer guide (at lest until the developer guide gets updated). As a skinner you may want to look for an option to store skin definitions in a Java Archive file (JAR) and then simply add it to the deployed application. The benefit of a JAR file approach,compared to the bundled version, is that
- A skin can be deployed and developed separately from the application. This also helps to reduce the number of files that need to be checked in case that some changes need to be applied to the skin. Foremost however, using a skin definition contained in a JAR file improves consistency in the look and feel
- Skin definitions and images can be within their own jar files, allowing developers to partition the image base into jar file, so that no all files need to be deployed with all applications
To deploy a skin in a JAR file, there are three rules to follow:
- The trinidad-skin.xml file that defines the skin and that references the CSS file must be within the META-INF directory
- All image resources and CSS files too must be under the META-INF directory. The images - and this is important - must be in a directory that starts with an "adf" root directory or any directory name that is mapped in the web.xml file for the resource servlet.
- Place the JAR file in the WEB-INF/lib directory of the ViewLayer project of the application to deploy (or use a shared library on the application server level)
-
<servlet-mapping>
-
<servlet-name>resources</servlet-name>
-
<url-pattern>/adf/*</url-pattern>
-
</servlet-mapping>
-
-
<servlet-mapping>
-
<servlet-name>resources</servlet-name>
-
<url-pattern>/afr/*</url-pattern>
-
</servlet-mapping>
Image: resource servlet mappings
To deploy a skin in a JAR file
Create a directory structure similar to the following
-
c:\temp\META-INF\adf\oracle\skin\images
-
META-INF\skins\oracleblaf.css
-
META-INF\trinidad-skins.xml
The images directory contains all the images used within the oracleblaf.css skin. Note that the directory in the META-INF directory starts with "adf". The CSS reference to the images looks e.g.
-
af|inputColor::swatch-overlay-icon:rtl {
-
content:url(../adf/oracle/skin/images/cfsortl.gif);
-
width: 12; height: 12;
-
left:-7px;
-
position:relative;
-
right:-7px;
-
top:5px;
-
}
Note the leading ".." in front of the image path ../adf/oracle/skin/images/cfsortl.gif, which, starting from the META-INF\skin directory in which the CSS is located, goes one directory up in the hierarchy to start the search in the META-INF root.
The trinidad-skin.xml file that is located directly in the META-INF directory, contains the following content
-
<?xml version="1.0" encoding="ISO-8859-1"?>
-
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
-
<skin>
-
<id>oracleblaf.desktop</id>
-
<family>oracleblaf</family>
-
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
-
<style-sheet-name>skins/oracleblaf.css</style-sheet-name>
-
</skin>
-
</skins>
This defines the skin as oracleblaf.desktop in the oracleblaf familily. Note that the trinidad-skin.xml file can have more than one skin definition in it. The oraclebalf.css file (or your custom css file) is referenced from the style-sheet-name element.
To create a jar file from this issue the following command from c:\temp
jar -cvf customSkin.jar META-INF/
Copy the resulting customSkin.jar file to the WEB-INF/lib directory of the Trinidad or ADF Faces RC project. Once this is done, configure the trinidad-config.xml file located on the WEb-INF directory of the Trinidad or ADF Faces RC project.
-
<?xml version="1.0" encoding="windows-1252"?>
-
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
-
<skin-family>oracleblaf</skin-family>
-
</trinidad-config>
Note that the skin can be discovered at runtime as well so that there is no need to hardcode the skin family name. Instead e.g. the application user can select the skin to use from a list box in the application.
Note that if you use Oracle JDeveloper 11, the skin definition in the JAR file is not displayed in the visual editor of the Java IDE. You might see a message in the log window saying that the skin family couldn't be found. Don't worry about this message.
Frank
Topics: ADF Faces RC, Trinidad | No Comments »
Comments are closed.
