com.sun.faces.metadata.taglib.faces.composite.taglib.xml Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
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"
xmlns:f="jakarta.faces.core"
xmlns:h="jakarta.faces.html"
xmlns:ez="jakarta.faces.composite/ezcomp">
...
</html>
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">
<namespace>http://example.com/path</namespace>
<composite-library-name>ezcomp</composite-library-name>
</facelet-taglib>
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"
xmlns:f="jakarta.faces.core"
xmlns:h="jakarta.faces.html"
xmlns:ez="http://example.com/path">
...
</html>
- <cc:interface name="foo"
- displayName="Very Simple Login Panel"
- preferred="true"
- expert="false"
- shortDescription="An illustration of the composite component feature">
- <cc:attribute name="model" required="true">
- <cc:attribute name="loginAction" required="true" method-signature="java.lang.Object action()"/ >
- </cc:attribute>
- <cc:attribute name="valueChangeListener" targets="username" />
- <cc:attribute name="specialMethodExpression"
- method-signature="com.foo.User validateCurrentUser()" />
- <cc:attribute name="loginButtonLabel" default="Login" />
- <cc:editableValueHolder name="username" />
- <cc:actionSource name="loginEvent" />
- <cc:actionSource name="cancelEvent" />
- <cc:actionSource name="allEvents" targets="loginEvent cancelEvent" />
- </cc:interface>
- <ui:decorate template="fooTemplate.xhtml">
- <ui:define name="header">
- <p>This is the login panel header</p>
- </ui:define>
- <ui:define name="body">
- <p>
- <h:inputText id="username" />
- </p>
- <p>
- <h:commandButton id="loginEvent"
- value="#{cc.attrs.loginButtonLabel}">
- </h:commandButton>
- <h:commandButton id="cancelEvent" value="Cancel" action="cancel">
- </h:commandButton>
- <special:validateUserButton
- validateUser="#{cc.attrs.specialMethodExpression}" />
- </p>
- </ui:define>
- <ui:define name="footer">
- <p>This is the login panel footer</p>
- </ui:define>
- </ui:decorate>
- </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.faces.composite
Declares that the
composite component whose contract is declared by the
<cc:interface>
in which this element is nested
exposes an implementation of ActionSource2
suitable for use
as the target of attached objects in the using page.
Any attached objects suitable for implementations of
ActionSource2
may be attached to the composite component.
Consider this excerpt from the using page:
- <ez:loginPanel id="loginPanel" model="#{bean}">
- <f:valueChangeListener for="username"
- binding="#{bean.useridValueChangeListener}" />
- <f:actionListener for="loginEvent"
- binding="#{bean.loginEventListener}" />
- <f:actionListener for="cancelEvent"
- binding="#{bean.cancelEventListener}" />
- <f:actionListener for="allEvents"
- binding="#{bean.allEventsListener}" />
- </ez:loginPanel>
The <f:actionListener>
elements on lines 4, 7, and 10
refer to the attached objects declared on lines 2, 3 and 4 below.
- <cc:interface name="loginPanel">
- <cc:actionSource name="loginEvent" />
- <cc:actionSource name="cancelEvent" />
- <cc:actionSource name="allEvents" targets="loginEvent cancelEvent" />
- </cc:interface>
Most of the concepts from example content from <cc:valueHolder>
also applies in the case of
<cc:actionSource>
.
Please see <cc:interface>
for a usage
example.