All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.sun.faces.metadata.taglib.faces.facelets.taglib.xml Maven / Gradle / Ivy

Go to download 





    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. 
        
  2. <html xmlns:ui="jakarta.faces.facelets">
    3. 

        
  3.     <head>
    4. 
        
  4.      
        <link
        href="styles.css"
        rel="stylesheet"
        type="text/css"/>
    5. 

        
  5.      
        <title><ui:insert
        name="title">Default Title</ui:insert></title>
    6. 
        
  6.     </head>
    7. 

        
  7.  
    8. 
        
  8.     <body>
    9. 
        
  9.      
        <ui:debug/>
    10. 
        
  10.      
        <div
        class="heading">
    11. 

        
  11.      
          <ui:insert
        name="heading"/>
    12. 
        
  12.      
        </div>
    13. 
        
  13.  
    14. 

        
  14.      
        <div
        class="content">
    15. 
        
  15.      
          <ui:insert
        name="content"/>
    16. 

        
  16.      
        </div>
    17. 
        
  17.     </body>
    18. 
        
  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. 
        
  2. <html xmlns:ui="jakarta.faces.facelets">
    3. 

        
  3.   <body>
    4. 
        
  4.     <ui:composition
        template="/layout.xhtml">
    5. 
        
  5.  
    6. 
        
  6.      
        <ui:define
        name="title">A List of Contacts</ui:define>
    7. 

        
  7.      
        <ui:define
        name="heading">Contacts</ui:define>
    8. 
        
  8.  
    9. 
        
  9.      
        <ui:define
        name="content">
    10. 

        
  10.      
          <ui:include
        src="contactsTable.xhtml"
        />
    11. 
        
  11.      
        </ui:define>
    12. 

        
  12.      
           
    13. 
        
  13.     </ui:composition>
    14. 
        
  14.   </body>
    15. 
        
  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. 
        
  2. <html xmlns:ui="jakarta.faces.facelets">
    3. 

        
  3.   <body>
    4. 
        
  4.     <ui:composition
        template="/layout.xhtml">
    5. 

        
  5.  
    6. 

        
  6.      
        <ui:define
        name="title">Create a Contact</ui:define>
    7. 

        
  7.      
        <ui:define
        name="heading">Create Contact</ui:define>
    8. 

        
  8.  
    9. 
        
  9.      
        <ui:define
        name="content">
    10. 
        
  10.      
          <ui:include
        src="createContactForm.xhtml"/>
    11. 

        
  11.      
        </ui:define>
    12. 

        
  12.  
    13. 

        
  13.     </ui:composition>
    14. 
        
  14.   </body>
    15. 
        
  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.facelets
    
        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.
  


        ]]>
        component
        com.sun.faces.facelets.tag.ui.ComponentRefHandler
        
            
                

                The identifier of the component that Faces inserts into the
                component tree. If an identifier is
                not explicitly specified by the page author, Faces will assign an
                identifier based on the algorithm
                that it uses for all components.
]]> id false java.lang.String

Binds the component to a backing bean property, as specified in section 3.1.5 "Component Bindings" of the Jakarta Faces Specification Document. The Java language type of this property must be a class that extends jakarta.faces.component.UIComponent. The scope of the bean on which this property resides must be no wider than request scope. If either of these conditions are not met, the results are undefined.

]]> binding false java.lang.String

Controls whether the component is rendered. Valid values for this attribute are either the strings "true" or "false" or an EL expression that evaluates to either "true" or "false".

If this attribute's value is "false" or the value is an EL expression that evaluates to "false", the component is not rendered in the page.

]]> rendered false boolean

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>
  2. <html xmlns:ui="jakarta.faces.facelets">
  3.   <body>
  4.  
  5.     THIS LINE, AND EVERYTHING ABOVE IT IS DISREGARDED BY FACELETS
  6.     <ui:composition template="/layout.xhtml">
  7.  
  8.       <ui:define name="title">#{msgs.contactsWindowTitle}</ui:define>
  9.       <ui:define name="heading">#{msgs.contactsHeading}</ui:define>
  10.  
  11.       <ui:define name="content">
  12.         <ui:include src="contactsTable.xhtml" />
  13.       </ui:define>
  14.          
  15.     </ui:composition>
  16.     THIS LINE, AND EVERYTHING BELOW IT IS DISREGARDED BY FACELETS
  17.  
  18.   </body>
  19. </html>
]]> composition com.sun.faces.facelets.tag.ui.CompositionHandler

A URI that points to a template, also known as a layout, that inserts pieces of the page defined in the composition. If the URI cannot be resolved a TagAttributeException must be thrown, including accurate location information to help the page author resolve the problem. When the template is intended to come from a resource library contract, the value of this attribute must be an absolute path starting with "/".

]]> template false java.lang.String

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.

]]> debug com.sun.faces.facelets.tag.ui.UIDebug

Defines a single character, that, pressed in conjunction with CTRL and SHIFT, will display the Faces debug window. By default, the hotkey is 'd'. The value for the hotkey attribute cannot be an EL expression.

]]> hotkey false java.lang.String

Controls whether the debug component is rendered. Valid values for this attribute are either the strings "true" or "false" or an EL expression that evaluates to either "true" or "false".

If this attribute's value is "false" or the value is an EL expression that evaluates to "false", the debug component is not rendered in the page, the hotkey attribute is disregarded, and users cannot open the debugging information window with a hotkey.

]]> rendered false java.lang.String

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.

]]> define com.sun.faces.facelets.tag.ui.DefineHandler

Assigns a name to the content inside a define tag. That name is used by corresponding ui:insert tags in a template that insert the named content into a page.

]]> name true java.lang.String

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" xmlns:ui="jakarta.faces.facelets">
  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. ]]> decorate com.sun.faces.facelets.tag.ui.DecorateHandler A URI that points to a template, also known as a layout, that inserts pieces of the page defined in the decorator. If the URI cannot be resolved a TagAttributeException must be thrown, including accurate location information to help the page author resolve the problem. When the template is intended to come from a resource library contract, the value of this attribute must be an absolute path starting with "/". ]]> template false java.lang.String

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.

]]> fragment com.sun.faces.facelets.tag.ui.ComponentRefHandler The identifier of the component that Faces inserts into the component tree. If an identifier is not explicitly specified by the page author, Faces will assign an identifier based on the algorithm that it uses for all components. ]]> id false java.lang.String

Binds the component to a backing bean property, as specified in section 3.1.5 "Component Bindings" of the Jakarta Faces Specification Document. The Java language type of this property must be a class that extends jakarta.faces.component.UIComponent. The scope of the bean on which this property resides must be no wider than request scope. If either of these conditions are not met, the results are undefined.

]]> binding false java.lang.String

Controls whether the fragment component is rendered. Valid values for this attribute are either the strings "true" or "false" or an EL expression that evaluates to either "true" or "false".

If this attribute's value is "false" or the value is an EL expression that evaluates to "false", the fragment is not rendered in the page.

]]> rendered false java.lang.String

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.

]]> include com.sun.faces.facelets.tag.ui.IncludeHandler The filename of an XHTML page to include. The filename is relative to the XHTML page that was originally loaded. When the included file is intended to come from a resource library contract, the value of this attribute must be an absolute path starting with "/".

]]> src true java.lang.String

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.

]]> insert com.sun.faces.facelets.tag.ui.IncludeHandler 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. ]]> name false java.lang.String

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. ]]> param com.sun.faces.facelets.tag.ui.ParamHandler The name of the parameter. ]]> name true java.lang.String The value of the parameter. Notice that this attribute's value can be an EL expression, which means that you can pass objects to either an included file or a template. ]]> value true java.lang.String

Use this tag as an alternative to h:dataTable or c:forEach

]]> repeat com.sun.faces.facelets.tag.ui.RepeatHandler

If value specified: Iteration begins at the item located at the specified index. First item of the collection has index 0. If value not specified: Iteration begins with index set at the specified value.

]]> begin false int

If value specified: Iteration ends at the item located at the specified index (inclusive). If value not specified: Iteration ends when index reaches the specified value (inclusive).

]]> end false int

Read-write property setting the offset from the beginning of the collection from which to start the iteration. If not set, this offset is not considered and iteration will start at the beginning of the collection.

]]> offset false int

Read-write property setting the size of the collection to iterate. If this value is less than the actual size of the collection, a FacesException must be thrown.

]]> size false int

Iteration will only process every step items of the collection, starting with the first one.

]]> step false int

The name of a collection of items that this tag iterates over. The collection may be a List, array, java.sql.ResultSet, java.lang.Iterable, java.util.Map or an individual java Object. If the collection is null, this tag does nothing.

]]> value true java.lang.Object

Name of the exported scoped variable for the current item of the iteration. This scoped variable has nested visibility.

]]> var true java.lang.String

Name of the exported request scoped variable for the status of the iteration. The object the name points to is a POJO with the following read-only JavaBeans properties. This scoped variable has nested visibility.

begin of type Integer

end of type Integer

index of type int

step of type Integer

even of type boolean

odd of type boolean

first of type boolean

last of type boolean

]]> varStatus false java.lang.String

Controls whether the repeat component is rendered. Valid values for this attribute are either the strings "true" or "false" or an EL expression that evaluates to either "true" or "false".

If this attribute's value is "false" or the value is an EL expression that evaluates to "false", the repeat is not rendered in the page.

]]> rendered false java.lang.String

Remove content from a page.

]]> remove com.sun.faces.facelets.tag.ui.SchemaCompliantRemoveHandler



© 2015 - 2024 Weber Informatics LLC | Privacy Policy