Академический Документы
Профессиональный Документы
Культура Документы
Table of Contents
Introduction
Getting started
Configuration
PrimeFaces integration
BootsFaces integration
OmniFaces integration
Release Notes
Migration
ButterFaces
What is ButterFaces?
YAJF - yet another JSF Framework. There are a lot of JSF frameworks like RichFaces or
PrimeFaces. Most of them bring a lot of features and they feel like fat clients. ButterFaces is
a lightweight JSF framework bringing a lot of nice features to JSF with beeing minimal
invasive. Easy to use and easy to extend by custom features.
ButterFaces is a JSF 2 component enrichment framework. It wrappes most of default JSF 2
components and adds labels, readonly-views, tooltips, placeholder, validation style class
marker and other nice features to the standard JSF 2 components.
Why ButterFaces?
It is simple: Because everything tastes better with butter. Plain JSF brings a lot of
components but if you want to use them they are naked. There are no labels for input
components, no tooltips except of titles and html5 is not supported. If you want to create a
template supporting input and output components you have to implement both types of
components.
ButterFaces creates a simple html structure based on twitters bootstrap around existing JSF
components. You do not have already use bootstrap in your project - it comes with
ButterFaces. And if you do not want to use bootstrap styles or you have your own version
you can disable it easily by configuring it in your web.xml.
Introduction
ButterFaces
Getting started
Install ButterFaces as maven dependency
ButterFaces is accessible by maven central repository. Add following dependency to use
components for each JSF implementation (i.e. MyFaces)
<dependency>
<groupId>de.larmic.butterfaces</groupId>
<artifactId>components</artifactId>
<version>2.0.0</version>
</dependency>
In pre 2.0.0 versions of ButterFaces some components are only supported by mojarra. In
this case use following dependency
<dependency>
<groupId>de.larmic.butterfaces</groupId>
<artifactId>components-mojarra</artifactId>
<version>2.0.0.CR1</version>
</dependency>
Using ButterFaces
Add http://butterfaces.org/components to your <html .../> and use <!DOCTYPE html> to
activate html 5 features.
HINT with version 2.0.0 web.xml parameters has been renamed from de.larmic.butterfaces.x
to org.butterfaces.x
Getting started
ButterFaces
<!DOCTYPE html>
<html lang="en"
xmlns:h="http://xmlns.jcp.org/jsf/html"
xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
xmlns:b="http://butterfaces.org/components"
xmlns:f="http://xmlns.jcp.org/jsf/core">
...
<b:text id="test" ... />
</html>
That's all!
Getting started
ButterFaces
Configuration
This part contains the options to customize ButterFaces by editing web.xml .
Using of jQuery
Using of Bootstrap
Ajax configuration
Auto trim input fields
Max length text
Tree configuration
Resourcehandling
HINT with version 2.0.0 web.xml parameters has been renamed from de.larmic.butterfaces.x
to org.butterfaces.x
Using of jQuery
As default ButterFaces comes with an actual version of jQuery 2.x. To disable ButterFaces
jQuery version because of using your own version you have to change following parameter
<context-param>
<param-name>org.butterfaces.provideJQuery</param-name>
<param-value>false</param-value>
</context-param>
Using of Bootstrap
As default ButterFaces comes with an actual version of Bootstrap 3.x. To disable
ButterFaces Boostrap version because of using your own version you have to change
following parameter
<context-param>
<param-name>org.butterfaces.provideBootstrap</param-name>
<param-value>false</param-value>
</context-param>
Ajax configuration
Configuration
ButterFaces
(since 1.11.1)
b:commandLink components comes with ajaxDisableRenderRegionsOnRequest to
crossfade render regions while ajax request is running. To configure this for global usage
add following parameter
<context-param>
<param-name>org.butterfaces.ajaxDisableRenderRegionsOnRequest</param-name>
<param-value>false</param-value>
</context-param>
This can be useful if you are using b:waitingPanel to disable b:commandLink support and to
prevent multiple crossfade windows.
Tree configuration
(since 1.11.1)
Configuration
ButterFaces
b:tree and b:treeBox are trivial components and can be configured by components attribute
or by changeing following parameters
<context-param>
<param-name>org.butterfaces.noEntriesText</param-name>
<param-value>No matching entries...</param-value>
</context-param>
<context-param>
<param-name>org.butterfaces.spinnerText</param-name>
<param-value>Fetching data...</param-value>
</context-param>
Resourcehandling
Each components comes up with it's own javascript and css resources. If you want to use
ButterFaces resources (i.e. Bootstrap or jQuery) without any ButterFaces component use
b:activateLibraries to load all resources to html
<!DOCTYPE html>
<html lang="en"
xmlns:h="http://xmlns.jcp.org/jsf/html"
xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
xmlns:b="http://butterfaces.org/components"
xmlns:f="http://xmlns.jcp.org/jsf/core">
...
<b:activateLibraries />
</html>
This tags add javascript and css resources for all existing components. In addition to that
you may activate compression by web.xml
<context-param>
<param-name>org.butterfaces.useCompressedResources</param-name>
<param-value>true</param-value>
</context-param>
Configuration
ButterFaces
When using Development resource will always provided as non minified and compressed.
Likewise sourcemaps will be supplied to enable javascript debugging.
Configuration
ButterFaces
PrimeFaces integration
As well as ButterFaces PrimeFaces comes with jQuery. This does not work out of the box.
Problem
ButterFaces deliveres css and javascript as first part of html head to allow custom class
handling. PrimeFaces deliveres its own jQuery after ButterFaces, so ButterFaces jQuery
plugins does not work anymore.
Solution
You can add your own version of jQuery or use jQuery from ButterFaces. You have to
disable jQuery from PrimeFaces. Unfortunately you can not disable jQuery by a simple
web.xml parameter (like in ButterFaces), but you can remove it from head by a
javax.faces.event.SystemEventListener .
PrimeFaces integration
10
ButterFaces
package de.larmic.butterfaces.primefaces.event;
import javax.faces.component.UIComponent;
import javax.faces.component.UIViewRoot;
import javax.faces.context.FacesContext;
import javax.faces.event.AbortProcessingException;
import javax.faces.event.SystemEvent;
import javax.faces.event.SystemEventListener;
public class HandleResourceListener implements SystemEventListener {
public boolean isListenerForSource(Object source) {
return source instanceof UIViewRoot;
}
public void processEvent(SystemEvent event) throws AbortProcessingException {
final UIViewRoot source = (UIViewRoot) event.getSource();
final FacesContext context = FacesContext.getCurrentInstance();
for (UIComponent resource : source.getComponentResources(context, "head")) {
final String resourceLibrary = (String) resource.getAttributes().get("library"
final String resourceName = (String) resource.getAttributes().get("name");
if ("primefaces".equals(resourceLibrary) && "jquery/jquery.js".equals(resourceName)) {
source.removeComponentResource(context, resource);
}
}
}
}
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee
<application>
<system-event-listener>
<system-event-listener-class>de.larmic.butterfaces.primefaces.event.HandleResourceListene
<system-event-class>javax.faces.event.PreRenderViewEvent</system-event-class>
</system-event-listener>
</application>
</faces-config>
Code example
PrimeFaces integration
11
ButterFaces
PrimeFaces integration
12
ButterFaces
BootsFaces integration
As well as ButterFaces BootsFaces comes with jQuery and Bootstrap. This does not work
out of the box.
Problem
ButterFaces deliveres css and javascript as first part of html head to allow custom class
handling. BootsFaces deliveres its own jQuery after ButterFaces, so ButterFaces jQuery
plugins does not work anymore.
Solution
Disable jQuery in BootsFaces and most things will work
<context-param>
<param-name>net.bootsfaces.get_jquery_from_cdn</param-name>
<param-value>false</param-value>
</context-param>
Known problems
BootsFaces and ButterFaces override some Bootstrap style sheet. Sometimes they come in
the transverse, i.e. placeholder position in ButterFaces. We are working on that.
Code example
Take a look at https://github.com/ButterFaces/bootsfaces-integration
BootsFaces integration
13
ButterFaces
OmniFaces integration
Problem
There is no problem. Just use it in one application.
Code example
Take a look at https://github.com/ButterFaces/omnifaces-integration
OmniFaces integration
14
ButterFaces
Release Notes
This page contains the important feature changes.
Release Notes
15
ButterFaces
version
new stuff
2.1.1
2.1.1
2.1.0
2.0.0
2.0.0.CR1
1.11.1
1.11.0
1.10.5
1.10.4
1.9.14
1.9.13
1.9.0
1.8.4
1.7.13
Release Notes
16
ButterFaces
Migration
This page shows migration instructions if some ButterFaces version require it.
Migration
17
ButterFaces
from
version
to
version
what to do
2.0.0
1.9.15
1.9.8
1.8.17
1.9.0
1.8.7.1
1.8.8
2.0.0.CR1
1.9.14
1.9.6
1.8.5
1.8.6
1.8.4
1.8.5
1.7.21
1.8.2
1.7.16
1.7.17
1.7.12
1.7.13
Migration
18