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.
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.
The default XML namespace URI of the taglib that contains the
composite component, for use in the using page, is
http://xmlns.jcp.org/jsf/composite/<composite-library-name>,
where <composite-library-name> is
the name of the
resource library. For example:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://xmlns.jcp.org/jsf/html"
xmlns:f="http://xmlns.jcp.org/jsf/core"
xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
xmlns:ez="http://xmlns.jcp.org/jsf/composite/ezcomp">
...
This declares that any Facelets2 file in the resource
library called ezcomp can be used as a regular
JSF 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 JSF 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>
<namespace>http://domain.com/path</namespace>
<composite-library-name>compositeTest</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 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://xmlns.jcp.org/jsf/html"
xmlns:f="http://xmlns.jcp.org/jsf/core"
xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
xmlns:ez="http://domain.com/path/namespace">
...
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:
<composite: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.
]]>This element declares the usage contract for a composite component. Optionally, and at the component author's discretion, this contract exposes the features of one or more inner components to the page author. The page author can work with the composite component as a single component whose feature set is the union of the features declared in the usage contract.
For example, consider a composite component that implements the functionality of a "login panel". Such a component would likely have two text fields and one button. The user of such a component might like to do one or more of the following.
Be able to listen for the ActionEvent
on the button.
In this case, a
<composite:actionSource>
element is
included in the usage contract that refers to the inner
button in the <composite:implementation>
section.
Provide an "action" to invoke when the button is pressed.
In this case, a
<composite:attribute> element
is included
in the usage contract that refers to the inner button in the
<composite:implementation>
section and
declares the proper method signature for an "action".
Provide parameters to the composite component for labels and other rendering specific aspects of the composite component.
In this case, one or more
<composite:attribute>
elements are included
in the usage contract and those parameters are referred to in
the <composite:implementation>
section
using EL expressions like
#{cc.attrs.usernameLabel},
assuming usernameLabel is the name
of one of the <composite:attribute>
elements in the usage contract.
Add ValueChangeListeners,
Converters, or Validators
to either
or both text fields.
In this case, a
<composite:editableValueHolder>
element is
included in the usage contract that refers to the inner text
field in the <composite:implementation>
section. In the case of wanting to enable only adding a
Converter (and not a
ValueChangeListener or Validator,
a
<composite:valueHolder>
element would be
used.
Add facet children to the login panel.
In this case, a <composite:facet>
element is included in the usage contract that refers to the
inner <composite:renderFacet>
element in
the <composite:implementation>
section.
For each of the behaviorial interfaces in Section JSF.3.2
of
the specification, there is a tag in the
composite: library to nest inside of the
<composite:interface>
section.
If the <composite:interface>
section
is not present in a VDL view, the contract will
be
inferred as described in the specification. There must be
zero or one of these elements in a composite component VDL
file. If a <composite:interface>
element
does appear, there must be an accompanying
<composite:implementation>
element in the
same VDL file.
Nesting of composite components
The implementation must support nesting of composite
components. Specifically, it must be possible for the
<composite:implementation>
section of a
composite component to act as the using page
for
another composite component. When a composite component
exposes a behavioral interface to the using page,
such as a <composite:actionSource>,
<composite:editableValueHolder>,
<composite:valueHolder> or
other
behavioral interface, it must be possible to
“propogate” the exposure of such an interface in
the case of a nested composite component. The composite
component author must ensure that the value of the
name attributes exactly match at all levels
of
the nesting to enable this exposure to work. The
implementation is not required to support
“re-mapping” of names in a nested composite
component.
For example, consider this nested composite component.
Using page
actionSourceOuter.xhtml: Outer composite component
actionSourceInner.xhtml: the composite component used within a composite component.
The id of the <h:commandButton>
on
line 6 of actionSourceInner.xhtml must match the name
on
line 2 of that file (this is a standard requirement for all
composite
components, nested or not). That id must
also match the
name on line 2 of actionSourceOuter.xhtml,
and the
for on line 2 of the using page.
The implementation must support any level of nesting as
long as the
for, name, and
id values match
up. Furthermore, the targets attribute is
also valid for
use in this nested fashion.
Naming containers within composite components
Composite components are themselves naming containers so
that any
possible id conflicts between inner components and components in the
using page are avoided. However, special care must be taken when
using
naming containers in the <composite:implementation>
section. In such cases the value of the “name”
attribute,
or the values of the “targets” attribute must be
used with a
clientId relative to the top level component to
expose any
attached object targets to the using page. For example:
Using page
loginButton.xhtml
Because the button on line 8 resides within a form, it must
be
referred to using a client id, relative to the top level
component, in the "targets" attribute on line 2. Using a
relative
clientId is required due to the semantics of
UIComponent.findComponent().
The name of this composite component. Advisory only. The real name is taken from the filename. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>The component-type of the UIComponent
that
will serve as the composite component root
for this composite
component. The declared component-family
for this
component must be javax.faces.NamingContainer.
The name to display in a tool palette containing this component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>Is this a "preferred" component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>Is this component only for expert users? The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>A short description of the purpose of this component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>Defines the implementation of the composite
component. There must be zero or one of these in a
composite component markup file. If a
<composite:interface> element
appears,
there must be a corresponding
<composite-implementation>
element. If no
<composite:interface> element
appears,
the <composite-implementation>
element is
optional.
Declares an attribute that may be given to an instance of
the
composite component tag for this composite
component. There
may be zero or many of these inside of the
<composite:interface>
section. This element may be
nested within other <composite:attribute>
elements to
convey a usage contract that includes nested properties.
Please see summary page for a usage example.
The top level component in which this
element is
ultimately nested must be a NamingContainer.
There are certain component properties that must not be
exposed using this element. The motivation for this
restriction is that the mapping of markup attributes to
component properties/attributes does not allow for these
attributes to be set. The following properties must not be
exposed using this element.
binding
id
inView
parent
rendered
rendererType
transient
The name of the attribute as it must appear on the composite
component tag in the using page.
If the value of the
name attribute is equal to (without the
quotes)
“action”, ”actionListener”,
“validator”, or “valueChangeListener”,
the
action described in ViewHandler.retargetMethodExpressions()
must be taken to handle the attribute. In these cases, the
method-signature attribute, if present,
must be ignored as
its value is derived as described in
retargetMethodExpressions().
]]>
If this element has a method-signature
attribute, the
value of the targets attribute must be
interpreted as a
space (not tab) separated list of client ids (relative to the
top
level component) of components within the
<composite:implementation>
section. Space is used as
the delimiter for compatibility with the IDREFS and NMTOKENS
data types
from the XML Schema. Each entry in the list must be interpreted
as the
id of an inner component to which the MethodExpression
from
the composite component tag in the using
page must be
applied. If this element has a method-signature
attribute,
but no targets attribute, the value of
the
name attribute is used as the single
entry in the list. If
the value of the name attribute is not
one
of the special values listed in the description of the name
attribute, targets (or its
derived value) need not
correspond to the id of an inner component.
If this attribute is not required, and a value is not supplied by the page author, use this as the default value.
]]>The name to display in a tool palette containing this component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>True if the page author must supply a value for this attribute.
]]>Is this a "preferred" component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>Is this component only for expert users? The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>A short description of the purpose of this component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>Declares that this attribute must be a MethodExpression
whose method signature is described by the value of this
attribute. The
signature must be described using fully qualified class names
wherever a
type is required. This attribute is mutually exclusive with the
"type"
attribute. If both attributes are present, the
"method-signature"
attribute is ignored.
PENDING: when this file is generated from the web-facesuicomponent_2_0.xsd, we will not need to copy the content here manually.
Provides the signature of the Java method. The syntax of the method-signature element is as follows (taken from function-signature in web-jsptaglibrary_2_1.xsd):
MethodSignature ::= ReturnType S MethodName S? '(' S? Parameters? S? ')'
ReturnType ::= Type
MethodName ::= Identifier
Parameters ::= Parameter | ( Parameter S? ',' S? Parameters )
Parameter ::= Type
Where:
Type is a basic type or a fully qualified Java class name (including package name), as per the 'Type' production in the Java Language Specification, Second Edition, Chapter 18.
Identifier is a Java identifier, as per the 'Identifier' production in the Java Language Specification, Second Edition, Chapter 18.
Example:
java.lang.String nickName(
java.lang.String, int )
Declares that this attribute must be a ValueExpression
whose expected type is given by the value of this attribute. If
not
specified, and no "method-signature" attribute is present,
java.lang.Object is assumed. This
attribute is mutually
exclusive with the "method-signature" attribute. If both attributes are
present, the
"method-signature" attribute is ignored.
This attribute allows the name of the attribute exposed to the using page to differ from the one actually used in the implementation. For example, consider a composite component that contains two buttons, one that means "submit" and one that means "cancel". It is natural to want to declare two composite component attributes to allow these buttons to be customized, for example, "submitAction" and "cancelAction". For both of these buttons, the method expression should be retargeted to the inner button's "action" attribute. This scenario would be expressed as follows.
<cc:interface>
<cc:attribute name="submitAction" targetAttributeName="action"
method-signature="java.lang.Object action()"/>
<cc:attribute name="cancelAction" targetAttributeName="action"
method-signature="java.lang.Object action()"/>
<cc:actionSource name="submitAction"/>
<cc:actionSource name="cancelAction"/>
</cc:interface>
<cc:implementation>
<h:commandButton id="submitAction" value="submit" />
<h:commandButton id="cancelAction" value="cancel" />
</cc:implementation>
Declares that this composite component supports a facet with the name given by the value of the "name" attribute.
Please see <composite:interface>
for a usage
example.
The name of the attribute as it must appear on the composite component tag in the using page.
]]>The name to display in a tool palette containing this component. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>True if the page author must supply a facet with this name.
]]>Is this a "preferred" facet. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>Is this facet only for expert users? The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>A short description of the purpose of this facet. The value of this attribute will be set as the value for this property on the composite component bean descriptor.
]]>This element is used in the
<composite:implementation>
section. The facet with
the name equal to the value of the name attribute, given by the page
author in the using page, will be rendered at this point in the
composite component VDL view.
The implementation of this tag handler must insert a
component with component-type
javax.faces.Output and renderer-type
javax.faces.CompositeFacet as a
child at this point in the component tree.
The implementation of this tag handler must store an
attribute into
the created component's attribute map under the key given by the
value
of the symbolic constant UIComponent.FACETS_KEY.
The value
for this key must be the evaluated value of the "name" attribute.
The value of the name attribute as it must appear on an
<f:facet> tag nested
within the composite
component tag in the using page.
If true, and there is no such
facet present on the top
level component, a TagException must be
thrown, containing
the Location, the facet name, and a
localized descriptive
error message.
This element is used in the
<composite:implementation>
section. Any child
components or template text within the composite component tag in
the
using page will be re-parented into the composite component at the
point
indicated by this tag's placement within the
<composite:implementation>
section. The normal
use-case for this element is to have only one occurrence within the
<composite:implementation>
section. Inserting
multiple occurrences may cause duplicate id errors. The results are
undefined if there are multiple occurrences of this element in the
<composite:implementation>
section.
Declares that the composite component whose
contract is declared by the
<composite:interface> in
which this
element is nested exposes an implementation of
ValueHolder suitable for use as the target
of
attached objects in the using page.
Any attached objects suitable for implementations of
ValueHolder may be attached to the
composite
component. Consider this excerpt from the using
page:
Line 2 refers to the
<composite:valueHolder>
declaration on
line 2 of foo.xhtml:
It is possible to declare that a single
<composite:valueHolder>
element should cause multiple
components within the <composite:implementation>
section to be the targets of an attached object
in the
using page. Assuming the same using page
excerpt as
above, the revised VDL view is:
In this case, the "targets" attribute on the
<composite:valueHolder>
element, on line 2 above,
replaces the "name" attribute in the previous example. "targets" is
a
list of ids of client ids (relative to the top level
component)
within the <composite:implementation>
section. In
this case, "targets" refers to the <h:inputText>
components on lines 6 and 7 above.
Please see <composite:interface>
for a usage
example.
The value of this attribute maps back to the "for" attribute on
an attachable object
nested within a composite component. If the "targets" attribute
is not specified,
this value also represents the component ID of the target
component within the
that the <composite:implementation>
ActionListener should be mapped to.
If present, this must be a space (not tab) separated
list of client
ids (relative to the top level component)
of components within
the <composite:implementation>
section. Space is
used as the delimiter for compatibility with the IDREFS and
NMTOKENS
data types from the XML Schema.
Declares that the composite component whose
contract is declared by the
<composite:interface> in
which this
element is nested exposes an implementation of
EditableValueHolder suitable for use as the
target of attached objects in the
using
page. Any attached objects suitable for
implementations of EditableValueHolder may
be
attached to the composite component.The example from <composite:valueHolder>
still applies.
Please see <composite:interface>
for a usage
example.
The value of this attribute maps back to the "for" attribute on
an attachable object
nested within a composite component. If the "targets" attribute
is not specified,
this value also represents the component ID of the target
component within the
that the <composite:implementation>
ActionListener should be mapped to.
If present, this must be a space (not tab) separated
list of client
ids (relative to the top level component)
of components within
the <composite:implementation>
section. Space is
used as the delimiter for compatibility with the IDREFS and
NMTOKENS
data types from the XML Schema.
Declares that the composite component whose
contract is declared by the
<composite: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:
The <f:actionListener>
elements on lines 4, 7, and 10
refer to the attached objects declared on lines
2, 3 and 4 below.
Most of the concepts from example content from <composite:valueHolder>
also applies in the case of
<composite:actionSource>.
Please see <composite:interface>
for a usage
example.
The value of this attribute maps back to the "for" attribute on
an attachable object
nested within a composite component. If the "targets" attribute
is not specified,
this value also represents the component ID of the target
component within the
that the <composite:implementation>
ActionListener should be mapped to.
If present, this must be a space (not tab) separated
list of client
ids (relative to the top level component)
of components within
the <composite:implementation>
section. Space is
used as the delimiter for compatibility with the IDREFS and
NMTOKENS
data types from the XML Schema.
Used within a <composite:interface>
section,
within any sub-element of that section, to include XML content not
defined by this specification. This element can be used to
incorporate
JSR-276
metadata into a composite component.
The presence of this tag in a
<composite:implementation>
section must cause the
named facet to be taken from the facet map of the top
level
component and inserted as a facet child of the component
in which
this element is nested.
The name of the facet child on the top level component which must be inserted as a facet child of the component in which this element is nested.
]]>If true, and there is no such
facet present on the top
level component, a TagException must be
thrown, containing
the Location, the facet name, and a
localized descriptive
error message.
Declares that the composite component whose contract is declared by
the <composite:interface> in which this element is
nested exposes an implementation of ClientBehaviorHolder
suitable for use as the target of attached objects in the
using page. Any attached objects suitable for implementations of
ClientBehaviorHolder may be attached to the composite
component.
The evaluated value of this attribute will be passed as the first
argument to the addClientBehavior() method on
ClientBehaviorHolder.
true, the page
author may omit the the "event" attribute when specifying the behavior
in the using page. This is analogous to "action" being the default
event for commandLink. The usage of this attribute assumes
only one clientBehavior is declared in this composite
component. If more than one is specified, only the first one is used in
the case of a using page with no event attribute.
]]>
The value of this attribute maps back to the "for" attribute on an attachable object
nested within a composite component. If the "targets" attribute is not specified,
this value also represents the component ID of the target component within the
that the <composite:implementation>
ActionListener should be mapped to.
If present, this must be a space (not tab) separated list of client
ids (relative to the top level component) of components within
the <composite:implementation> section. Space is
used as the delimiter for compatibility with the IDREFS and NMTOKENS
data types from the XML Schema.