JSF2 Composite Component Metadata - No Fluff Just Stuff
NFJS2026

JSF2 Composite Component Metadata

Posted by: Ed Burns on September 2, 2009

This ultra-quick blog entry shows how to use the JSF runtime to access metadata for a composite component. Note that most of the metadata is optional when creating a composite component, therefore, this entry will be of interest to tool vendors and those wishing to write composite components that stand a chance of showing up nicely in tools.

The Using Page

When showing a composite component demo, I always like to start out with the using page.

Listing 1: the using page

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  2. <html xmlns="http://www.w3.org/1999/xhtml"
  3.      xmlns:h="http://java.sun.com/jsf/html"
  4.      xmlns:f="http://java.sun.com/jsf/core"
  5.      xmlns:my="http://java.sun.com/jsf/composite/cc"
  6.      xmlns:meta="http://mojarra.dev.java.net/cc-metadata">
  7. <h:head>
  8.   <title>A Simple JavaServer Faces 2.0 View</title>
  9. <style type="text/css">
  10. .grayBox { padding: 8px; margin: 10px 0; border: 1px solid #CCC; background-color: #f9f9f9;  }
  12.  
  13. </h:head>
  14. <h:body>
  15.   <h:form>
  16.  
  17.     <p>Composite Component usage:</p>
  18.  
  19. <div id="cc" class="grayBox" style="border: 1px solid #090;">
  20. <my:myComponent loginAction="#{userBean.loginAction}" />
  21. </div>
  22.  
  23. <h2>Metada for This Composite Component</h2>
  24.  
  25. <div id="foo" class="grayBox" style="border: 1px solid #090;">
  26.     <pre>
  27.     <meta:printMetadata viewName="main.xhtml" libraryName="cc"
  28.                        resourceName="myComponent.xhtml"/>
  29.     </pre>
  30. </div>
  31.  
  32.  
  33.     <p><h:commandButton value="submit" /></p>
  34.   </h:form>
  35. </h:body>
  36. </html>
  37.  

Line 5 declares the namespace “my” using the handy composite component namespace prefix “http://java.sun.com/jsf/composite” followed by “cc”. JSF 2 interprets this to mean: treat any .xhtml files in the directory /resources/cc as a JSF composite component.

Line 6 declares a Facelet custom tag library with the namespace “http://mojarra.dev.java.net/cc-metadata”.

Line 20 uses the composite component named “myComponent” in the “cc” library.

Line 27 uses the “printMetadata” component from the Facelet custom tag library. We must pass in the name of a Facelet page, the library name, and the resource name.

The Composite Component

Let's examine the composite component itself. As I mentioned earlier, most of this metadata is optional and is included here just to show what the system understands. This component has just about every kind of metadata that is in the JSF2 spec.

Listing 2 the composite component

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  2. <html xmlns="http://www.w3.org/1999/xhtml"
  3.      xmlns:h="http://java.sun.com/jsf/html"
  4.      xmlns:f="http://java.sun.com/jsf/core"
  5.      xmlns:ui="http://java.sun.com/jsf/facelets"
  6.      xmlns:fmd="http://java.sun.com/xml/ns/javaee/faces/design-time-metadata"
  7.      xmlns:cc="http://java.sun.com/jsf/composite">
  9.  
  10. <title>Not present in rendered output</title>
  11.  
  12. </head>
  13.  
  15.  
  16. <cc:interface
  17.    name="component"
  18.    displayName="A really fancy composite component"
  19.    expert="true"
  20.    hidden="false"
  21.    preferred="true"
  22.    shortDescription="This component has all the supported metadata."
  23.    extraTopLevelAttribute="Whatever I want here">
  24.  
  25. <!-- start top level attributes -->
  26.  
  27.   <cc:attribute
  28.    name="model"
  29.    required="true"
  30.    displayName="model"
  31.    expert="false"
  32.    hidden="false"
  33.    preferred="true"
  34.    shortDescription="The model for this component"
  35.    extraTopLevelAttribute="Whatever I want here">
  36.     <cc:extension>
  37.       <fmd:expert>true</fmd:expert>
  38.     </cc:extension>
  39.     <cc:attribute
  40.      name="userid"
  41.      default="guest"
  42.      displayName="User Id"
  43.      expert="false"
  44.      hidden="false"
  45.      preferred="true"
  46.      shortDescription="The model must have a userid property"/>
  47.     <cc:attribute
  48.      name="password"
  49.      default="guest"
  50.      displayName="Password"
  51.      expert="false"
  52.      hidden="false"
  53.      preferred="true"
  54.      shortDescription="The model must have a password property"/>
  55.   </cc:attribute>
  56.  
  57.   <cc:attribute name="useridLabel" default="Userid:" />
  58.  
  59.   <cc:attribute name="passwordLabel" default="Password:" />
  60.  
  61.   <cc:attribute name="loginButtonLabel" default="Login" />
  62.  
  63.   <cc:attribute name="loginAction" method-signature="java.lang.String f()"
  64.    required="true" />
  65.  
  66. <!-- end top level attributes -->
  67.  
  68. <!-- start facets -->
  69.  
  70.   <cc:facet
  71.    name="header"
  72.    displayName="The header facet for the fancy component"
  73.    expert="true"
  74.    hidden="false"
  75.    preferred="false"
  76.    shortDescription="If you want a header, this is where you put it"
  77.    anotherExtraAttribute="Lots of metadata" />
  78.  
  79.   <cc:facet
  80.    name="footer"
  81.    displayName="The footer facet for the fancy component"
  82.    expert="true"
  83.    hidden="false"
  84.    preferred="false"
  85.    shortDescription="If you want a footer, this is where you put it"
  86.    anotherExtraAttribute="Lots of metadata" />
  87.  
  88. <!-- end facets -->
  89.  
  90. <!-- start attached objects -->
  91.  
  92.   <cc:editableValueHolder
  93.    name="userid"
  94.    displayName="Userid field"
  95.    expert="true"
  96.    hidden="false"
  97.    preferred="false"
  98.    shortDescription="Attach a converter or validator here, if you like"
  99.    someExtraMetadata="userid metadata" />
  100.  
  101.   <cc:editableValueHolder
  102.    name="password"
  103.    displayName="Password field"
  104.    expert="true"
  105.    hidden="false"
  106.    preferred="false"
  107.    shortDescription="Attach a converter or validator here, if you like"
  108.    someExtraMetadata="password metadata" />
  109.  
  110.   <cc:actionSource
  111.    name="login"
  112.    displayName="Login button"
  113.    expert="true"
  114.    hidden="false"
  115.    preferred="false"
  116.    shortDescription="Attach an actionListener here, if you like"
  117.    someExtraMetadata="login metadata" />
  118.  
  119. <!-- end attached objects -->
  120.  
  121. </cc:interface>
  122.  
  123. <cc:implementation>
  124.  
  125.   <cc:renderFacet name="header" />
  126.  
  127.   <p><h:outputLabel for="#{cc.clientId}:userid"
  128.                    value="#{cc.attrs.useridLabel}" />
  129.      <h:inputText id="userid" /></p>
  130.  
  131.   <p><h:outputLabel for="#{cc.clientId}:password"
  132.                    value="#{cc.attrs.passwordLabel}" />
  133.      <h:inputText id="password" /></p>
  134.  
  135.   <p><h:commandButton value="#{cc.attrs.loginButtonLabel}"
  136.                      action="#{cc.attrs.loginAction}" /></p>
  137.  
  138.   <cc:renderFacet name="footer" />
  139.  
  140.  
  141. </cc:implementation>
  142.  
  143. </body>
  144.  
  145. </html>
  146.  

Lines 16 - 23 declare the top level composite component metadata.

Lines 25 - 65 declare the attributes that may be passed as XML elements on the composite component instance in the using page. Note that the loginAction attribute is declared as required on line 63. This is useful because Facelets will put up a helpful error if the page author doesn't supply a value here.

Lines 68 - 88 declare the allowable facets. In this case, they're optional.

Lines 90 - 119 declare the attached objects within the implementation section that are publically accessible from the using page.

Programmatically accessing the metadata

Up to this point, everything I've shown has been included in other blog entries elsewhere. What hasn't been shown is how the JSF runtime uses the metadata API to actually conjure up the composite component instance. This API is also accessible to tools that want to embed a JSF runtime into their tool environment. To show this off, I've created a non-composite JSF component and exposed it in the usual way, with a Facelet taglib. This still requires a descriptor, which is placed in WEB-INF/classes/META-INF.

Listing 3 the cc-metadata.taglib.xml

  1. <facelet-taglib  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  2.   xmlns='http://java.sun.com/xml/ns/javaee'
  3.   xsi:schemaLocation='http://java.sun.com/xml/ns/javaee web-facelettaglibrary_2_0.xsd'
  4.   version="2.0">
  5.     <namespace>http://mojarra.dev.java.net/cc-metadata</namespace>
  6.     <tag>
  7.         <tag-name>printMetadata</tag-name>
  8.         <component>
  9.             <component-type>jsf2.PrintMetadata</component-type>
  10.         </component>
  11. <!-- these are advisory and not enforced by the runtime -->
  12.         <attribute>
  13.             <name>viewName</name>
Ed Burns's complete blog can be found at: http://weblogs.java.net/blog/edburns/
Ed Burns

About Ed Burns

Ed Burns is currently a Senior Staff Engineer at Sun Microsystems, Inc. At Sun, Ed leads a team of web experts from across the industry in developing JavaServer™ Faces Technology through the Java Community Process and in open source. His areas of professional interests include web application frameworks, AJAX, reducing complexity, test driven development, requirements gathering, and computer supported collaborative work. Before working on JavaServer Faces, Ed worked on a wide variety of client and server side web technologies since 1994, including NCSA Mosaic, Mozilla, the Sun Java Plugin, Jakarta Tomcat, the Cosmo Create HTML authoring tool, and the web transport layer in the Irix operating system from Silicon Graphics.

Ed has a Bachelor of Computer Science degree from the University of Illinois at Urbana Champaign. While at UIUC, Ed took a minor in Germanic Studies and worked for IBM in the co-op program, where he first aquired a fondness for computer history by working on System 370 Office Software.

Ed has presented many times at Sun's JavaOne conference, given a keynote address at the W-JAX conference in Munich, Germany, and also has spoken at numerous Java User Group meetings. Further information and blogs may be found at http://purl.oclc.org/NET/edburns/.

Why Attend the NFJS Tour?

  • » Cutting-Edge Technologies
  • » Agile Practices
  • » Peer Exchange

Current Topics:

  • Languages on the JVM: Scala, Groovy, Clojure
  • Enterprise Java
  • Core Java, Java 8
  • Agility
  • Testing: Geb, Spock, Easyb
  • REST
  • NoSQL: MongoDB, Cassandra
  • Hadoop
  • Spring 4
  • Cloud
  • Automation Tools: Gradle, Git, Jenkins, Sonar
  • HTML5, CSS3, AngularJS, jQuery, Usability
  • Mobile Apps - iPhone and Android
  • More...
Learn More »