The jQuery ThemeRoller provides various icons and corresponding style classes, but the number of icons is limited. If you need more icons, check out the Font Awesome project. (http://fortawesome.github.io/Font-Awesome). Font Awesome gives you hundreds of scalable vector icons that can be customized—size, color, drop shadow, and anything that can be done with the power of CSS. With a little effort, you are able to use many new icons in your JSF application in the same way that you use predefined icons from ThemeRoller.
In this recipe, we will learn step- by- step how to integrate additional icons from Font Awesome with PrimeFaces themes. We will develop an example with custom icons for buttons and links.
First of all, we need two dependencies in the pom.xml (two JAR files in the classpath)—one for the premade Font Awesome JAR created by the WebJars project (http://webjars.org) and one for the OmniFaces (http://omnifaces.org):
<dependency> <groupId>org.webjars</groupId> <artifactId>font-awesome</artifactId> <version>4.2.0</version> </dependency> <dependency> <groupId>org.omnifaces</groupId> <artifactId>omnifaces</artifactId> <version>1.8.1</version> </dependency>
The next steps are straightforward. Register
OmniFacess' UnmappedResourceHandler in faces-config.xml:
<application>
...
<resource-handler>
org.omnifaces.resourcehandler.UnmappedResourceHandler
</resource-handler>
</application>In web.xml, add /javax.faces.resource/* to FacesServlet URL-mapping:
<servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/javax.faces.resource/*</url-pattern> <url-pattern>*.jsf</url-pattern> </servlet-mapping>
And the following mime-type mappings:
<mime-mapping> <extension>eot</extension> <mime-type>application/vnd.ms-fontobject</mime-type> </mime-mapping> <mime-mapping> <extension>otf</extension> <mime-type>font/opentype</mime-type> </mime-mapping> <mime-mapping> <extension>ttf</extension> <mime-type>application/x-font-ttf</mime-type> </mime-mapping> <mime-mapping> <extension>woff</extension> <mime-type>application/x-font-woff</mime-type> </mime-mapping> <mime-mapping> <extension>svg</extension> <mime-type>image/svg+xml</mime-type> </mime-mapping> <mime-mapping> <extension>ico</extension> <mime-type>image/x-icon</mime-type> </mime-mapping>
The last step is including font-awesome.css from the Font Awesome JAR file, which is available via the Maven dependency:
<h:outputStylesheet name="webjars/font-awesome/4.2.0/css/font-awesome.css"/>
Let us now develop PrimeFaces buttons and links with some custom icons. All available icons can be viewed on the F
ont Awesome site at http://fontawesome.io/icons. The pattern for the icons' style class is always the same—fa fa-* where * is an icon name:
<p:commandButton value="Area Chart" icon="fa fa-area-chart"
style="margin-right:10px;"/>
<p:commandButton value="Bar Chart" icon="fa fa-bar-chart"/>
<p/>
<p:commandLink style="margin-right:15px;">
<i class="fa fa-linux"/>
<h:outputText value="Linux" style="margin-left:5px;"/>
</p:commandLink>
<p:commandLink>
<i class="fa fa-windows"/>
<h:outputText value="Windows" style="margin-left:5px;"/>
</p:commandLink>
<p/>
<p:selectBooleanButton onLabel="Bus" offLabel="Taxi"
onIcon="fa fa-bus" offIcon="fa fa-taxi"
style="width:80px"/>
<style type="text/css">
.ui-icon.fa {
text-indent: 0;
margin-top: -6px;
}
</style>The result looks as follows:
.
WebJars are client-side web libraries packaged into JAR files. The project structure inside a JAR file is compatible with the JSF resource identifier format. OmniFaces' UnmappedResourceHandler is typically needed to manage the JSF resource handling in third-party CSS files, such as font-awesome.css. Third-party files normally contain relative URLs to images and don't have #{resource[...]} to activate the JSF 2 facility for resources loading from JAR files. The UnmappedResourceHandler helps to load images by relative URLs in CSS files.
Setting text-indent to 0 pixels is required for overriding the PrimeFaces own ui-icon style {text-indent: -99999px}:
.ui-icon.fa {
text-indent: 0;
}PrimeFaces 5.1.1 (and upwards) bundles Font Awesome and provides the CSS tuning of components for the icons. Any component that provides an icon attribute such as a button or menu item can accept an icon from the Font Awesome project. In order to enable this feature, a context parameter in web.xml is required:
<context-param> <param-name>primefaces.FONT_AWESOME</param-name> <param-value>true</param-value> </context-param>
This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, build and deploy the WAR file on every Servlet 3.x compatible application server such as JBoss WildFly or Apache TomEE.
The showcase for the recipe is available at http://localhost:8080/pf-cookbook/views/chapter2/fontAwesome.jsf.