Escolar Documentos
Profissional Documentos
Cultura Documentos
Pg. 1
Table of Contents Introduction Documentation Guide 1. Getting Started with Facelets 1.1. 1.2. 1.3. 1.4. Downloading Facelets Dependencies Directory Structure Project Setup 1.4.1. Web.xml Descriptor 1.4.2. Faces-Config.xml 1.5. The NumberBean 1.5.1. The Java Code 1.5.2. Faces Bean Descriptor 1.6. Creating Web Pages 1.6.1. The Page Template - template.xhtml 1.6.2. Configuring User Input - guess.xhtml 1.6.3. Displaying the Response - response.xhtml 1.7. Handling Navigation 1.8. Deployment 2. Configuration 2.1. Configuring JavaServer Faces 2.1.1. JavaServer Faces RI 2.1.2. Apache MyFaces 2.2. Web Application Descriptors 2.2.1. Initialization Parameters 2.2.2. Security 2.3. Logging 3. Tag Libraries 3.1. Using Tags 3.1.1. Tag Namespaces 3.1.2. Using 'jsfc' 3.1.3. Unresolved Namespaces 3.2. Available Tag Libraries 3.2.1. 3.2.2. 3.2.3. 3.2.4. JavaServer Faces Specification Templating Library JSTL Support Oracle ADF Faces
3.3. Functions 3.4. Loading Libraries 3.5. Creating Tag Libraries 3.5.1. Tag Library Schema
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 2
4. Expression Language 4.1. Inlining Text 4.2. EL Lifecycle 5. Templating and Re-Use 5.1. Template/Client Relationships 5.1.1. Wrapping Content within a Template 5.1.2. Piecemeal Content within a Template 5.1.3. Multi-Level Templating 5.2. <ui:component/> 5.3. <ui:composition/> 5.4. <ui:debug/> 5.5. <ui:decorate/> 5.6. <ui:define/> 5.7. <ui:fragment/> 5.8. <ui:include/> 5.9. <ui:insert/> 5.10. <ui:param/> 5.11. <ui:remove/> 5.12. <ui:repeat/> 6. Facelets Architecture 6.1. View Creation 6.2. Facelets API 6.2.1. FaceletFactory 6.2.2. Facelet 6.2.3. FaceletHandler 6.3. Document Compiler 7. Extending Facelets 7.1. Tag Development Overview 7.2. Custom TagHandlers 7.3. Meta Tags 7.3.1. Custom ComponentHandlers 7.3.2. Custom ValidateHandlers 7.3.3. Custom ConvertHandlers 7.4. FaceletViewHandler 7.5. Tag Decorators 8. Building Facelets 8.1. Using Ant 8.2. IDE Integration
Introduction
The web community is eagerly seeking a light-weight, templating framework backed by JavaServer Faces as the industry standard. While JavaServer Faces and JavaServer Pages technology (JSP) are meant to be aligned, Facelets steps outside of the JSP specification and provides a highly performant, JSF-centric view technology. Anyone who has created a JSP page will be able to do the same with Facelets and familiar XML-tag use. The difference is under the hood where all the burden of the JSP vendor API is removed to greatly enhance JSF as a platform and provide easy plug-and-go development without requiring JSP tag development. JavaServer Faces UIComponents are first class citizens within Facelets; there's no need to develop extra objects to integrate. There's also no need to learn yet another XML schema to define your views. Facelets includes many features such as: Works with JSF 1.1 and JSF 1.2, including Sun's RI and Apache MyFaces.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 3
Out of the box, Facelets provides full support for all components specified in the JavaServer Faces specification, including limited support for JSTL tags such as <c:forEach> and <c:if>. Where developers really gain an advantage with using Facelets is its ability to auto-wire additional artifacts to your XML documents such as UIComponents, Validators, and Converters. Facelets is a clean slate for correcting concerns with JSF. Templating, re-use, and ease of development are top priorities that will help bring developers on board with JSF as a suitable platform for large scale projects.
Documentation Guide
To get a jump start on development, this guide covers varying degrees of depth. Please follow these steps: Chapter 1, Getting Started with Facelets as an entry-level tutorial on using JavaServer Faces and Facelets together. All of the content in this section is generic to Faces with the exception of Section 1.6, Creating Web Pages. This section describes the simplest Facelets templating scenario that could possibly work. Chapter 2, Configuration for details on setting up your web application for use with Facelets. Chapter 3, Tag Libraries for incorporating JSF objects into Facelet documents as tags. Chapter 5, Templating and Re-Use to learn about how Facelets encourages templating and re-use in your documents. Chapter 6, Facelets Architecture as an overview to the Facelets API and compiler. Chapter 7, Extending Facelets as a starting point for extending Facelets functionality with custom tag handlers. Additional documentation and resources such as: mailing lists, forums, and announcements, are available on Facelets' home page at: http://facelets.dev.java.net
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 4
1.2. Dependencies
Facelets will work with both version 1.1 and 1.2 of JavaServer Faces and makes no bearing on the implementation used. Facelets also uses the new EL-API and again can be used with any implementation of that API. Please reference the table below to make sure your dependencies are available to Facelets: Table 1.1. Facelets Dependencies Project JavaServer Faces RI Build Req? No Included? Description The reference implementation of JSF 1.1 and JSF 1.2 are available for use with your application. The alternative to the JSF reference implementation. MyFaces currently implements the JSF 1.1 specification. JSF 1.2 API that works with the new EL Specification. This API is packaged with the JavaServer Faces RI and available on Java.net. The standardized EL specification that is standalone from JSP or JSF, but used by both frameworks. The reference implementation that is used by Facelets for handling EL. This dependency should not be an issue for most deployments as it's a standard part of web containers and JREs. Link http:// javaserverfaces.dev.java.net/
No
Apache MyFaces
No
No
http://myfaces.apache.org/
Yes
No
http:// javaserverfaces.dev.java.net/
EL API
Yes
Yes
http://glassfish.dev.java.net/
EL RI
No
Yes
http://glassfish.dev.java.net/
XML SAX
Yes
No
http://java.sun.com/xml/
For more information on using these projects: Those projects that are required to build Facelets, please see Chapter 8, Building Facelets. If you would like to use Apache MyFaces with Facelets, see Section 2.1.2, Apache MyFaces. To use Facelets with the JavaServer Faces Reference Implementation, see Section 2.1.1, JavaServer Faces RI.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 5
1.4.2. Faces-Config.xml
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 6
JavaServer Faces is extremely interoperable with other frameworks. Most of this flexibility lies in JSF's Application composite which includes: a default ActionListener, ELResolver, StateManager, NavigationHandler, and ViewHandler. Facelets is used as the application's ViewHandler, represented by the class com.sun.facelets.FaceletViewHandler. To configure JavaServer Faces to use Facelets as the ViewHandler, modify your project's faces-config.xml to specify the <view-handler> element: <faces-config> <application> <view-handler> com.sun.facelets.FaceletViewHandler </view-handler> </application> </faces-config> Even though there are other parts to the faces-config.xml needed for this tutorial, only the <view-handler> element is required for Facelets use.
public class NumberBean implements Serializable { protected final static Random rand = new Random(); protected protected protected protected int int int int min; max; guess; actual;
// Default Constructor public NumberBean() { this.min = 1; this.max = 10; } // called by JSF to validate user input public void validate(FacesContext context, UIComponent component, Object value) throws ValidatorException { // coerce the value to an int try { int param = Integer.parseInt(value.toString()); // validate param if (param > this.max || param < this.min) { FacesMessage msg = new FacesMessage("Guess must be between "+this.min+" and "+this.max); throw new ValidatorException(msg); } } catch (NumberFormatException e) { FacesMessage msg = new FacesMessage("Must be a number"); throw new ValidatorException(msg); } } // lazy generate our actual value public synchronized int getActual() { if (this.actual == 0) { this.actual = rand.nextInt(this.max-this.min); this.actual += this.min;
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 7
The above class should be compiled with Java and located at $DEPLOY_DIR/WEB-INF/classes/tutorial/NumberBean.class. If you do not know how to compile Java classes, please stop this tutorial and go to http://java.sun.com for introductory help.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 8
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 9
<ui:define name="body"> <h:form id="helloForm"> <h:inputText type="text" id="userNo" value="#{NumberBean.guess}" validator="#{NumberBean.validate}"/> <br/> <h:commandButton type="submit" id="submit" action="success" value="Submit" /> <br/> <h:message showSummary="true" showDetail="false" style="color: red; font-weight: bold;" id="errors1" for="userNo"/> </h:form> </ui:define> This text will not be displayed. </ui:composition> This text below will also not be displayed. </body> </html> 1. Using a <ui:composition> tag will trim everything outside of it. This means that you can create/edit your documents with a visual editor, but Facelets will only use what's between the <ui:composition> tags. 2. The <ui:composition> uses the template attribute to reference the template or look and feel of this page. 3. Two <ui:define> tags are specified with names that match the ones used in the template we had created. This means that when Facelets builds your page, those blocks of content will be placed appropriately in the template. Any text that happens to reside inside the <ui:composition> tag, but outside of the <ui:define> tags is not displayed in the rendered output. 4. Facelets also can use 'inlined' EL Expressions to make outputting dynamic content extremely easy. In the example above, #{NumberBean.max} will display the max property of the NumberBean in your session. EL expressions may also reside outside tag attributes, in the space between tags, but you must keep in mind that the result of evaluating the expression will only appear in the rendered output if template text in that same position would appear. If you have questions or do not understand the attributes used for <h:inputText>, <h:commandButton>, or <h:message>; documentation on those components are available at http://java.sun.com/j2ee/javaserverfaces. Keep in mind that Facelets uses the same attributes, behavior, and naming conventions as the tags specified for JavaServer Faces' JSP TLD documents.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 10
1.8. Deployment
Finally, you should be able to deploy all of these artifacts now to your web application. Your application should generate a random number and allow you to flip between your guess page and response page. To access your application, remember that the javax.faces.web.FacesServlet in your web.xml was mapped to *.jsf. To start your guessing fun, point your browser to http://localhost:8080/numberguess/guess.jsf (presuming you used the application name numberguess). If you have additional problems or questions, going to Facelet's home page at http://facelets.dev.java.net will provide you with additional resources such as forums, mailing lists, and additional documentation.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 11
Chapter 2. Configuration
facelets.LIBRARIES
/WEB-INF/facelets/foo.taglib.xml; /WEBINF/facelets/bar.taglib.xml
facelets.DECORATOR S
com.sun.facelets.tag.jsf.html.HtmlDecor ator
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 12
facelets.DEVELOPME NT
false
Setting this to true will cause the FaceletViewHandler to print out debug information in an easy to use screen when an error occurs during the rendering process. The buffer size to set on the response when the ResponseWriter is generated. By default the value is -1, which will not assign a buffer size on the response. This should be increased if you are using development mode in order to guarantee that the response isn't partially rendered when an error is generated. When a page is requested, what interval in seconds should the compiler check for changes. If you don't want the compiler to check for changes once the page is compiled, then use a value of -1. Setting a low refresh period helps during development to be able to edit pages in a running application.
true
facelets.BUFFER_ SIZE
-1
8192
facelets.REFRESH_ PERIOD
-1
facelets.RESOURCE_ RESOLVER
Optionally provide an alternate com.sun.facelets.impl.DefaultResourceReso ResourceResolver that will replace the lver default logic of allowing the FacesContext resolve the resource URL. A semicolon (;) delimitted list of resources that Facelets should use. If no resource paths are specified, Facelets will handle all requests (DEFAULT). If one or more paths are specified, Facelets will only use the ones specified, otherwise fall back on the parent or default ViewHandler (JSP). Note, this requires the FacesServlet in your web.xml to be mapped with a prefix for capturing multiple file types ex: / faces/*. A boolean value that tells the compiler to skip comments (default is true). Even if you comment out code in your page, the tags will not be compiled but expressions (EL) will be treated as if they were inlined-- still compiled and evaluated for output in the document. Skipping comments will remove all comments completely from the document.
my.company.IDEResourceResolver
facelets.VIEW_ MAPPINGS
/demos/*; *.xhtml
facelets.SKIP_ COMMENTS
true
false
2.2.2. Security
Java applications can restrict access to resources or pages by outside users. This feature is common to all application servers and part of the Servlet specification. Lets presume that you want to take advantage of developing simple Facelet XHTML documents that are viewable in your browser during development. When your application is deployed to production, you don't want anyone from the outside to access your XHTML documents unless they are served through the JavaServer Faces Servlet. <web-app> <!-- servlets and such would be above --> <security-constraint>
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 13
2.3. Logging
Facelets uses java.util.Logger for handling logging. This was done to reduce library dependencies while taking advantage of many Servlet container's ability to modify logging levels on the fly. For many, using the JDK 1.4 java.util.Logger will be new to them. You can read more on it at http://java.sun.com/j2se/1.4.2/docs/guide/util/ logging/index.html Table 2.2. Facelet Logger Names Name facelets.compiler Description For outputting debug information about the compilation process. This would include namespace resolution for TagLibraries and XML events. Most of the output will be FINE. Information about the inner workings of the FaceletFactory. Debug information that helps with component lifecycles in relation to Facelets. Will output view-id mapping/resolution and the states of your views.
For those who are currently developing a Facelets project and would like to have all the debug information available on both your application server and in your IDE; modify the logging.properties in your JRE/lib directory and add the following lines to the end of that file: facelets.level = FINEST # uncomment any of the below #facelets.compiler.level = SEVERE #facelets.tag.component.level = INFO #facelets.viewhandler.level = SEVERE
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 14
This tag library contains JavaServer Faces component tags for all UIComponent + HTML RenderKit Renderer combinations defined in the JavaServer Faces Specification.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 15
test
true
Table 3.3. <c:forEach/> Attribute Required? var items false false Description An optional expression variable to store the actual currently indexed value. An expression that evaluates to an indexable Collection, Array, or Map. Variable to bind an Object that describes the current indexed state. The Object has the following properties: first[boolean], last[boolean], begin[int], end[int], index[int], step[int]. Index the forEach should start at. Example employee #{empDao.employees}
varStatus
false
idx
begin
false
end
false
step
false
Table 3.4. <c:catch/> Attribute var Required? false Description An optional value to store the Exception Object exp Example
Table 3.5. <c:set/> (Avoid if Possible) Attribute Required? var true A variable to store the 'value' expression An expression that will be bound under the specified 'var' attribute. Anytime this 'var' shows up in other expression, this 'value' will be embeded in the succeeding expression. The example here would bind 'aList' as "the list within the map under the key 'listA'", NOT as a List Object. Every time 'aList' is used, it will evaluate the example expression to generate the instance. Description Example aList
value
true
#{listMap ['listA']}
A note about EL within this JSTL implementation. Since all set variables from these tags are backed by the new EL API, the only scope they can bind to is within the current FaceletContext, no others. This means that variables only can exist for the benefit of creating the component tree for JSF and do not work to assign variables in other scopes. The reason for this is that the Expressions are actually bound to the FaceletContext, not the evaluted Object. This is to better serve JSF tree creation.
3.3. Functions
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 16
Functions are declared within EL in the following format: #{fn:sizeOf(myCollection)}. What that line says is to reference the tag library using the prefix fn for a function named sizeOf. This syntax should feel similar to what's required for using tags from imported libraries. Any tag library can offer any amount of functions. Please reference the particular library's documentation for function names and parameters information.
As you can see, JSF entities are treated as first class citizens in Facelets' tag libraries. A couple things to observe from the schema above:
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 17
The definition of a tag library (including namespace) can be delegated to the class specified in the library-class element. The class specified must implement com.sun.facelets.tag.TagLibrary. This is useful if you would like to maintain your tag library in Java, but would like to have it automatically picked up by the compiler by placing an XML file in your Jar's meta-inf folder. Each document (not specified by library-class) requires a namespace element which will match the namespace used in your document, see Section 3.1.1, Tag Namespaces. The rest of the document is made up of tag and function elements. Tag elements require a tag-name and can take on different behavior depending on what you would like Facelets to handle for you. Functions can also be specified under the library's namespaces and follow the same signature as in JSP TLD files. The following sections describe how to integrate your objects within the XML tag library.
3.5.2. UIComponents
UIComponents can be auto-wired by using the component element in your tag library. <tag> <tag-name>bar</tag-name> <component> <component-type>com.mycompany.Data</component-type> <renderer-type>com.mycompany.Bar</renderer-type> </component> </tag> In the above example, we are binding a component of type (not Class) com.mycompany.Data to the tag name bar. A renderer-type is also provided, but not required since UIComponents can easily render themselves. Based on if your component implements ActionSource[2], ValueHolder, or EditableValueHolder, Facelets will take care of auto-wiring those standard attributes according to the specification. Facelets differs greatly from JSP in this important regard, and this difference is a feature of Facelets that takes advantage of the dynamism in JavaServer Faces that is wasted on JSP. Specifically, any tag attribute in a Facelets page is tolerated. If the value of the attribute is a ValueExpression, and tag is associated with a UIComponent, the expression is stored in the components's ValueExpression Map. Otherwise, Facelets looks for a JavaBeans property on the component whose name is equal to the tag attribute name. If it exists, its setter is called with the value of the tag attribute. If it doesn't exist, an entry is created in the generic attribute set for the component, the value of which is the value of the tag attribute. The upshot of all this is that turnaround time is greatly reduced because you can modify the component and/or renderer without having to change a TLD. Of course, the downside is that any attribute is legal, but errors in that regard are logged in the logging system. This approach exemplifies a general philosophy of Facelets, sensible default behavior from the perspective of the page developer. The attribute wiring behavior also applies to validators, EL expressions, converters, etc. Any additional properties on your component will also be wired for you too, just as JSP sets the properties on a JspTag. If you think that Facelets can't handle the special wiring your component needs, then skip to Section 7.3.1, Custom ComponentHandlers. If you've just created a UIComponent from scratch and you are not sure how to integrate it into JavaServer Faces, here's all the code you need: <faces-config> <component> <component-type>com.mycompany.Data</component-type> <component-class>com.mycompany.jsf.components.UIDataComponent</component-class> </component> </faces-config> Notice that the component-type matches the one used in the Facelets tag library XML. This degree of indirection by referencing components by type increases the maintainability and portability of JavaServer Faces components.
3.5.3. Validators
Validators can also be added to Facelets with the validator element. <tag> <tag-name>validateEmail</tag-name> <validator> <validator-id>faces.validator.Email</validator-id> </validator> </tag> Again, we reference JSF entities by type or id. Facelets will also take care of wiring attributes directly to your Validator by matching attribute name to property name. If you would like to provide special behavior or wire odd properties, you can jump ahead to Section 7.3.2, Custom ValidateHandlers.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 18
3.5.4. Converters
Converters can be registered with Facelets by adding a converter element. <tag> <tag-name>convertMoney</tag-name> <converter> <converter-id>faces.convert.Money</converter-id> </converter> </tag> Converters are referenced by id. Facelets will take care of wiring attributes directly to your Converter by matching attribute name to property name. If you would like to provide special behavior or wire odd properties, you can jump ahead to Section 7.3.3, Custom ConvertHandlers. If you've just written your own Converter, you can add it to your JSF Application with the following snippet in your faces-config.xml: <faces-config> <converter> <converter-id>faces.convert.Money</converter-id> <handler-class>com.mycompany.jsf.convert.ConvertMoney</handler-class> </converter> </faces-config>
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 19
All tags in a Facelets extend com.sun.facelets.tag.TagHandler which provides some base functionality for tying XML data to your Java code. To read more about creating custom tags, jump to Section 7.2, Custom TagHandlers.
4.2. EL Lifecycle
Facelets provides a unique lifecycle to EL. When building a UIComponent tree, all EL expressions are re-built based on the state of the current FaceletContext. These expressions are either stored on things like UIComponents or stored in the component tree as text. When it's time to render, then these expressions are evaluated as the second phase. This offers the truest form of variable/state management in relation to tree building within JavaServer Faces. This is also a feature that is not supported within JSP for inlined text.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 20
Any document can act as a template; but what makes a document a template? It just simply uses one or more <ui:insert/> tags to inject content from another source. The other half of the equation is the template client. This includes documents that use the <ui:component/>, <ui:composition/>, <ui:fragment/>, or <ui:decorate/>. Each of those tags is detailed in the sections below.
5.2. <ui:component/>
Table 5.1. Component Tag Attributes Attribute Required? id false Description A unique id may be provided, otherwise Facelets will automatically assign one under the same logic it uses for all UIComponents. This binding attribute is used the same as with any other UIComponent such that it allows you to reference them as a property of a JavaBean. If that target property did not have a UIComponent instance assigned already, JavaServer Faces will lazily create an instance for you and set it on your JavaBean before continuing with building the tree. Example mainMenu
binding
false
# {page.menu}
The component tag and the composition tag (below) behave exactly the same, except the component tag will insert a new UIComponent instance into the tree as the root of all the child components/fragments it has.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 21
Using the ability to use Tag files in your tag libraries, see Section 3.5.5, Tag (Source) Files, you could include the above component into your pages while having the attributes automatically made available as variables within the document above: ... <span id="header"> <my:mainMenu page="home" role="#{user.role}"/> </span> ... Pretty cool eh?
5.3. <ui:composition/>
Table 5.2. Composition Tag Attributes Attribute Required? template false Description The resolvable URI of the template to use. The content within the composition tag will be used in populating the template specified. Example /WEB-INF/templates/detaltemplate.xhtml
Facelets is founded on the idea of compositions. This means that a UIComponent tree can be defined in multiple Facelet pages and executed in part or whole. Some other frameworks, like Tapestry (http://jakarta.apache.org/tapestry), may define a single component within a page, Facelets instead marks the start of a branch of child UIComponents-- a composition if you will. Text before will be removed. <ui:composition> #{dynamic.text} <h:inputText id="myText" value="#{foo.bar}"/> </ui:composition> Text after will be removed. This means you can start a full XHTML document in your favorite visual tool with CSS definitions, but have Facelets trim everything outside of the <ui:composition/> tag. Here's a simple example of using a composition in separate document: ... <h:column> <ui:include src="/composition.xhtml"/> </h:column> ... Lets say this composition was included inside of a <h:column/> tag/component; it would gain two children based on the above example: # {dynamic.text} and the <h:inputText/>. The composition tag has templating abilities, to read more about how templating is coordinated, jump over to Section 5.6, <ui:define/> and Section 5.9, <ui:insert/>.
5.4. <ui:debug/>
Table 5.3. Debug Tag Attributes
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 22
Example d
The debug tag will capture the component tree and variables when it is encoded, storing the data for retrieval later. You may launch the debug window at any time from your browser by pressing 'CTRL' + 'SHIFT' + 'D' (by default). ... <ui:debug hotkey="d" rendered="#{initParam.debugMode}"/> </body> </html> ... In the above example, we use the hot key 'd' to launch the debug window. Creating debug output on every request adds some overhead, so you can use the UIComponent rendered property to turn debugging on or off based on some expression. In this example, debugging is backed by an entry in the web.xml. The debug tag doesn't need to be used with the facelet.DEVELOPMENT parameter. The best place to put this tag is in your site's main template where it can be enabled/disabled across your whole application. If your application uses multiple windows, you might want to assign different hot keys to each one.
5.5. <ui:decorate/>
Table 5.4. Decorate Tag Attributes Attribute Required? template true Description The resolvable URI of the template to use. The content within the decorate tag will be used in populating the template specified. Example /WEB-INF/templates/ sideBox.xhtml
The decorate tag acts the same as a composition tag, but it will not trim everything outside of it. This is useful in cases where you have a list of items in a document, which you would like to be decorated or framed. The sum of it all is that you can take any element in the document and decorate it with some external logic as provided by the template. Text before will stay. <ui:decorate template="/WEB-INF/templates/sideBox.xhtml"> <ui:define name="title">Product Search</ui:define> <ui:define name="body"> ... </ui:define> </ui:decorate> Text after will stay. In some cases, it would make sense to externalize your "Product Search" box into a separate file, in other cases it doesn't and the decorate tag allows you to inline as such. For more information on how templating works in relation to the <ui:define/> tags, see Section 5.6, <ui:define/>.
5.6. <ui:define/>
Table 5.5. Define Tag Attributes Attribute Required? name true Description The literal name for this definition. This name will match up with a <ui:insert/> tag in a target template. Example header
The define tag can be used within tags that allow templating. This includes composition and decorate tags. Text before will stay. <ui:decorate template="/WEB-INF/templates/sideBox.xhtml"> <ui:define name="title">Product Search</ui:define> <ui:define name="body"> ... </ui:define> </ui:decorate> Text after will stay.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 23
5.7. <ui:fragment/>
Table 5.6. Fragment Tag Attributes Attribute Required? id false Description A unique id may be provided, otherwise Facelets will automatically assign one under the same logic it uses for all UIComponents. This binding attribute is used the same as with any other UIComponent such that it allows you to reference them as a property of a JavaBean. If that target property did not have a UIComponent instance assigned already, JavaServer Faces will lazily create an instance for you and set it on your JavaBean before continuing with building the tree. Example mainMenu
binding
false
#{uiCache ['searchResults']}
Just like composition has decorate as a non-trimming version of the same behavior, component has fragment. This allows you to logically insert a UIComponent into the tree and possibly bind this fragment to a JavaBean property or Map for management. The Text above will be used. <ui:fragment binding="#{uiCache['searchResult']}"> <div id="searchResults"> ... </div> </ui:fragment> The Text below will be used. The fragment tag was also added to Facelets to get around some of the optimizations used in handling text within your document. If you are using components such as <f:panelGrid/>, which renders its children, you may want more control over the building process that Facelets does and using a fragment tag will help guarantee parent/child relationships for you.
5.8. <ui:include/>
Table 5.7. Include Tag Attributes Attribute Required? src true Description A literal or EL expression that specifies the target Facelet that you would like to include into your document. Example anotherPage.xhtml
This tag should be familiar to most. The include tag can point at any Facelet which might use the composition tag, component tag, or simply be straight XHTML/XML. It should be noted that the src path does allow relative path names, but they will always be resolved against the original Facelet requested. <span id="header"> <ui:include src="#{backingBean.headerSource}"/> </span> The include tag can be used in conjunction with multiple <ui:param/> tags to pass EL expressions/values to the target page. See Section 5.10, <ui:param/>, for more on passing variables to other pages.
5.9. <ui:insert/>
Table 5.8. Insert Tag Attributes Attribute Required? name false Description The optional name attribute matches the associated <ui:define/> tag in this template's client. If no name is specified, it's expected that the whole template client will be inserted. Example header
The insert tag is used within your templates to declare spots of replaceable data.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 24
As you can see, these insert tags indicate to the Facelets compiler where to insert content from the template client. If the template client doesn't specify content for the specified name, then the body of the ui:insert tag in the template is used.
5.10. <ui:param/>
Table 5.9. Param Tag Attributes Attribute name value Required? true true Description The name of the variable to pass to the included Facelet. The literal or EL expression value to assign to the named variable. user #{sessionScope.user} Example
From reading about Facelets templating, you've probably become familiar with passing fragments of content between pages. With the param tag, you can pass objects as variables instead of just fragments of content. You can use the param tag wherever a define tag is used within composition or decorate tags, in addition to passing objects to an include tag. <span id="leftNav"> <ui:include src="/WEB-INF/siteNav.xhtml"> <ui:param name="user" value="#{currentUser}"/> <ui:param name="page" value="home"/> </ui:include> </span> In the above example, when siteNav.xhtml is used, it will have user and page variables available for use which will reference the the currentUser object and the home string literal.
5.11. <ui:remove/>
The remove tag does not have any attributes and is used to remove chunks of XML content from a Facelet at compilation time. The remove tag is often used in conjunction with the jsfc feature, see Section 3.1.2, Using 'jsfc'. ... <ui:remove> This will be removed. </ui:remove> ... <span jsfc="ui:remove"> This won't be compiled either <h:outputText value="#{foo.bar}"/> </span> ... There are times in development when you need to quickly remove parts of the document just for testing purposes, or you would like to leave a 'templatemodel' in your document, but don't want it to be part of the final Facelet.
5.12. <ui:repeat/>
Table 5.10. Repeat Tag Attributes
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 25
The repeat tag should be used in almost all cases instead of the c:forEach to iterate over content with JSF. The repeat tag is often used in conjunction with the jsfc feature, see Section 3.1.2, Using 'jsfc'. ... <dl> <ui:repeat value="#{company.departments}" var="dept"> <dt>#{dept.name}</dt> <ui:repeat value="#{dept.employees}" var="emp"> <dd>#{emp.lastName}, #{emp.firstName}</dd> </ui:repeat> </ui:repeat> </dl> ... While this is a great step for JSF compositions, we can do better with the jsfc attribute where the repeat tag will provide some special behavior inclusive of the declared tag. ... <table> <tr jsfc="ui:repeat" value="#{dept.employees}" var="emp" class="#{emp.manager ? 'mngr' : 'peon'}"> <td>#{emp.lastName}</td><td>#{emp.firstName}</td> </tr> </table> ...
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 26
6.2.1. FaceletFactory
The FaceletFactory is an interface to the Facelet compiler while offering features such as caching and modification monitoring. FaceletFactory factory = FaceletFactory.getInstance(); Facelet facelet = factory.getFacelet("/example.xml");
6.2.2. Facelet
The Facelet class is similar to a lot of the Servlet API, such that it's stateless and can handle multiple threads accessing it at once. The Facelet's soul responsibility is to populate a tree of UIComponents for manipulation and, of course, rendering. A single instance is representative of physical XML resource, compiled into memory once and shared for all requests. FacesContext faces = FacesContext.getCurrentInstance(); Facelet facelet = factory.getFacelet("/example.xml"); facelet.apply(faces, faces.getViewRoot()); After 'applying' this Facelet to the UIViewRoot, it will be fully populated according to your various XHTML or XML pages used with the Facelets framework. Facelets delegate tree creation logic to an internal tree of FaceletHandlers constructed by the compiler. The action of passing UIComponents through the tree of FaceletHandlers causes the view to be populated in a UIComponent tree, reflective of the logic included in the FaceletHandlers.
6.2.3. FaceletHandler
The FaceletHandler is a part of a parent Facelet in a many to one association. FaceletHandlers work off of the visitor pattern where state is passed to them for modification and tree creation, then possibly passed along to the next FaceletHandler in the chain. public class LoggingHandler implements FaceletHandler public void apply(FaceletContext ctx, UIComponent parent) throws IOException, FacesException, FaceletException, ELException { Logger.getLogger("example").info("Hello Logger"); } } That example, while silly, shows the simple API that the FaceletHandler uses. If you would like to construct your own FaceletHandlers for use in UIComponent tree creation, jump over to Section 7.2, Custom TagHandlers.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 27
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 28
tagId
java.lang.String
A unique id, assigned at compilation time for this stateless element. This can be used in combination with the FaceletContext.generateUniqueId(String) to generate consistently unique ids for a given page evaluation. A Tag instance which is Facelet's representation of the element declared in a page. The Tag includes namespace/name information, along with accessors to the TagAttributes specified on the element declared in the page. A generic interface representing zero or more child tags and their associated handlers. Since Facelets uses stateless TagHandlers, the parent handler can evaluate the nextHandler any number of times or not at all to dictate component tree creation.
tag
com.sun.facelets.tag.Tag
nextHandler
com.sun.facelets.FaceletHandler
For more information on the inner workings of Facelets, please hop over to Chapter 6, Facelets Architecture.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 29
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 30
This is probably the best example of customization so far. The ConvertHandler allows you to override the method createConverter (FaceletContext) to return any Converter instance. Also, the setAttributes(FaceletContext,Object) was overridden to do special wiring for the Locale on the NumberConverter. The NumberConverter has many properties, but we only wanted to make a special case for locale, so we only tell the MetaRuleset to ignore that one attribute because we will take care of it ourselves.
7.4. FaceletViewHandler
Facelets comes with a ViewHandler that you may extend. Some extension points include initializing the compiler and setting up alternate response writers for JavaServer Faces to use. To learn more, look at the Facelets JavaDocs for the com.sun.facelets.FaceletViewHandler.
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07
Pg. 31
Compiles, then Jars Does the jar'ing and prepares/populates the dist directory Cleans or resets the project
https://facelets.dev.java.net/nonav/docs/dev/docbook.html
23/3/2009 20:42:07