ui

Tag Library Information 
InfoValue
ID (tag prefix)ui
URIhttp://xmlns.jcp.org/jsf/facelets
Tag Summary 
TagDescription
component

This tag is the same as ui:composition, except for two things: Faces creates a component and adds it directly to the tree, and there's no associated template.

Use this tag to create a component and specify a filename for the component as either the source of a ui:include, or the source of a Facelets tag.

composition

Defines a composition that optionally uses a template, as outlined in the description of the ui tag library. Multiple compositions can use the same template, thus encapsulating and reusing layout. Faces disregards everything outside of the composition, which lets developers embed compositions in well-formed XHTML pages that can be viewed in an XHTML viewer, such as Dreamweaver or a browser, without including extraneous elements such as head and body.

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  2.         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3.  
  4. <html xmlns="http://www.w3.org/1999/xhtml"
  5.    xmlns:ui="http://xmlns.jcp.org/jsf/facelets">
  6.  
  7.   <body>
  8.  
  9.     THIS LINE, AND EVERYTHING ABOVE IT IS DISREGARDED BY Faces
  10.     <ui:composition template="/layout.xhtml">
  11.  
  12.       <ui:define name="title">#{msgs.contactsWindowTitle}</ui:define>
  13.       <ui:define name="heading">#{msgs.contactsHeading}</ui:define>
  14.  
  15.       <ui:define name="content">
  16.         <ui:include src="contactsTable.xhtml" />
  17.       </ui:define>
  18.          
  19.     </ui:composition>
  20.     THIS LINE, AND EVERYTHING BELOW IT IS DISREGARDED BY Faces
  21.  
  22.   </body>
  23. </html>
debug

When the ui:debug tag is placed in an XHTML page, it creates a component and adds it to the component tree. That debug component captures debugging information, namely the current state of the component tree and the scoped variables in the application, when the component is rendered. If the user presses CTRL + SHIFT + d, Faces opens a window that shows the debugging information captured by the debug component.

Typically, the best place to put the ui:debug tag is in an application's main template, which lets developers enable or disable viewing of debugging information in one central location. Additionally, page authors can change the hotkey (which by default is CTRL + SHIFT + d, where the d stands for debug) to CTRL + SHIFT + ?, where ? represents the key specified as the value of the hotkey attribute.

You can use the rendered attribute to control whether the debug component is rendered. Using an EL expression as the value for the rendered attribute lets you control whether debug output is enabled for multiple views based on a single bean property.

Note ui:debug only works when the ProjectStage is set to Development.

define

The define tag defines content that is inserted into a page by a template. The define tag can be used inside ui:composition, ui:component, ui:decorate, and ui:fragment tags.

Content defined by the define tag can be inserted into a page by using ui:insert.

decorate

The decorate tag is identical to the composition tag, except that ui:decorate, unlike ui:composition, does not disregard all content outside of the tag. The decorate is useful when you want to decorate some content in a page, for example, you might want to decorate a list of items, like this:

  1. <ui:decorate template="/layout.xhtml">
  2.   <ui:define name="listHeading">
  3.     <ui:include src="shared/listHeading.xhtml"/>
  4.   </ui:define>
  5.        
  6.   <c:forEach items="#{items}" var="item">
  7.     ...
  8.   </c:forEach>
  9.   ...
  10. </ui:decorate>

Because Faces does not disregard everything outside of the ui:decorate tag, ui:decorate can be used to decorate pieces of a page.
fragment

The fragment tag is identical to the component tag, except that ui:fragment, unlike ui:component, Faces does not disregard all content outside of the tag.

include

Use this tag —which is very similar to JSP's jsp:include — to encapsulate and reuse content among multiple XHTML pages. There are three things this tag can include: plain XHTML, and XHTML pages that have either a composition tag or a component tag.

You supply a filename, through ui:include's src attribute for Faces to include. That filename is relative to the XHTML file that was rendered as a result of the last request. So, for example, if Faces loaded the view login.xhtml, and that file included pageDecorations/header.xhtml, and pageDecorations/header.xhtml included companyLogo.xhtml, then companyLogo.xhtml will not be found if it's in the pageDecorations directory, because companyLogo.xhtml has to be in the same directory as login.xhtml.

insert

Inserts content into a template. That content is defined —with the ui:define tag — in either a ui:composition, ui:component, ui:decorate, or ui:fragment.

param

Use this tag to pass parameters to an included file (using ui:include), or a template (linked to either a composition or decorator). Embed ui:param tags in either ui:include, ui:composition, or ui:decorate to pass the parameters.

repeat

Use this tag as an alternative to h:dataTable or c:forEach, especially when you are using the jsfc feature of Facelets. You can specify this component as the value of the jsfc attribute, like this: <div... jsfc="ui:repeat" value="#{contacts}" var="contact">...

remove

Remove content from a page. This tag is often used in conjunction with the jsfc feature of Facelets, to wrap additional markup. When Facelets removes markup from a page by substituting markup items that have a jsfc attribute with the specified component, Facelets also removes anything in the page that is contained in a ui:remove tag.