VDL Documentation Generator - Generated Documentation

Tag Libraries 

Jakarta Faces Passthrough Elements Tag Library

The presence of an attribute from this namespace on an otherwise non-Faces aware markup element indicates that the markup element must be treated as a Faces component that will be rendered equivalently to what is specified directly in the Facelet page, with the added benefit of being associated with a server side UIComponent instance.

Please see the documentation for Java class jakarta.faces.view.facelets.TagDecorator.


Jakarta Faces Facelets Tag Library

The tags in this library add templating — a powerful view composition technique — to Faces. Templating is so useful that there are entire frameworks, such as Tiles and SiteMesh, that are built around the concept of templating. So what is templating, how can you benefit from it, and how does this tag library implement it?

If you've used Jakarta Server Pages before, you've probably used jsp:include. The prototypical example for jsp:include is a header on each page in a web application. One Jakarta Server Pages page, say header.jsp, encapsulates the header content, and the header is included by each page. You encapsulate and reuse content, so that changes to one file, header.jsp, affect the header on every page.

This tab library contains a tag —ui:include — that's analagous to jsp:include, but encapsulating and reusing content is only half the templating story, because templating also lets you encapsulate and reuse layout. You define a single template (meaning layout), and you reuse that template with multiple compositions. So now you can control the layout of many pages with a single template (layout). Let's take a look at an example.

A Templating Example

First, we define a template:

  1. <!DOCTYPE html>
  2. <html xmlns:ui="jakarta.faces.facelets">
  3.     <head>
  4.       <link href="styles.css" rel="stylesheet" type="text/css"/>
  5.       <title><ui:insert name="title">Default Title</ui:insert></title>
  6.     </head>
  8.     <body>
  9.       <ui:debug/>
  10.       <div class="heading">
  11.         <ui:insert name="heading"/>
  12.       </div>
  14.       <div class="content">
  15.         <ui:insert name="content"/>
  16.       </div>
  17.     </body>
  18. </html>

In the preceeding listing, we've defined a layout, also known as a template. That template uses the ui:insert tag to insert pieces of a page — namely, title, heading, and content — defined in a composition. Notice that on line 8, we define a default title, in case one isn't provided by the composition. Also note that on line 12 we have the ui:debug tag, which lets the user activate a popup window with debugging information by typing CTRL + Shift + d.

The title, heading, and content pieces of the page referenced in the template are defined in a separate XHTML file in a composition, like this:

  1. <!DOCTYPE html>
  2. <html xmlns:ui="jakarta.faces.facelets">
  3.   <body>
  4.     <ui:composition template="/layout.xhtml">
  6.       <ui:define name="title">A List of Contacts</ui:define>
  7.       <ui:define name="heading">Contacts</ui:define>
  9.       <ui:define name="content">
  10.         <ui:include src="contactsTable.xhtml" />
  11.       </ui:define>
  13.     </ui:composition>
  14.   </body>
  15. </html>

At runtime, Faces synthesizes the two previous XHTML pages to create a single Faces view by inserting the pieces defined in the composition into the template (that template is layout.xhtml, which is the first listing above). Faces also disregards everything outside of the composition tag so that we don't wind up with two body elements in the view. Also, note that we use the ui:include tag on line 14 to include content (which happens to be a table) from another XHTML page, so that we can reuse that table in other views.

So why do we have two XHTML pages to define a single view? Why not simply take the pieces and manually insert them into the layout so that we have only a single XHTML page? The answer is simple: we have separated layout from the content so that we can reuse that layout among multiple compositions. For example, now we can define another composition that uses the same layout:

  1. <!DOCTYPE html>
  2. <html xmlns:ui="jakarta.faces.facelets">
  3.   <body>
  4.     <ui:composition template="/layout.xhtml">
  6.       <ui:define name="title">Create a Contact</ui:define>
  7.       <ui:define name="heading">Create Contact</ui:define>
  9.       <ui:define name="content">
  10.         <ui:include src="createContactForm.xhtml"/>
  11.       </ui:define>
  13.     </ui:composition>
  14.   </body>
  15. </html>

By encapsulating the layout, we can reuse that layout among multiple compositions. Just like ui:include lets us encapsulate and reuse conent, Faces compositions let us encapsulate and reuse layout, so that changes to a single layout can affect multiple views. Fundamentally, that's what this tag library is all about.


Jakarta Faces Core Tag Library

The core Jakarta Faces tags that are independent of any particular RenderKit.


Jakarta Faces HTML Tag Library

This tag library contains Jakarta Faces component tags for all UIComponent + HTML RenderKit Renderer combinations as defined in section 9.5 "Standard HTML RenderKit Tag Library" of the Jakarta Faces Specification Document.


Jakarta Faces Passthrough Attributes Tag Library

Facelet tag attributes in this namespace must be added to the pass through attribute map on the UIComponent corresponding to the facelet tag. There are no tags in this tag library.

Usage example

<h:outputText value="Namespaced Attributes" p:foo="bar" />

Would cause <span foo="bar">Namespaced Attributes</span> to be rendered.


Jakarta Faces Composite Components Tag Library

Describes the tag library used for declaring and defining the usage contract for composite UI Components. When authoring a composite component, use of this tag library is largely optional, though always recommended. Declaring and defining a composite component with this taglib provides valuable information about the component that can be used by tools and users of the composite component. In most cases, a composite component can be authored without declaring and defining its usage contract with this taglib.

Creating a Composite Component

A composite component is declared by creating a Facelets file inside of a resource library. (See section 2.6 "Resource Handling" of the Jakarta Faces Specification Document for more information about resource libraries.) A composite component must reside within a resource library. It is not possible to create a composite component without putting it inside of a resource library.

The default XML namespace URI of the taglib that contains the composite component, for use in the using page, is jakarta.faces.composite/<composite-library-name>, where <composite-library-name> is the name of the resource library. For example:

<!DOCTYPE html>
<html xmlns:ui="jakarta.faces.facelets"

This declares that any Facelets file in the resource library called ezcomp can be used as a regular Faces UI component in a view with the above namespace declaration by using the "ez" prefix. For example, placing a file called foo.xhtml in a resource library called ezcomp would make that file accessible like this.

<ez:foo />

The implementation must also support declaring the namespace of the tag library in a Faces VDL tag library descriptor. This descriptor file is optional and is useful for component vendors that do not want to use the default XML namespace. This version of the proposal currently uses the facelet taglib descriptor syntax. For example:

<facelet-taglib id="ez">

Components from that taglibrary may be used in a using page by declaring them in the XML namespace for that view:

<!DOCTYPE html>
<html xmlns:ui="jakarta.faces.facelets"

Below is an example of a fairly involved composite component declaration. Such a declaration might appear in foo.xhtml.

  1. <cc:interface name="foo"
  2.               displayName="Very Simple Login Panel"
  3.               preferred="true"
  4.               expert="false"
  5.               shortDescription="An illustration of the composite component feature">
  6.   <cc:attribute name="model" required="true">
  7.     <cc:attribute name="loginAction" required="true" method-signature="java.lang.Object action()"/ >
  8.   </cc:attribute>
  9.   <cc:attribute name="valueChangeListener" targets="username" />
  10.   <cc:attribute name="specialMethodExpression"
  11.                        method-signature="com.foo.User validateCurrentUser()" />
  12.   <cc:attribute name="loginButtonLabel" default="Login" />
  13.   <cc:editableValueHolder name="username" />
  14.   <cc:actionSource name="loginEvent" />
  15.   <cc:actionSource name="cancelEvent" />
  16.   <cc:actionSource name="allEvents" targets="loginEvent cancelEvent" />
  17. </cc:interface>
  18.   <ui:decorate template="fooTemplate.xhtml">
  19.     <ui:define name="header">
  20.       <p>This is the login panel header</p>
  21.     </ui:define>
  22.     <ui:define name="body">
  23.       <p>
  24.          <h:inputText id="username" />
  25.       </p>
  26.       <p>
  27.         <h:commandButton id="loginEvent"
  28.                          value="#{cc.attrs.loginButtonLabel}">
  29.         </h:commandButton>
  30.         <h:commandButton id="cancelEvent" value="Cancel" action="cancel">
  31.         </h:commandButton>
  32.         <special:validateUserButton
  33.           validateUser="#{cc.attrs.specialMethodExpression}" />
  34.       </p>
  35.     </ui:define>
  36.     <ui:define name="footer">
  37.      <p>This is the login panel footer</p>
  38.     </ui:define>
  39.   </ui:decorate>
  40. </cc:implementation>

The values for attributes in a composite component VDL file can be fully localized by putting them inside a ResourceBundle in the same directory as the VDL view and accessing them with the per-component resource bundle syntax. Consider the file foo.xhtml, in the resource library ezcomp. The shortDescription element could be changed to be:

<cc:interface shortDescription="#{cc.resourceBundleMap.shortDescription}" >

In this case, In the same ezcomp directory as foo.xhtml, there would be a foo.properties file that would contain this entry:

shortDescription=A really nifty login panel.

The normal localization rules for ResourceBundle would apply.

Refer to the composite tag for the details of defining the interface and implementation for composite components.


Jakarta Tags Core Tag Library


Jakarta Tags Functions Tag Library

Comments to: faces-dev@eclipse.org.
Copyright © 2019, 2022 Eclipse Foundation. All rights reserved.
Use is subject to license terms.