composite (</pre> <div class="changed_added_2_0"> <p>Describes the Facelets2 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. PENDING: the limit of what one can do without declaring and defining a usage contract must be cleary specified and documented. PENDING: The implementation team must help discover these limits. </p> <h2>Creating a Composite Component</h2> <p>The default implementation must support authoring A composite component is declared by creating a Facelets2 file inside of a resource library. (See section JSF.2.6 of the specification prose 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.</p> <p>The default XML namespace URI of the taglib that contains the composite component, for use in <em>the using page</em>, is <code>http://java.sun.com/jsf/composite/<composite-library-name></code>, where <code><composite-library-name></code> is the name of the resource library. For example:</p> <pre><code> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" <br /> "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><br /> <html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:h="http://java.sun.com/jsf/html"<br /> xmlns:f="http://java.sun.com/jsf/core"<br /> xmlns:ui="http://java.sun.com/jsf/facelets"<br /> xmlns:ez="<i>http://java.sun.com/jsf/composite/<b>ezcomp</b></i>"><br /> ...<br /> </code></pre> <p>This declares that any Facelets2 file in the resource library called <code>ezcomp</code> can be used as a regular JSF UI component in a page with the above namespace declaration by using the "<code>ez</code>" prefix. For example, placing a file called <code>foo.xhtml</code> in a resource library called <code>ezcomp</code> would make that file accessible like this.</p> <pre><code> <ez:foo /> </code></pre> <p>The implementation must also support declaring the namespace of the tag library in a JSF PDL 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: </p> <pre><code> <facelet-taglib><br /> <namespace>http://domain.com/path</namespace> <br /> <composite-library-name>compositeTest</composite-library-name> <br /> </facelet-taglib> <br /> </code></pre> <p>Components from that taglibrary may be used in a using page by declaring them in the XML namespace for that page:</p> <pre><code> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" <br /> "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><br /> <html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:h="http://java.sun.com/jsf/html"<br /> xmlns:f="http://java.sun.com/jsf/core"<br /> xmlns:ui="http://java.sun.com/jsf/facelets"<br /> xmlns:ez="<i><b>http://domain.com/path/namespace</b></i>"><br /> ...<br /> </code></pre> <p><a name="composite_example">Below is an example of a fairly involved composite component declaration. Such a declaration might appear in <code>foo.xhtml</code>.</a></p> <div class="syntax"><div class="html4strict" style="font-family: monospace;"><ol><li class="li1"><div class="de1"><span class="sc2"><<a href="interface.html">composite:interface</a> <span class="kw3">name</span>=<span class="st0">"foo"</span></div></li> <li class="li2"><div class="de2">                     displayName=<span class="st0">"Very Simple Login Panel"</span></div></li> <li class="li1"><div class="de1">                     preferred=<span class="st0">"true"</span></div></li> <li class="li2"><div class="de2">                     expert=<span class="st0">"false"</span></div></li> <li class="li1"><div class="de1">                     shortDescription=<span class="st0">"An illustration of the composite component feature"</span><span class="kw2">></span></span></div></li> <li class="li2"><div class="de2">  <span class="sc2"><<a href="attribute.html">composite:attribute</a> <span class="kw3">name</span>=<span class="st0">"model"</span> required=<span class="st0">"true"</span><span class="kw2">></span></span></div></li> <li class="li1"><div class="de1">    <span class="sc2"><composite:attribute <span class="kw3">name</span>=<span class="st0">"loginAction"</span> required=<span class="st0">"true"</span> method-signature=<span class="st0">"java.lang.Object action()"</span>/ <span class="kw2">></span></span></div></li> <li class="li2"><div class="de2">  <span class="sc2"><span class="kw2"><</span>/composite:attribute></span></div></li> <li class="li1"><div class="de1">  <span class="sc2"><composite:attribute <span class="kw3">name</span>=<span class="st0">"valueChangeListener"</span> targets=<span class="st0">"username"</span> /<span class="kw2">></span></span></div></li> <li class="li2"><div class="de2">  <span class="sc2"><composite:attribute <span class="kw3">name</span>=<span class="st0">"specialMethodExpression"</span></div></li> <li class="li1"><div class="de1">                       method-signature=<span class="st0">"com.foo.User validateCurrentUser()"</span> /<span class="kw2">></span></span></div></li> <li class="li2"><div class="de2">  <span class="sc2"><composite:attribute <span class="kw3">name</span>=<span class="st0">"loginButtonLabel"</span> default=<span class="st0">"Login"</span> /<span class="kw2">></span></span></div></li> <li class="li1"><div class="de1">  <span class="sc2"><<a href="editableValueHolder.html">composite:editableValueHolder</a> <span class="kw3">name</span>=<span class="st0">"username"</span> /<span class="kw2">></span></span></div></li> <li class="li2"><div class="de2">  <span class="sc2"><composite:actionSource <span class="kw3">name</span>=<span class="st0">"loginEvent"</span> /<span class="kw2">></span></span></div></li> <li class="li1"><div class="de1">  <span class="sc2"><composite:actionSource <span class="kw3">name</span>=<span class="st0">"cancelEvent"</span> /<span class="kw2">></span></span></div></li> <li class="li2"><div class="de2">  <span class="sc2"><composite:actionSource <span class="kw3">name</span>=<span class="st0">"allEvents"</span> targets=<span class="st0">"loginEvent,cancelEvent"</span> /<span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"><span class="sc2"><span class="kw2"><</span>/composite:interface></span></div></li> <li class="li2"><div class="de2"><span class="sc2"><<a href="implementation.html">composite:implementation</a> <span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">  <span class="sc2"><ui:decorate template=<span class="st0">"fooTemplate.xhtml"</span><span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">    <span class="sc2"><ui:define <span class="kw3">name</span>=<span class="st0">"header"</span><span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">      <span class="sc2"><span class="kw2"><p></span></span>This is the login panel header<span class="sc2"><span class="kw2"></p></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">    <span class="sc2"><span class="kw2"><</span>/ui:define></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">    <span class="sc2"><ui:define <span class="kw3">name</span>=<span class="st0">"body"</span><span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">      <span class="sc2"><span class="kw2"><p></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">         <span class="sc2"><h:inputText <span class="kw3">id</span>=<span class="st0">"username"</span> /<span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">      <span class="sc2"><span class="kw2"></p></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">      <span class="sc2"><span class="kw2"><p></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2">        <span class="sc2"><h:commandButton <span class="kw3">id</span>=<span class="st0">"loginEvent"</span> </div></li> <li class="li1"><div class="de1">                         <span class="kw3">value</span>=<span class="st0">"#{cc.attrs.loginButtonLabel}"</span><span class="kw2">></span></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">        <span class="sc2"><span class="kw2"><</span>/h:commandButton></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">        <span class="sc2"><h:commandButton <span class="kw3">id</span>=<span class="st0">"cancelEvent"</span> <span class="kw3">value</span>=<span class="st0">"Cancel"</span> <span class="kw3">action</span>=<span class="st0">"cancel"</span><span class="kw2">></span></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">        <span class="sc2"><span class="kw2"><</span>/h:commandButton></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">        <span class="sc2"><special:validateUserButton </div></li> <li class="li2"><div class="de2">          validateUser=<span class="st0">"#{cc.attrs.specialMethodExpression}"</span> /<span class="kw2">></span></span></div></li> <li class="li1"><div class="de1"> </div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">      <span class="sc2"><span class="kw2"></p></span></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">    <span class="sc2"><span class="kw2"><</span>/ui:define></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">    <span class="sc2"><ui:define <span class="kw3">name</span>=<span class="st0">"footer"</span><span class="kw2">></span></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">     <span class="sc2"><span class="kw2"><p></span></span>This is the login panel footer<span class="sc2"><span class="kw2"></p></span></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">    <span class="sc2"><span class="kw2"><</span>/ui:define></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1">  <span class="sc2"><span class="kw2"><</span>/ui:decorate></span></div></li> <li class="li2"><div class="de2"> </div></li> <li class="li1"><div class="de1"><span class="sc2"><span class="kw2"><</span>/composite:implementation></span> </div></li></ol></div></div> <p>The values for attributes in a composite component PDL file can be fully localized by putting them inside a ResourceBundle in the same directory as the PDL page and accessing them with the per-component resource bundle syntax. Consider the file <code>foo.xhtml</code>, in the resource library <code>ezcomp</code>. The <code>shortDescription</code> element could be changed to be:</p> <pre><code> <composite:interface shortDescription="#{cc.resourceBundleMap.shortDescription}" > </code></pre> <p>In this case, In the same <code>ezcomp</code> directory as <code>foo.xhtml</code>, there would be a <code>foo.properties</code> file that would contain this entry:</p> <pre><code> shortDescription=A really nifty login panel. </code></pre> <p>The normal localization rules for <code>ResourceBundle</code> would apply.</p> </div> <pre>)

composite

Tags
composite:interface
composite:implementation
composite:attribute
composite:facet
composite:renderFacet
composite:insertChildren
composite:valueHolder
composite:editableValueHolder
composite:actionSource
composite:extension
composite:insertFacet