Posted by
edburns on October 15, 2009 at 12:47 PM PDT
The following topics and more will be covered in detail in my
upcoming book with Neil Griffin, JavaServer Faces 2.0: The Complete
Reference. Please enjoy this early access content!
One challenging aspect of designing JSF 2.0 was how to standardize
Facelets. We wanted to standardize only the minimum amount that would
still allow developers get the job done. Initially, we did not include
binary custom tag handlers in the standard because most users of
Facelets were simply using it to declare pages of existing UI
components. Andy
Schwartz and others advocated for the inclusion of a custom tag
handler feature in the standard but I didn't want to just standardize
what Jacob had initially done.
While Jacob's initial work for custom tag handlers was certainly
effective, EG discussions with Ken Paulsen, creator of the JSFTemplating View
Declaration Language led the EG to conclude that the standardization
work for some of Facelets would best be left to JSF 2.1. In
particular, Ken and EG member Imre Oßwald came up with something
they called View Abstract Syntax Tree that would handle deeper aspects
of Faces templating that they felt solved some of the flaws in the
implementation of Facelets. Rather than overspecify, we came up with a
simpler solution that still enables the most common usecases for custom
tag handlers.
First, let's take a look at the custom.taglib.xml file. The manner
and location for this file is exactly the same as before. In this
example, (available in the Mojarra
svn repo), the file lives at
WEB-INF/classes/META-INF/custom.taglib.xml.
<?xml version="1.0" encoding="UTF-8"?>
<facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-facelettaglibrary_2_0.xsd"
version="2.0">
<namespace>http://mojarra.dev.java.net/custom</namespace>
<tag>
<tag-name>custom1</tag-name>
<component>
<component-type>javax.faces.Input</component-type>
<renderer-type>javax.faces.Text</renderer-type>
<handler-class>com.sun.faces.facelets.custom.CustomComponentHandler1</handler-class>
</component>
</tag>
</facelet-taglib>
The java code for this class is shown next. At right, you see the
stack trace for a breakpoint set on line 8.
package com.sun.faces.facelets.custom;
import javax.faces.view.facelets.ComponentConfig;
import javax.faces.view.facelets.ComponentHandler;
public class CustomComponentHandler1 extends ComponentHandler {
public CustomComponentHandler1(ComponentConfig config) {
super(config);
}
}
The preceding code does nothing. But it's a start. Particurlarly
useful is that ComponentConfig
argument. This gives you access to a whole bunch of useful stuff. Note
also that extends javax.faces.view.facelets.ComponentHandler.
There are handlers for all the kinds of tags in JSF: converter,
validator, component, and behavior.
In many cases, the only reason people were doing custom Facelet tags
was so they could be notified when the component is built. To get this
in JSF 2.0, just override the onComponentCreated()
method, as shown in the next class.
package com.sun.faces.facelets.custom;
import javax.faces.component.UIComponent;
import javax.faces.view.facelets.ComponentConfig;
import javax.faces.view.facelets.ComponentHandler;
import javax.faces.view.facelets.FaceletContext;
public class CustomComponentHandler2 extends ComponentHandler {
public CustomComponentHandler2(ComponentConfig config) {
super(config);
}
@Override
public void onComponentCreated(FaceletContext ctx, UIComponent c, UIComponent parent) {
super.onComponentCreated(ctx, c, parent);
}
@Override
public void onComponentPopulated(FaceletContext ctx, UIComponent c, UIComponent parent) {
super.onComponentPopulated(ctx, c, parent);
}
}
The stack traces for onComponentCreated and
onComponentPopulated are here
and here,
respectively.
If you really must have access to the apply method, and
indeed override it, you can still do so. However, to preserve a clean
separation between interface and implementation there is a little extra
syntatic sugar you must endure. Sorry. Here's the code for a custom
tag handler that overrides apply() and
createMetaRuleset(). The stack trace for
apply() is shown at left, while the one for
createMetaRuleset() is available here.
package com.sun.faces.facelets.custom;
import java.io.IOException;
import javax.faces.component.UIComponent;
import javax.faces.view.facelets.ComponentConfig;
import javax.faces.view.facelets.ComponentHandler;
import javax.faces.view.facelets.FaceletContext;
import javax.faces.view.facelets.MetaRuleset;
import javax.faces.view.facelets.TagHandlerDelegate;
public class CustomComponentHandler3 extends ComponentHandler {
public CustomComponentHandler3(ComponentConfig config) {
super(config);
}
@Override
public void onComponentCreated(FaceletContext ctx, UIComponent c, UIComponent parent) {
super.onComponentCreated(ctx, c, parent);
}
@Override
public void onComponentPopulated(FaceletContext ctx, UIComponent c, UIComponent parent) {
super.onComponentPopulated(ctx, c, parent);
}
@Override
protected TagHandlerDelegate getTagHandlerDelegate() {
final TagHandlerDelegate parent = super.getTagHandlerDelegate();
TagHandlerDelegate result = new TagHandlerDelegate() {
@Override
public MetaRuleset createMetaRuleset(Class type) {
return parent.createMetaRuleset(type);
}
@Override
public void apply
(FaceletContext ctx, UIComponent comp
) throws IOException { parent.apply(ctx, comp);
}
};
return result;
}
}
As mentioned previously, there are handlers for all the different
kinds of JSF artifacts that may appear in a Facelet page. The syntax in
the .taglib.xml file is rather similar for all of them, but
the one for the validator is shown next.
<tag>
<tag-name>validator</tag-name>
<validator>
<validator-id>javax.faces.Required</validator-id>
<handler-class>com.sun.faces.facelets.custom.CustomValidatorHandler</handler-class>
</validator>
</tag>
Finally, here's the code for this custom validator.
package com.sun.faces.facelets.custom;
import java.io.IOException;
import javax.faces.component.UIComponent;
import javax.faces.view.facelets.FaceletContext;
import javax.faces.view.facelets.MetaRuleset;
import javax.faces.view.facelets.TagHandlerDelegate;
import javax.faces.view.facelets.ValidatorConfig;
import javax.faces.view.facelets.ValidatorHandler;
public class CustomValidatorHandler extends ValidatorHandler {
public CustomValidatorHandler(ValidatorConfig config) {
super(config);
}
@Override
protected TagHandlerDelegate getTagHandlerDelegate() {
final TagHandlerDelegate parent = super.getTagHandlerDelegate();
TagHandlerDelegate result = new TagHandlerDelegate() {
@Override
public MetaRuleset createMetaRuleset(Class type) {
return parent.createMetaRuleset(type);
}
@Override
public void apply
(FaceletContext ctx, UIComponent comp
) throws IOException { parent.apply(ctx, comp);
}
};
return result;
}
}
The callstacks for apply() and
createMetaRuleset() are here
and here
80% of the time, there is no need for any custom tag handlers. If
you're doing your job right, the logic should be in the UIComponent,
Validator, Converter, etc. However, for that extra 20% of the time, you
can use the above practices to get the job done.
Technorati Tags: edburns
