General notes on decoding
+ +Only Renderers for components which cause data to sent to the
+ server on a page submit need to implement decode behavior. In
+ practical terms, this means Renderers for components that implement
+ from jakarta.faces.component.EditableValueHolder or
+ jakarta.faces.component.ActionSource or Renderers for
+ jakarta.faces.component.UIForm components. Renderers
+ for components that do not send data to the server on page submit
+ may choose to accept the no-op decode behavior of the
+ jakarta.faces.render.Renderer abstract class. In the
+ Renderer descriptions that follow, the omission of a Decode
+ Behavior section indicates that this Renderer does no decoding.
If a Renderer chooses to implement decode behavior, it must + consult the "disabled" and "readonly" attributes of the component + to be rendered, if the value of either attribute is equal to, + ignoring case, the string "true" (without the quotes) the decode + method must take no action and return immediately.
+ +If the component associated with the Renderer implements the
+ jakarta.faces.component.behavior.ClientBehaviorHolder interface,
+ process jakarta.faces.component.behavior.ClientBehaviors as follows:
+
jakarta.faces.component.behavior.ClientBehaviors
+ associated with this component by calling the implementation of
+ jakarta.faces.component.behavior.ClientBehaviorHolder.getClientBehaviors.client behaviors, determine the
+ client behavior event name from the request parameter given by the value of the constant jakarta.faces.component.behavior.ClientBehaviorContext.BEHAVIOR_EVENT_PARAM_NAME.List of
+ jakarta.faces.component.behavior.ClientBehaviors for the
+ behavior event name from the Map returned from
+ jakarta.faces.component.behavior.ClientBehaviorHolder.getClientBehaviors.client behaviors for the behavior event name,
+ determine the behavior source name from the request parameter given by the value
+ of the constant jakarta.faces.component.behavior.ClientBehaviorContext.BEHAVIOR_SOURCE_PARAM_NAME.clientId, iterate over the List of
+ jakarta.faces.component.behavior.ClientBehaviors and call the
+ decode() method for each one.+ +
General notes on encoding
+ +If the value of the component's "rendered" property is false, + the component, and its children must not be rendered.
+ +For all renderers that are responsible + for rendering their own children, the renderer will decide if the + end tag is required or not based on the presence or absence of + children for the component.
+ +General notes regarding the id attribute
All components, and therefore all tags for those components
+ support the id attribute. This attribute is optional.
+ If not present its value is autogenerated by the implementation and
+ used for internal purposes only. If present, an id
+ attribute must not start with the String listed as the
+ value of the constant UIViewRoot.UNIQUE_ID_PREFIX, and
+ it must be unique within the scope of the nearest component that is
+ a NamingContainer.
All renderers must take the following action regarding the
+ id attribute: If the value returned from
+ component.getId() is non-null and does
+ not start with UIViewRoot.UNIQUE_ID_PREFIX, call
+ component.getClientId() and render the result as the
+ value of the id attribute in the markup for the
+ component. See the javadoc for
+ component.getClientId() for details, particularly note
+ that the Renderer has a chance to modify the client id before it is
+ rendered. If the component doesn't generate any markup elements,
+ include the id attribte on a "span" element that
+ encloses the content for the component.
In addition to any action already specified in the renderers, all
+ renderers for UIInput components must take the
+ following action regarding the id attribute: Call
+ component.getClientId() and render the result as the
+ value of the name attribute. This may cause some
+ renderers to have "id" and "name" attributes that have exactly the
+ same value.
General notes regarding the rendering of JavaScript in the + standard components.
+ +The intent of the standard renderkit is to specify the minimal + Renderers a JSF implementation must provide. As such, it is the + baseline for building JSF applications that are maximally + portable across JSF implementations and user agents. Therefore, + the use of JavaScript must be minimized as not all browsers + support JavaScript, nor do all users enable JavaScript support in + their user agents.
+ +Compliant implementations must only generate JavaScript in the
+ jakarta.faces.Link and
+ jakarta.faces.Button
+ Renderers for the jakarta.faces.Command
ignored-by-renderer
+ attribute, such as "onmouseover", is excluded from this restriction.
+
+
+
+ General notes regarding the rendering of component Client Behaviors.
Components that implement the jakarta.faces.component.behavior.ClientBehaviorHolder
+ interface are eligable to have ClientBehavior instances attached to them. The standard
+ renderers are responsible for inserting the scripts produced by client behaviors into the component's
+ rendered content. Components may obtain script from multiple sources. Event handler scripts may be specified
+ by page authors, scripts may be produced by client behaviors and renderers may produce ther own scripts.
+ When multiple scripts are present, the scripts must be chained together in this order:
+
+ If any of the scripts in the chain returns false, subsequent script must not be executed.
+ The specification provides a utility function faces.util.chain to handle this capability. If there
+ are UIParameter children the parameter names and values must be passed into the client behavior
+ getScript method via the ClientBehaviorContext.
Rendering Pass Through Attributes.
+ +The set of attributes written for a component is determined by
+ its Renderer and collectively are known as
+ renderer specific attributes. In addition to
+ renderer specific attributes, pass through
+ attributes are also possible. Pass through
+ attributes are declared as markup attributes on components
+ in the VDL view and are stored in the Map returned
+ by UIComponent.getPassThroughAttributes(). When
+ rendering a UIComponent instance,
+ Renderers call
+ ResponseWriter.startElement(), passing in the
+ UIComponent instance. The
+ ResponseWriter must ensure that any pass through
+ attributes are rendered on the outer-most markup element for
+ the component. If there is a pass through attribute
+ with the same name as a renderer specific attribute, the
+ pass through attribute takes precedence. Pass
+ through attributes are rendered as if they were passed to
+ ResponseWriter.writeURIAttribute().
Rendering Behavior Event Attributes.
+ +
+ When the component is an instance of ClientBehaviorHolder
+ and the attribute name starts with 'on'
+ and the substring after 'on' is contained in ClientBehaviorHolder#getEventNames()
+ and it is not available as a renderer specific attribute,
+ then it must be rendered the same way as a pass through attribute.
+
Decode Behavior
+ +Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If the value in the
+ Map for the value of the "clientId" property of the
+ component is null, create a String by concatenating
+ the value of the "clientId" property of the component with the
+ String ".x" (without the quotes). Create another String in the
+ same manner, but concatenate ".y" (without the quotes). If
+ null is the value in the Map for both
+ Strings, return from decode(). If the value in the
+ Map for the value of the "clientId" property of the
+ component is not null, get the value of the "type"
+ attribute, and convert it to lower case. If the result is equal
+ to the String "reset" (without the quotes), return from
+ decode(). Otherwise, create a
+ jakarta.faces.event.ActionEvent around the component,
+ and pass it to the queueEvent() method of the
+ component, which must be an instance of
+ UICommand.
Encode Behavior
+ +Render the clientId of the component as the value of the "name"
+ attribute. Render the current value of the component as the value
+ of the "value" attribute. If "image" attribute is specified render
+ it as the value of the "src" attribute after passing it to the
+ getResourceURL() method of the
+ ViewHandler for this application, and passing the
+ result through the encodeResourceURL() method of the
+ ExternalContext. Note that calling
+ getResourceURL() will prefix the context-root of the
+ current application if the value of the "src" attribute starts
+ with "/". When handling the "image" attribute, the value
+ must not be escaped. For example, & must not be
+ turned into &. If the "styleClass" attribute
+ is specified, render its value as the value of the "class"
+ attribute. If the user has specified an "onclick" attribute,
+ append that JavaScript to any existing JavaScript already being output by the
+ implementation before rendering.
If the component being rendered by
+ this renderer has any UIParameter children, each one
+ of them must be rendered using the renderer for component-family:
+ "jakarta.faces.Input" and renderer-type: "jakarta.faces.Hidden". For
+ discussion, this is called the hiddenRenderer. A component with
+ component-type "jakarta.faces.Input" must be created for local use
+ in rendering each UIParameter child. The "id"
+ property of the temporary component must be set to the "name" of
+ the UIParameter. The "value" property of the
+ temporary component must be set to the "value" of the
+ UIParameter. For each UIParameter
+ child, the hiddenRenderer must have its
+ encodeBegin(), encodeChildren(), and
+ encodeEnd() methods called, in order, passing the
+ temporary component as the second argument.
Because this renderer is responsible for rendering its own + children, the renderer will decide if the end tag is required or + not based on the presence or absence of children for the + component.
+ +To support entering flows that are defined by both a defining
+ document id and a flow id, add a component attribute to this
+ component whose name is given by the value of the symbolic
+ constant
+ jakarta.faces.event.ActionListener.TO_FLOW_DOCUMENT_ID_ATTR_NAME,
+ and whose value is the defining document id. For example, when
+ using this component in a facelet page, the following markup
+ would cause such an attribute to be added.
<h:commandButton id="start_a" value="enter flow-a" action="flow-a">
+ <f:attribute name="to-flow-document-id" value="unique"/>
+</h:commandButton>
+It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>General Behaviour
+ +Both the encode and decode behavior require the ability to get + the id/name for a hidden field, which may be rendered in markup or which + may be programmatically added via client DOM manipulation, + whose value is set by the JavaScript form submit. This name must + be constructed as follows:
+ +Get the clientId for the form of which this component is a + child.
Append
+ NamingContainer.SEPARATOR_CHAR.
Append a constant string that is the same for all command + link components in the tree.
In the following text, this String is called + hiddenFieldName.
+ +Decode Behavior
+ +Obtain the "clientId" property of the component. Obtain the
+ Map from the "requestParameterMap" property of the
+ ExternalContext. Derive hiddenFieldName as above.
+ Get the entry in the Map under the key that is the
+ hiddenFieldName. If the there is no entry, or the entry is the
+ empty String, or the entry is not equal to the value of the
+ "clientId" property, return immediately. If there is an entry,
+ and its value is equal to the value of the "clientId" property,
+ create a new jakarta.faces.event.ActionEvent instance
+ around the component and call queueActionEvent() on
+ the component, passing the event.
Encode Behavior
+ +If the value of the disabled attribute is
+ true, render a span element. Render all the
+ ignored-by-renderer attributes and the target
+ attribute as ignored-by-renderer attributes on the span, even
+ though the target attribute will have no effect on a
+ span. Render the current value of the component as the content of
+ the span. Return.
If the disabled attribute is not present, or its
+ value is false, render an HTML a
+ element. Render "#" as the value of the "href" attribute. Render
+ the current value of the component as the link text if it is
+ specified. Render JavaScript that is functionally equivalent to
+ the following as the value of the "onclick" attribute:
document.forms['CLIENT_ID']['hiddenFieldName'].value='CLIENT_ID';
+ document.forms['CLIENT_ID']['PARAM1_NAME'].value='PARAM1_VALUE';
+ document.forms['CLIENT_ID']['PARAM2_NAME'].value='PARAM2_VALUE';
+ document.forms['CLIENT_ID'].submit(); return false;
where hiddenFieldName is as described above, CLIENT_ID is the
+ clientId of the UICommand component, PARAM*_NAME and PARAM*_VALUE
+ are the names and values, respectively, of any nested UIParameter
+ children. The name and the value must be URLEncoded. Note that the required url
+ encoding is handled by
+ ResponseWrter.writeAttribute(). If an
+ "onclick" attribute was specified by the user, render this
+ JavaScript in a function, and render the user's JavaScript in a
+ function. Render both functions in a choice function as
+ follows:
var a=function(){#USER_FUNCTION#};
+ var b=function(){#FACES_FUNCTION#};
+ return (a()==false) ? false : b();
where #USER_FUNCTION# is the user's JavaScript and + #FACES_FUNCTION# is the JavaScript rendered by Jakarta Faces. The choice + function should operate such that if the user's JavaScript returns + true, then the rendered JavaScript will also execute.
+ +If the "styleClass" attribute is specified, render its value as + the value of the "class" attribute. Render any non-UIParameter + output children as normal inside of the "a" element. These will + appear as the link text. Allow the form renderer to output a + single "input" element (for the entire page, regardless of how + many command link components are in the page) of "type" "hidden" + whose "name" is the value of hiddenFieldName, and which must not + have a "value" attribute. Multiple occurrences of command link + components in the tree should not cause multiple hiddenFieldName + hidden fields. Allow the form renderer to output an "input" + element of "type" "hidden" for each of the nested UIParameter + children, taking the name property (but not the value) from each + one in turn. If the "disabled" attribute is specified, do not + render the HTML "a" anchor element or its "href" attribute. + Instead, render a "span" element. If the "styleClass" attribute + is specified, render its value as the value of the "class" + attribute on the "span". Render any ignored-by-renderer attributes on + the "span". The content of the span element comes from the value + of the component or its children as specified above.
+ +If the user specified a target attribute, its
+ value must be set using javascript since the onclick
+ handler will prevent the target attribute from being generated.
+ This must be accomplished using JavaScript that is equivalent to
+ the following.
document.forms['CLIENT_ID'].target='TARGET';
Where TARGET is the value of the target attribute on the tag.
+ +To support entering flows that are defined by both a defining
+ document id and a flow id, add a component attribute to this
+ component whose name is given by the value of the symbolic
+ constant
+ jakarta.faces.event.ActionListener.TO_FLOW_DOCUMENT_ID_ATTR_NAME,
+ and whose value is the defining document id. For example, when
+ using this component in a facelet page, the following markup
+ would cause such an attribute to be added.
<h:commandLink id="start_a" value="enter flow-a" action="flow-a">
+ <f:attribute name="to-flow-document-id" value="unique"/>
+</h:commandLink>
+It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>
+ Render a JavaScript function that invokes faces.ajax.request() function.
+
+ Render an HTML script element. If the value of the "name" attribute does not contain a
+ period . indicating a namespaced function name, then render JavaScript var
+ keyword, followed by a space character. Render the value of the "name" attribute, followed by
+ JavaScript assignment operator. Render JavaScript function which invokes faces.ajax.request()
+ with data provided by execute, render, onbegin,
+ oncomplete, onsuccess and onerror arguments, if any.
+
+ If the component being rendered has any UIParameter children, each one of them must be
+ encoded into params object of the options object of the faces.ajax.request()
+ function.
+
+ If the rendered JavaScript function is invoked with an object argument, each property must be
+ encoded into params object of the options object of the faces.ajax.request()
+ function. This will override any property with the same key.
+
+ Obtain the Map from the "requestParameterMap" property of the ExternalContext.
+ If the value in the Map for the value of the "jakarta.faces.source" equals to the "clientId" property of the component,
+ create a jakarta.faces.event.ActionEvent around the component, and pass it to the queueEvent() method of the component,
+ which must be an instance of UICommand.
+
name="ez.functionName".
+ ]]>window.
+ Defaults to false.
+ ]]>UIViewRoot.resetValues().
+ The implementation must cause an ActionListener to be attached to the ActionSource
+ component in which this tag is nested that calls UIViewRoot.resetValues() passing the value
+ of the render attribute as the argument.
+ ]]>Please consult the javadoc for
+ UIData to supplement this specification. If the
+ "styleClass" attribute is specified, render its value as the value
+ of the "class" attribute on the "table" element. Any
+ ignored-by-renderer attributes are also rendered on the "table"
+ element.
Column Groups
+ +If the UIData component has a "colgroups" facet,
+ render its contents. Consistent with the rules of facets in
+ general, this facet must have only one child. In general, this
+ will be a panel group component that will contain
+ colgroup and col elements per the HTML
+ Table specification. Use of column grouping can improve
+ accessibility. This facet must be rendered before the table
+ header and footer.
Rendering the header
+ +If the UIData component has a "header" facet, or
+ any of the child UIColumn components has a "header"
+ facet, render a "thead" element. If the UIData
+ component has a "header" facet, encode its contents inside of "tr"
+ and "th" elements, respectively. Output the value of the
+ "headerClass" attribute of the UIData component, if
+ present, as the value of the "class" attribute on the "th".
+ Output the number of child UIColumn components of the
+ UIData component as the value of the "colspan"
+ attribute on the "th". Output "colgroup" as the value of the
+ "scope" attribute on the "th" element.
If any of the child UIColumn components has a
+ "header" facet render a "tr" element. For each
+ UIColumn that actually has a "header" facet, render
+ it inside of a "th" element. Columns that don't have a "header"
+ facet cause an empty "th" element to be rendered. Output the
+ value of the "headerClass" attribute of the UIColumn
+ component, if present, as the value of the "class" attribute on
+ the "th". If the "headerClass" attribute of the UIColumn
+ component is not present, output the value of the "headerClass"
+ attribute of the UIData component, if present, as
+ the value of the "class" attribute on the "th". Output "col" as
+ the value of the "scope" attribute on the "th" element.
+
Close out the "thead" element.
+ +Rendering the footer
+ +If the UIData component has a "footer" facet, or
+ any of the child UIColumn components has a "footer"
+ facet, render a "tfoot" element. If the UIData
+ component has "footer" facets, encode the contents inside of a "tr"
+ element.
If any of the child UIColumn components has a
+ "footer" facet render a "td" element. For each
+ UIColumn that actually has a "footer" facet, render
+ it inside of a "td" element. Columns that don't have a "footer"
+ facet cause an empty "td" element to be rendered. Output the
+ value of the "footerClass" attribute of the UIColumn
+ component, if present, as the value of the "class" attribute on
+ the "td". If the "footerClass" attribute of the UIColumn
+ component is not present, output the value of the "footerClass"
+ attribute of the UIData component, if present, as
+ the value of the "class" attribute on the "td".
If the UIData component has a "footer" facet,
+ encode its contents inside of "tr" and "td" elements, respectively.
+ Output the value of the "footerClass" attribute of the
+ UIData component, if present, as the value of the
+ "class" attribute on the "td". Output the number of child
+ UIColumn components of the UIData
+ component as the value of the "colspan" attribute on the "td".
Close out the "tfoot" element.
+Rendering the table body
+ +Look at the value of the "bodyrows" attribute. If present, + this must be a comma separated list of integers. Each entry in + this list is the row index of the row before which a "tbody" + element should be rendered.
+ +If there was no "bodyrows" attribute, or it was empty, render a
+ "tbody" element. Keep track of the result of the "rows" property
+ on the UIData component. Keep track of the number of
+ rows we have rendered so far. Iterate through the rows. Set the
+ "rowIndex" property of the UIData component to be
+ correct as we iterate through the rows. Stop rendering children
+ and close out the "tbody" element if the "rowAvailable" property
+ of the UIData returned false. If the current row
+ index is contained in the "bodyrows" attribute, check if a "tbody"
+ start element was rendered that needs to be closed, and if so,
+ close the "tbody" element. Then render a "tbody" element start.
+ Otherwise, do not render a "tbody" element.
Output a "tr" element. Output the value of the "rowClasses"
+ per the attribute description below, or rowClass. For each
+ UIColumn child, if the column component has a
+ "rowHeader" attribute with a value of "true", output a "th"
+ element with a "scope" attribute with the value of "row".
+ Otherwise, if the column component has no "rowHeader" attribute,
+ or its value is false, output a "td" element. In either case
+ attach the value of the "columnClasses" attribute of the
+ UIData component per the attribute description below.
+ Recursively encode each child of each UIColumn child.
+ Close out the "td" or "th" element. When done with the row, close
+ out the "tr" element. When done with all the rows, close out the
+ "tbody" element.
When done rendering all the rows, set the "rowIndex" property of
+ the UIData to -1, and close out the "table"
+ element.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Assigns one or more space-separated CSS class names to each + "tr"
+ + + + ]]>Decode Behavior
+ +Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If the map contains
+ an entry for the "clientId" of this UIForm component,
+ call setSubmitted(true) on the form, otherwise call
+ setSubmitted(false) on the form.
Encode Behavior
+ +The value of the "method" attribute must be "post". The value
+ of the "action" attribute must be the result of passing the view
+ identifier of the current view to the getActionURL()
+ method of the ViewHandler for this application, then
+ passing that String to the encodeActionURL() method
+ on the ExternalContext. The value of the acceptcharset
+ attribute must be rendered as the value of "accept-charset".
+ If the "styleClass" attribute is specified, render its value as the
+ value of the "class" attribute. Render a "name"
+ attribute with a value the same as the "id" attribute as described
+ in "General Notes on
+ Encoding" regarding the "id" attribute for UIInput
+ components.
Obtain the UIViewRoot view identifier and
+ use it to obtain an action URL by calling ViewHandler.getActionURL.
+ Use the action URL to obtain an encoded action URL by calling
+ ExternalContext.encodeActionURL. Obtain an
+ encoded partial action URL by calling
+ ExternalContext.encodePartialActionURL using action URL as the argument.
+ Compare the result from ExternalContext.encodePartialActionURL with the
+ value from ExternalContext.encodeActionURL(). If they are different,
+ render a hidden field with the name jakarta.faces.encodedURL and the value
+ of this hidden field as the value from ExternalContext.encodePartialActionURL.
ViewHandler.writeState()
+ before the the close of the "form" element.
+ Render all the necessary hidden fields
+ for all commandLink instances in the page just before the close of the "form" element.
+ </form> element tag, render
+ any resources that have been targeted for this form:
+ UIViewRoot instance.List of component resources targeted for
+ this form with a call to UIViewRoot.getComponentResources()
+ with the String "form" as the argument.List of UIComponent instances
+ and call encodeAll on each UIComponent instance.
+ It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Handling the Value
+ +If the "name" attribute is present, execute algorithm
+ Common Algorithm for Obtaining A Resource to Render
+ to obtain a Resource instance.
+ Call Resource.getRequestPath() and output the result as the
+ value of the "src" attribute on the rendered markup.
Otherwise, if the "url" attribute is present, treat its value as
+ if it was the value of the "value" attribute. Otherwise, if the
+ "value" attribute is present, render the value of the component as
+ the value of the "src" attribute, after passing it to the
+ getResourceURL() method of the ViewHandler
+ for this application, and passing the result through the
+ encodeResourceURL() method of the
+ ExternalContext.
When handling the "src" attribute,
+ the value must not be escaped. For example, & must not
+ be turned into &. If the "styleClass"
+ attribute is specified, render its value as the value of the "class"
+ attribute.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>The libraryName for this resource.
]]>The + resourceName for this resource.
]]>The local name of the rendered element must first be
+ determined for encoding. Look in the components's pass through
+ attribute map for a value under the key given by the value of the
+ symbolic constant
+ Renderer.PASSTHROUGH_RENDERER_LOCALNAME_KEY. If not found,
+ throw a FacesException. If found, let this value be
+ localName.
If the component has a manually declared, not auto-generated + clientId, or if the component has behaviors attached to it, render the + clientId as the value of the "id" attribute.
+ +Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If the
+ Map contains an entry for the "clientId" of the
+ component, pass the value of the entry to the
+ setSubmittedValue() method of the component, which
+ must be an instance of EditableValueHolder, and
+ return. Otherwise, obtain the "request" property from the
+ ExternalContext and cast it to
+ jakarta.servlet.http.HttpServletRequest. Call
+ getParts() on the httpServletRequest. Iterate over
+ the parts. If the "name" property of the current part is equal to
+ the "clientId", pass the current part to the
+ setSubmittedValue() method of the component. If an
+ exception is thrown during the iteration, log the exception and
+ continue.
The standard implementation must override the
+ getConvertedValue() so that it simply returns the
+ submittedValue argument.
Any exception thrown when interacting with the underlying
+ multi-part API must be wrapped in a FacesException
+ and allowed to reach the ExceptionHandler.
Encode Behavior
+ +Render the clientId of the component as the value of the + "name" attribute. Do not render the "value" attribute. If the + "styleClass" attribute is specified, render its value as the value + of the "class" attribute.
+ +If ProjectStage is not
+ ProjectStage.Production, verify that the enclosing
+ form has an enctype attribute whose value is
+ multipart/form-data. If not, add a
+ FacesMessage for this component's clientId to the
+ FacesContext stating that file upload requires a form
+ with enctype equal to
+ multipart/form-data. If ProjectStage
+ is ProjectStage.Production, do not
+ do this verification.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Decode Behavior
+ +See the decode description for the Input Text renderer.
+Encode Behavior
+ +Render the clientId of the component as the value of the + "name" attribute. Render the current value of the component as + the value of the "value" attribute.
+ +Decode Behavior
+ +See the decode description for the Input Text renderer.
+Encode Behavior
+ ++ Render the clientId of the component as the value of the "name" + attribute. Render the current value of the component as the value + of the "value" attribute, if and only if the "redisplay" component + attribute is the string "true". If the "styleClass" attribute is + specified, render its value as the value of the "class" + attribute.
+ +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If the
+ Map contains an entry for the "clientId" of the
+ component, pass the value of the entry to the
+ setSubmittedValue() method of the component, which
+ must be an instance of EditableValueHolder.
Encode Behavior
+ +Render the clientId of the component as + the value of the "name" attribute. Render the current value of + the component as the value of the "value" attribute. If the + "styleClass" attribute is specified, render its value as the value + of the "class" attribute. +
+ +If this element has children, they + must be ignored by default. Implementions may provide a + configuration option that allows this element to render its + children.
+ +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Decode Behavior
+ +See the encode description for the Input + Text renderer.
+ +Encode Behavior
+ +Render the + clientId as the value of the "name" attribute. Render the current + valu eof the component inside the "textarea" + element.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Set-up for Rendering
+ +Obtain the "summary" and "detail" properties from
+ UIMessage component. If not present, keep the
+ empty string as the value, respectively. Obtain the first
+ FacesMessage to render from the component, using
+ the "for" property of the UIMessage.
+
If the "for" property is set and
+ not empty, the SearchExpressionHandler must be used to
+ resolve the associated component.
FacesMessage.SEVERITY_INFO, the severity style
+ comes from the value of the "infoStyle" attribute. If the
+ severity of the message is
+ FacesMessage.SEVERITY_WARN, the severity style
+ comes from the value of the "warnStyle" attribute, and so on for
+ each of the severities, INFO, WARN, ERROR and
+ FATAL. The same rules apply for obtaining the
+ severity style class, but instead of "infoStyle, warnStyle", etc
+ use "infoClass, warnClass", etc. Obtain the "style",
+ "styleClass" and "layout" attributes from the
+ UIMessage component. If we have a "style"
+ attribute and a severity style attribute, use the severity style
+ attribute as the value of the "style" attribute. If we have no
+ "style" attribute, but do have a severity style, use the
+ severity style as the value of the "style" attribute. The same
+ precedence rules apply for the style class. Obtain the value of
+ the dir and lang attributes.
+
+ Rendering
+ +For the message renderer, we only render one row, for the first
+ message. For the messages renderer, we render as many rows as we
+ have messages. If any of the "dir", "lang", "style" or
+ "styleClass" attributes has a non-null value (as determined
+ above), render a "span" element, outputting the value of the
+ "style" attribute as the the value of the "style" attribute, and
+ outputting the value of the "styleClass" attribute as the value of
+ the "class" attribute on the "span" element. Output the "dir" and
+ "lang" attributes as well, if they are present. If the
+ UIMessage has a "tooltip" attribute with the value of
+ "true", and we haven't already written out the "span" and the "title" attribute for
+ the "span", output the "detail" as the value of the "title" attribute on the
+ "span". If we haven't already written out a "title" attribute, and there is
+ no detail, output the "summary" as the value of the "title" attribute.
+ Close out the span if necessary.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>UIMessages, and there is
+ no "for" attribute. Therefore, use either null to
+ obtain the messages from the FacesContext or the empty
+ string if the components "globalOnly" property is
+ true. If the layout was "table" close out the table
+ elements, otherwise, close out the list elements.
+
+ ]]>It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>style, styleClass, dir, and
+ lang attributees from this component. If any are
+ present, render a "span" element. Output the
+ styleClass attribute (if present) as the value of the
+ class attribute. Output the style
+ attribute as the value of the style attribute.
+ Output the dir and lang attributes as
+ ignored-by-renderer attributes. Accrue a list of the values of all child
+ UIParameter components of this component. If there
+ are one or more accumulated parameter values, convert the list of
+ parameter values to an Object array, call
+ MessageFormat.format(), passing the
+ value of this component as the first argument, and
+ the array of parameter values as the second argument, and render
+ the result. Otherwise, render the value of this
+ component unmodified.]]>It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Render the
+ current value of the component as label text if it is
+ specified. If a "for" attribute is specified, find the
+ component specified by the value of the "for" attribute
+ via the
+ SearchExpressionHandler, and render its
+ client id as the value of the "for" attribute. If
+ "styleClass" attribute is specified, render its value as the
+ value of the "class" attribute.
+
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>disable property is false
+ are appended to the String to be output as the value of the
+ "href" attribute as query parameters before rendering. The
+ entire "href" string must be processed by a call to the
+ encodeResourceURL() method of the
+ ExternalContext. The name of the UIParameter
+ goes on the left hand side, and the value of the UIParameter
+ on the right hand side. The name and the value must be
+ URLEncoded. Note that the required url encoding is
+ handled by
+ ResponseWrter.writeURIAttribute(). Each
+ UIParameter instance is separeted by an ampersand, as
+ dictated in the URL spec. If the "styleClass" attribute is
+ specified, render its value as the value of the "class"
+ attribute. If the "id" attribute is specified, follow the
+ same steps as mentioned in the "General Notes
+ on Encoding" regarding the "id" attribute for UIInput
+ components. If the "disabled" attribute is specified, do
+ not render the HTML "a" anchor element or the "href"
+ element. Instead, render a "span" element. If the
+ "styleClass" attribute is specified, render its value as the
+ value of the "class" attribute on the "span". Render any
+ ignored-by-renderer attributes on the "span".
+
+ ]]>It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Any child UIParameter components
+whose disable
+property is false are appended to the String to be
+output as the value of the "href" attribute as query parameters before
+rendering. The entire "href" string must be processed by a call to
+the encodeResourceURL() method of the
+ExternalContext. The name of the UIParameter
+goes on the left hand side, and the value of the
+UIParameter on the right hand side. The name and the value
+must be URLEncoded. Note that
+the required url encoding is handled by
+ResponseWrter.writeAttribute(). Each
+UIParameter instance is separated by an ampersand, as
+dictated in the URL spec. If the "fragment" attribute is specified, the
+value will be included at the end of the resulting URL preceded by a
+hash mark. If the "styleClass" attribute is specified, render its value
+as the value of the "class" attribute.
If the "id" attribute is specified, follow +the same steps as mentioned in the "General Notes on +Encoding" regarding the "id" attribute for UIInput components. If +the "disabled" attribute is specified, do not render the HTML "a" anchor +element or the "href" element. Instead, render a "span" element. If +the "styleClass" attribute is specified, render its value as the value +of the "class" attribute on the "span". Render any ignored-by-renderer +attributes on the "span".
+ +To support entering flows that are defined by both a defining
+ document id and a flow id, add a component attribute to this
+ component whose name is given by the value of the symbolic
+ constant
+ jakarta.faces.event.ActionListener.TO_FLOW_DOCUMENT_ID_ATTR_NAME,
+ and whose value is the defining document id. For example, when
+ using this component in a facelet page, the following markup
+ would cause such an attribute to be added.
<h:link id="start_a" value="enter flow-a" outcome="flow-a">
+ <f:attribute name="to-flow-document-id" value="unique"/>
+</h:link>
+It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>ClientWindow on the rendering of this element.
+ ]]>Encode Behavior
+ +Render an HTML "input" element of type "button". The value of the
+component is rendered as the button text and the outcome of the
+component is used to determine the target URL which is activated by
+onclick. If "image" attribute is specified, render it as the value of
+the "src" attribute after passing it to the
+getResourceURL() method of the ViewHandler for
+this application, and passing the result through the
+encodeResourceURL() method of the
+ExternalContext.
If the component is not disabled, take the following actions.
+ +Algorithm to obtain the url to which the user-agent should issue a GET request when clicked
+ +Obtain the NavigationCase that corresponds to the
+ component instance for this Renderer.
Obtain an instance of
+ jakarta.faces.application.ConfigurableNavigationHandler
+ from the ViewHandler. If no such instance can be
+ obtained, write the "disabled" attribute on the button. Otherwise,
+ let outcome be the result of calling
+ getOutcome() on the argument component, which must be an
+ instance of UIOutcomeTarget. If this result is
+ null, let outcome be the viewId of the current
+ UIViewRoot. Obtain a
+ reference to the NavigationCase, called navCase
+ for discussion. If the component has a non-null
+ attribute named by the value of the symbolic constant
+ jakarta.faces.event.ActionListener.TO_FLOW_DOCUMENT_ID_ATTR_NAME,
+ let navCase be the return from calling
+ getNavigationCase() on the
+ ConfigurableNavigationHandler, passing the current
+ FacesContext as the first argument, null, as
+ the second argument, outcome as the third argument, and the
+ value of the TO_FLOW_DOCUMENT_ID_ATTR_NAME attribute as
+ the fourth argument. Otherwise, let navCase be the return
+ from calling getNavigationCase() on the
+ ConfigurableNavigationHandler, passing the current
+ FacesContext as the first argument, null, as
+ the second argument, and outcome as the third
+ argument. If this returns null, log an informative
+ error which includes the component id, and write the "disabled"
+ attribute on the component markup, with the value of
+ true. Otherwise obtain the encoded target URL using the
+ following algorithm.
Algorithm to obtain the encoded target URL
+ +Let params be the Map<String,
+ List<String>> to be passed to
+ ViewHandler.getBookmarkableURL(). Build this map up first
+ from any child UIParameter components. These children must
+ be processed in the order in which they appear as children. If multiple
+ children with the same name are encountered, their values must appear in
+ the List<String> in the Map entry with
+ the same name, and appear in the list in the same order as their child
+ order.
Obtain any parameters included within the
+ navigation case. Call getParameters() on
+ navCase. The result will be a Map<String,
+ List<String>>. If the result is
+ non-null and non-empty, iterate over the entries
+ from the result Map and, if no entry with the
+ same name exists in params, set the value from the
+ current entry as the value in the params
+ Map.
If the navigation case has a
+ non-null toFlowDocumentId property, add two
+ parameters as shown in this table.
| parameter name | +parameter value | +
|---|---|
value of FlowHandler.TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME |
+
+ value of the toFlowDocumentId property
+ of the navigation case |
+
value of FlowHandler.FLOW_ID_REQUEST_PARAM_NAME |
+
+ value of the fromOutcome property
+ of the navigation case |
+
Let includeViewParams be the result of a
+ logical OR of the results from calling
+ isIncludeViewParams() on the argument
+ UIOutcomeTarget component and calling
+ isIncludeViewParams on navCase.
Call getBookmarkableURL() on the
+ ViewHandler, passing the current
+ FacesContext as the first argument, the return
+ from calling getToViewId() as the second
+ argument, params as the third argument, and
+ includeViewParams as the last argument.
The entire target URL string must be processed by a call to
+ the encodeResourceURL() method of the
+ ExternalContext. The name of the
+ UIParameter goes on the left hand side, and the value of
+ the UIParameter on the right hand side. The name and the
+ value must be URLEncoded. Each UIParameter instance is
+ separeted by an ampersand, as dictated in the URL spec. The final
+ encoded result will be written out to the onclick attribute of the
+ button as "window.location.href = '
Because this renderer is responsible for rendering its own + children, the renderer will decide if the end tag is required or + not based on the presence or absence of children for the + component.
+ +To support entering flows that are defined by both a defining
+ document id and a flow id, add a component attribute to this
+ component whose name is given by the value of the symbolic
+ constant
+ jakarta.faces.event.ActionListener.TO_FLOW_DOCUMENT_ID_ATTR_NAME,
+ and whose value is the defining document id. For example, when
+ using this component in a facelet page, the following markup
+ would cause such an attribute to be added.
<h:button id="start_a" value="enter flow-a" outcome="flow-a">
+ <f:attribute name="to-flow-document-id" value="unique"/>
+</h:button>
+It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>ClientWindow on the rendering of this element.
+ ]]>If this element has children, + they must be ignored by default. Implementions may provide a + configuration option that allows this element to render its + children.
]]>It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>Assigns one or more space-separated CSS class names to each + "tr"
+ + + + ]]>Decode Behavior
+ +Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If there is no
+ entry in the Map for the "clientId" of this
+ component, pass "false" to the setSubmittedValue()
+ method of the component, which must be an instance of
+ EditableValueHolder. If there is an entry, and its
+ value is equal, ignoring case and without quotes, to any of the
+ Strings: "on", "yes" or "true" pass true to the
+ setSubmittedValue() method of the component.
Encode Behavior
+ ++ Render the clientId of the component as the value of the "name" + attribute. If the current value of the component is "true", + output the "checked" attribute (must be rendered as checked="checked"). + If the "styleClass" attribute is specified, render its value as the value + of the "class" attribute.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>See the "Decode + Behavior for UISelectMany Components" section.
+ +Encode Behavior
+ +Render a "table" element. If the "styleClass" is specified,
+ render the value of the "styleClass" attribute as the value of the
+ "class" attribute on the "table" element. If the "style", or
+ "border" attributes are specified, convey them and render their values as the "style"
+ and "border" attributes on the "table", respectively. If
+ the "layout" attribute is specified, and its value is
+ "pageDirection", render the children elements vertically,
+ otherwise horizontally, in the table. If any of the children are
+ an instance of SelectItemGroup, render them as a nested table.
+ Each of the children are ultimately rendererd as follows. Render
+ an "input" element of "type" "checkbox" for each child component.
+ Render the "name" attribute on the "input" element with the value
+ of the clientId of the component. Render an "id"
+ attribute on the "input" element. Each "id" value must be unique.
+ If the current SelectItem.isDisabled() returns true, render
+ "disabled" as the value of the "disabled" attribute. Close out
+ the "input" element. Render a "label" element. Render the "for"
+ attribute of the "label" element whose value is the corresponding
+ "input" element's "id" value.
+ If the current checkbox would be
+ rendered as being checked, and there is a "selectedClass"
+ attribute, append a space, followed by the value of the
+ "selectedClass" attribute to any existing "class" attribute value
+ on the label element. Otherwise, render the value of the
+ "selectedClass" attribute as the value of the "class" attribute on
+ the label element. If the current checkbox would be rendered as
+ being not checked, and there is a "unselectedClass" attribute,
+ append a space, followed by the value of the "unselectedClass"
+ attribute to any existing "class" attribute value on the label
+ element. Otherwise, render the value of the "unselectedClass"
+ attribute as the value of the "class" attribute on the label
+ element. If the
+ current checkbox would be rendered as being disabled, and there is a
+ "disabledClass" attribute, append a space, followed by the value
+ of the "disabledClass" attribute to any existing "class" attribute
+ value on the label element. Otherwise, render the value of the
+ "disabledClass" attribute as the value of the "class" attribute on
+ the label element. If the current checkbox would be rendered as
+ being enabled, and there is an "enabledClass" attribute, append a
+ space, followed by the value of the "enabledClass" attribute to any
+ existing "class" attribute value on the label element. Otherwise,
+ render the value of the "enabledClass" attribute as the value of
+ the "class" attribute on the label element. Close out the starting
+ "label" element and render the label value from SelectItem.getLabel().
+ Close out the "label" element. As an exception to the general rules about
+ how to handle the "id" attribute, render it as an attribute on the outer "table"
+ element, the value of which is the clientId of the
+ component per the rules at the beginning of this specification.
+ The value of the current SelectItem is rendered as the value of
+ the "value" attribute. Coerce the value of the currently rendered
+ child to the type of the parent UISelectMany value following the
+ Expression Language coercion rules, before comparing the values.
+ If the value of the enclosing UISelectMany matches the current
+ value, render "checked" as the value of the "checked" attribute.
+ See the "Rendering the option
+ elements" specification for ListboxRenderer for
+ more detail on how to render the "option" elements in this
+ renderer. Note that this
+ renderer does not support SelectItemGroup elements,
+ so the text that describes the rendering of
+ SelectItemGroup does not apply to this
+ renderer.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>java.util.Collection, or an EL expression that
+ evaluates to either 1. such a String, or 2. the
+ Class object itself. ]]>Decode Behavior
+ +This section documents the decode behavior for all renderers
+ that handle UISelectMany or UISelectOne
+ components.
If the collection type of the collection that provides the
+ value of this component is not one of the types handled by a
+ converter in the package jakarta.faces.convert, a
+ converter must explicitly be specified using the appropriate code
+ in the VDL. For example, use <f:converter> in
+ JSP or Facelet pages.
Decode Behavior for
+ UISelectMany components
Obtain the Map from the
+ "requestParameterValuesMap" property of the
+ ExternalContext. If the Map contains
+ an entry for the "clientId" of the component, pass the value of
+ the entry, cast to a String [], to the
+ setSubmittedValue() method of the component, which
+ must be an EditableValueHolder. If the
+ Map does not contain an entry, create an empty
+ String array and call
+ setSubmittedValue() with it.
Please check the javadoc for UISelectMany.getConvertedValue() + for additional requirements for renderers that render this kind + of component.
+ +Decode Behavior for
+ UISelectOne components
Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If there is a
+ Map entry for the "clientId" property of the
+ component, pass it to the setSubmittedValue() method
+ of the component. If the
+ Map does not contain an entry, call
+ setSubmittedValue() passing an empty
+ String as the argument.
Encode Behavior
+ +Render an HTML "select" element. Render the clientId of
+ the component as the value of the "name" attribute. If the "styleClass"
+ attribute is specified, render its value as the value of the "class"
+ attribute on the "select" element. If the component is a
+ UISelectMany instance, render "multiple" as the value of the
+ "multiple" attribute. If the "size" attribute is specified, render its
+ value as the value of the "size" attribute. Otherwise use the number of
+ items as the value of the "size" attribute.
Rendering the "option" elements
+ +The only valid children of this component are
+ UISelectItem or UISelectItems
+ instances. Iterate over the children of this component, and accrue
+ a list of jakarta.faces.model.SelectItem instances.
+ If the current child is a
+ SelectItem whose noSelctionProperty is
+ true, and the UISelectOne or
+ UISelectMany parent of this option has one or more
+ selected values that are not the "no selection"
+ SelectItem, and the component has a
+ "hideNoSelectionLabel" attribute whose value is true,
+ then the current option, which is the "no selection" option, must
+ not be rendered. If the current child is a
+ UISelectItem create a SelectIteminstance
+ from its itemValue, itemLabel, itemEscaped, and
+ itemDescription properties, add it to the list. If
+ the current child is a UISelectItems instance, call
+ its getValue() method. If the result is a
+ SelectItem bean, add it to the list. If the result
+ is an array of SelectItem beans, add each one to the
+ list. If the result is a Collection of
+ SelectItem beans, add each one to the list. If the
+ result is a Map, create a SelectItem
+ bean for each entry in the Map using the key as the
+ label, the value as the value, and null as the
+ description.
Iterate over the list
+ of SelectItem beans. If the current element is a
+ SelectItemGroup, render an "optgroup" element with a
+ "label" attribute, the value of which is the "label" property from
+ the current element, then call getSelectItems() and
+ render each element as below. If the current element is not a
+ SelectItemGroup, render an "option" element. In both the case of the "option"
+ element or the "optgroup" element, the implementation must pass
+ the UISelectItem or UISelectItems
+ corresponding to the SelectItem bean to the call to
+ ResponseWriter.startElement(). Follow the
+ conversion rules in the spec to obtain a renderable
+ String from the "value" property of the current
+ element, render that as the value of the "value" atribute. Now it
+ is time to see if the current element is the selected value. Call
+ its getSubmittedValue() method, casting the result to
+ an Object [], otherwise the component must be a
+ UISelectOne instance, call its
+ getSubmittedValue() method and create an Object
+ [] around the result. Determine the type of the resultant
+ array, if the resultant array is non-null, otherwise the type is
+ String. Coerce the current item value to this type
+ following the Expression Language coercion rules. If the
+ resultant array is non-null, we look in the array for a
+ value that, when we pass the renderable value to its
+ equals() method, it returns true,
+ meaning the current element is selected. If the resultant array
+ is null, if the component is a
+ UISelectMany, call its getValue()
+ method. If the result is a List obtain the values in
+ the list as an array. Otherwise, the component must be a
+ UISelectOne instance. Call its
+ getValue() method, which must be an Object array.
+ Look for an element in the resultant array that, 1. when we pass
+ the renderable value to its equals() method, it
+ returns true , or 2. if the renderable value is null,
+ and there is a null element in the array, also conclude that the
+ current element is selected. Otherwise the current element is not
+ selected. Now, if the current value is selected, write out an
+ HTML boolean property "selected". If the current
+ SelectItem.isDisabled() returns true, render "disabled" as the
+ value of the "disabled" attribute. If the value of the
+ escape property is true, use the
+ writeText() method of ResponseWriter to
+ write out the value of the label property.
+ Otherwise, use the write() method of the
+ ResponseWriter to do so.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>java.util.Collection, or an EL expression that
+ evaluates to either 1. such a String, or 2. the
+ Class object itself. ]]>See the "Decode + Behavior for UISelectMany Components" section.
+ +Encode Behavior
+ +Render an HTML "select" element. Render the clientId of
+ the component as the value of the "name" attribute. If the "styleClass"
+ attribute is specified, render its value as the value of the "class"
+ attribute on the "select" element. If the component
+ to be rendered is a UISelectMany, render "multiple" as the value of
+ the "multiple" attribute. Render "1" as the value of the "size"
+ attribute. See the "Rendering the option
+ elements" specification for ListboxRenderer for
+ more detail on how to render the "option" elements in this
+ renderer.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>java.util.Collection, or an EL expression that
+ evaluates to either 1. such a String, or 2. the
+ Class object itself. ]]>See the "Decode + Behavior for UISelectOne Components" section.
+ +Encode Behavior
+ +Render an HTML "select" element. Render the clientId of
+ the component as the value of the "name" attribute. If the "styleClass"
+ attribute is specified, render its value as the value of the "class"
+ attribute on the "select" element. If the component
+ to be rendered is a UISelectMany, render "multiple" as the value of
+ the "multiple" attribute. If the "size" attribute is specified,
+ render its value as the value of the "size" attribute. Otherwise
+ use the number of items as the value of the "size" attribute. See
+ the "Rendering the option
+ elements" specification for ListboxRenderer for
+ more detail on how to render the "option" elements in this
+ renderer.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>See the "Decode + Behavior for UISelectOne Components" section.
+ +Encode Behavior
+ +Render an HTML "select" element. Render the clientId of the
+ component as the value of the "name" attribute. If the
+ "styleClass" attribute is specified, render its value as the value
+ of the "class" attribute on the "select" element. If the component
+ to be rendered is a UISelectMany, render "true" as the value of
+ the "multiple" attribute. Use the number of items as the value of
+ the "size" attribute. See the "Rendering
+ the option elements" specification for
+ ListboxRenderer for more detail on how to render the
+ "option" elements in this renderer.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>See the "Decode + Behavior for UISelectOne Components" section.
+ +Encode Behavior
+ +Render a "table" element. If the "styleClass" is specified,
+ render the value of the "styleClass" attribute as the value of the
+ "class" attribute on the "table" element. If the "style", "border"
+ attributes are specified, convey them and render their values as the "style"
+ and "border" attributes on the "table", respectively.. If
+ the "layout" attribute is specified, and its value is
+ "pageDirection", render the children elements vertically,
+ otherwise horizontally, in the table. If any of the children are
+ an instance of SelectItemGroup, render them as a nested table.
+ Each of the children are ultimately rendered as follows. Render
+ an "input" element of "type" "radio" for each child component.
+ Render the "name" attribute on the "input" element with the value
+ of the clientId of the component. Render an "id"
+ attribute on the "input" element. Each "id" value must be unique.
+ If the current SelectItem.isDisabled() returns true, render
+ "disabled" as the value of the "disabled" attribute. Close out
+ the "input" element. Render a "label" element. Render the "for"
+ attribute of the "label" element whose value is the corresponding
+ "input" element's "id" value. Render any "style" as the "class"
+ attribute on the "label" element. Close out the starting "label"
+ element and render the label value from SelectItem.getLabel().
+ Close out the "label" element. As an exception to the general
+ rules about how to handle the "id" attribute, render it as an
+ attribute on the outer "table" element, the value of which is the
+ clientId of the component per the rules at the
+ beginning of this specification. Coerce the value of the
+ currently rendered child to the type of the parent UISelectOne
+ value using the Expression Language coercion rules before
+ comparing the values. If the value of the currently rendered
+ child is equal to the value of the parent UISelectOne, render an
+ appropriate HTML boolean value indicating "checked" for the
+ enclosing "input". See the "Rendering the option elements"
+ specification for ListboxRenderer for more detail on
+ how to render the "option" elements in this renderer. Note that this renderer does
+ not support SelectItemGroup elements, so the text
+ that describes the rendering of SelectItemGroup does
+ not apply to this renderer.
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>value attribute is
+ absent then the one from first component of the group will be used. If
+ the UISelectItem child is absent then the one from first
+ component of the group will be used. When specified, the
+ group attribute disables the default rendering of the
+ "table" element and any attribute related to the rendering of the
+ "table" element, such as "border", is ignored.
+ ]]>Renders a composite component.
+ +Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Ask the argument UIComponent for its facet
+ under the key UIComponent.COMPOSITE_FACET_NAME.
+ Such a facet must exist. Call the encodeAll()
+ method on this facet.
Renders a facet at +this particular point in the composite component VDL page.
+ +Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +encodeBegin() and encodeEnd() must take no
+action for this renderer. Due to the specification of the
+<composite:insertChildren> tag handler, the component
+passed to the encodeChildern() method of this renderer will
+be the component with component-family
+jakarta.faces.Output and renderer-type equal to
+the one for this renderer. The implementation of
+encodeChildren(), must obtain the component attribute value
+under the key given by the value of the symbolic constant
+UIComponent.FACETS_KEY from the attributes map of the
+argument component. If not found, throw IOException. This
+value is referred to as "facetName" for discission. Find the closest
+ancestor composite component in which the argument component is nested.
+If no such component can be found, thow IOException.
+Otherwise, get the facet whose name is "facetName". If found call
+encodeAll() on the facet.
<script> element that renders the script
+ Resource specified by the optional
+ name attribute and library
+ attributes.
+
+The implementation of this renderer must
+have a @ListenerFor
+annotation attached to it, at the class level, declaring PostAddToViewEvent.class
+as the value of the systemEventClass attribute. The
+presence of this annotation on a renderer implies the renderer
+implements ComponentSystemEventListener,
+which this renderer must do. The implementation of
+processEvent() must extract the UIComponent
+from the argument event and look for the presence of the key
+"target" in the component's attribute Map. If
+and only if such a key is present, the implementation of
+processEvent() must pass the component to UIViewRoot.addComponentResource().
Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Common Algorithm for Obtaining A Resource to Render
+ +This algorithm is used by all resource renderers to obtain
+ a Resource instance which is then rendered in a
+ specific way depending on what kind of renderer is doing the
+ encoding.
Look in the component attribute Map for a
+ value under the key name.
Look in the component attribute Map for a
+ value under the key library. This attribute is
+ optional, therefore, library may be
+ null.
Create the resource by calling
+ Application.getResourceHandler.createResource(name,
+ library);.
This algorithm is used by all resource renderers to render the + resource.
+ +encodeBegin() must take no action.
Because this renderer returns true from
+ getRendersChildren(), the encodeChildren()
+ method must take the following action.
If there is no name attribute, and the
+ argument component has no children, and
+ ProjectStage is not
+ ProjectStage.Production, add a
+ FacesMessage for this component's clientId to the
+ FacesContext stating that if no name attribute is
+ present, and no body content is present either, then the user
+ should take action to correct this problem. In this case,
+ encodeChildren() must take no further
+ action.
If there is no name attribute and the argument
+ component does have children, the renderer
+ must ensure that those children are encoded as usual.
If there is a name attribute and the
+ argument component does have children, the
+ renderer must log a descriptive localized message stating that
+ the child content will be ignored. The resource referenced by
+ the name attribute will be rendered in
+ encodeEnd().
If there is a name attribute and the
+ argument component does not have children,
+ encodeChildren() must take no action.
encodeEnd() must take specific action based on
+ the specific kind of resource being rendered.
Use the algorithm Common Encode Behavior for
+ encodeBegin(), encodeChildren() and
+ getRendersChildren().
For encodeEnd(), use the algorithm Common
+ Algorithm for Obtaining A Resource to Render above to
+ obtain a reference to the Resource to be
+ encoded.
If this is NOT the first time this Resource has
+ been referenced on this request take no action and return.
Render a script element. Call
+ resource.getRequestPath(). If the result contains
+ a query string, take care to handle it correctly. Pass the
+ request path to a call to encodeResourceURL() on
+ the ExternalContext. Use the result as the value
+ of the "src" attribute. Use the result from calling
+ resource.getContentType() as the value of the
+ "type" attribute.
The libraryName for this resource.
]]>The + resourceName for this resource.
++ This attribute is required if the script is NOT inline. +
+The + target area for which this resource will be + rendered. For example, target="head" would + cause the resource to be rendered within the + head element. If no value is + specififed, the script element is rendered at the + same point in the view where the tag is + located. Currently + supported values for this attribute are "head", + "body", and "form".
]]><link> element that renders the style
+Resource specified by the optional name and
+library attributes.
+
+ Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Use the algorithm Common Encode Behavior for
+ encodeBegin(), encodeChildren() and
+ getRendersChildren().
For encodeEnd(), use the algorithm Common
+ Algorithm for Obtaining A Resource to Render to obtain a
+ reference to the Resource to be encoded.
Output a <link> element. Use the result from
+calling resource.getRequestPath() as the value of the
+"href" attribute, the result from calling
+resource.getContentType() as the value of the "type"
+attribute, and the literal string "stylesheet" as the value of the "rel"
+attribute. If this tag has a "media"
+attribute, use its value as the value of the "media" attribute.
+Otherwise, do not render a media attribute.
The implementation of this renderer must have a @ListenerFor
+annotation attached to it, at the class level, declaring PostAddToViewEvent.class
+as the value of the systemEventClass attribute. The presence of
+this annotation on a renderer implies the renderer implements ComponentSystemEventListener,
+which this renderer must do. The implementation of
+processEvent() must extract the UIComponent
+from the argument event pass it to UIViewRoot.addComponentResource(), specifying
+the literal string "head" as the last argument.
The stylsheet renderer must ensure that any stylesheets are included in the <head> of the document. +
+ +The libraryName for this resource.
]]>The + resourceName for this resource.
++ This attribute is required if the stylesheet is NOT inline. +
+The + media type for this stylesheet. For + example, media="screen" would cause the + resource to be rendered with the media + attribute of the link set to + screen.
]]>Render the markup for
+a <!DOCTYPE> declaration.
Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Output an XML Doctype using the provided attributes. Output the
+literal text <!DOCTYPE. The "rootElement" attribute is
+required and must be rendered next. If the "public" attribute is
+defined, render the literal text PUBLIC then render the
+value of the attribute inside double quotes. If the "system" attribute
+is defined, render it next, inside double quotes. Close the doctype
+declaration with the literal text >.
No relocation occurs with the output of this component. It is +rendered at whatever position in the view hierarchy it happens to be +encountered when traversing the view to render. Therefore, this +component must be located in the view hierarchy at the correct location +so that the final rendered markup has it in the proper place with +respect to the user agent that consumes the rendered markup. In practice +this means in front of the <html> or <h:html> element. +Furthermore, if multiple <h:doctype> components exist, +all of them will be rendered.
+ +If this component is present in a view, any DOCTYPE that would +otherwise have been rendered by virtue of being present in the VDL page +must be ignored.
+ +<head> element.
+
+Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Render the starting <head> element tag. Any
+attributes declared on the element must be conveyed unmodified to
+the rendered output. At some
+point before rendering the closing </head> element
+tag, render any resources that have been targeted for this "head"
+element:
+
UIViewRoot instance.List of component resources targeted for
+ this "head" element with a call to UIViewRoot.getComponentResources()
+ with the String "head" as the argument.List of UIComponent instances
+ and call encodeAll on each UIComponent instance.
+
+Any attributes declared on the element must be conveyed +unmodified to the rendered output.
+ +Note that due to the cascading nature of CSS files, the order
+ in which these files have been added to the view must be preserved
+ when rendering the references to the files within the
+ <head> element. Also, the end result of the
+ rendered <head> section must be that any CSS
+ files referenced due to previous calls to
+ addComponentResource() do not adversely interfere
+ with any CSS files manually placed in this section by the page
+ author.
Render the ending </head> element tag.
<body> element.
+
+Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Render the starting <body> element tag. Just before rendering the
+ closing </body> element tag, render any resources that have been targeted
+ for this "body" element:
+
UIViewRoot instance.List of component resources targeted for
+ this "body" element with a call to
+ UIViewRoot.getComponentResources() with the
+ String "body" as the argument. Render the ending
+ </body> element tag.List of UIComponent instances
+ and call encodeAll on each UIComponent instance.
+ Any attributes declared on the element must be conveyed +unmodified to the rendered output.
+ +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]>
+ Render a JavaScript function that invokes faces.push.init() function.
+
+ Render an HTML script element with an "id" attribute.
+ Render JavaScript function which invokes faces.push.init() function with data provided by
+ onopen, onmessage, onerror, onclose and connected
+ arguments, if any.
+
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. +
+ + + +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>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.
+ +]]>
Declares that the
+composite component whose contract is declared by the
+<cc:interface> in which this element is nested
+exposes an implementation of ActionSource suitable for use
+as the target of attached objects in the using page.
+Any attached objects suitable for implementations of
+ActionSource 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 <cc:valueHolder>
+also applies in the case of
+<cc:actionSource>.
Please see <cc: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 <cc: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 <cc:implementation> section. Space is
+used as the delimiter for compatibility with the IDREFS and NMTOKENS
+data types from the XML Schema.
The "hidden" flag is used to identify features that are intended only for tool use, and which should not be exposed to humans.
+ +]]> + +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
+<cc:interface> section. This element may be
+nested within other <cc: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.
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.
]]> + +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.
]]> + +The "hidden" flag is used to identify features that are intended only + for tool use, and which should not be exposed to humans. 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.
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 )
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().]]>
+
+
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.
]]> + +True if the page author must supply a value + for this attribute. The default value is false.
]]> + +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.
]]> + +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>
+
+
+]]>
+
+ 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
+<cc: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.
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.
Declares that the composite component whose contract is declared by
+the <cc: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.
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 evaluated value of this attribute will be passed as the first
+argument to the addClientBehavior() method on
+ClientBehaviorHolder.
+ 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 <cc:implementation>
+ to which the ActionListener should be mapped.
+
If present, this must be a space (not tab) separated list of client
+ids (relative to the top level component) of components within
+the <cc: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
+<cc: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 <cc:valueHolder>
+still applies.
+
Please see <cc: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 <cc:implementation>
+ to which the ActionListener should be mapped.
+
If present, this must be a space (not tab) separated
+ list of client
+ ids (relative to the top level component)
+ of components within
+ the <cc:implementation>
+ section. Space is
+ used as the delimiter for compatibility with the IDREFS and
+ NMTOKENS
+ data types from the XML Schema.
Declares that this composite component supports a facet + with the + name given by the value of the "name" attribute.
+ +Please see <cc:interface>
+ for a usage
+ example.
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 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.
+ + ]]>The name of the attribute as it must appear + on the composite component tag in the + using page.
+ + ]]>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.
+ + ]]>True if the page author must supply a facet with this + name.
+ + ]]>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.
+ + ]]>Defines the implementation of the composite
+ component. There must be zero or one of these in a
+ composite component markup file. If a
+ <cc:interface> element appears,
+ there must be a corresponding
+ <composite-implementation> element. If no
+ <cc:interface> element appears,
+ the <composite-implementation> element is
+ optional.
This element is used in the
+ <cc: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
+ <cc:implementation>
+ section. The normal
+ use-case for this element is to have only one occurrence within the
+ <cc:implementation>
+ section. Inserting
+ multiple occurrences may cause duplicate id errors. The results are
+ undefined if there are multiple occurrences of this element in the
+ <cc:implementation>
+ section.
The presence of this tag in
+a <cc: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 results are
+undefined if there are facets in the composite component tag in the
+using page, but there is no correspondingly named occurrence of this
+element in the <cc:implementation>
+section.
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.
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
+ <cc:actionSource> element is
+ included in the usage contract that refers to the inner
+ button in the <cc:implementation>
+ section.
Provide an "action" to invoke when the button is pressed. +
+ +In this case, a
+ <cc:attribute> element is included
+ in the usage contract that refers to the inner button in the
+ <cc: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
+ <cc:attribute> elements are included
+ in the usage contract and those parameters are referred to in
+ the <cc:implementation> section
+ using EL expressions like
+ #{cc.attrs.usernameLabel},
+ assuming usernameLabel is the name
+ of one of the <cc:attribute>
+ elements in the usage contract.
Add ValueChangeListeners,
+ Converters, or Validators to either
+ or both text fields.
+
In this case, a
+ <cc:editableValueHolder> element is
+ included in the usage contract that refers to the inner text
+ field in the <cc:implementation>
+ section. In the case of wanting to enable only adding a
+ Converter (and not a
+ ValueChangeListener or Validator, a
+ <cc:valueHolder> element would be
+ used.
Add facet children to the login panel.
+ +In this case, a <cc:facet>
+ element is included in the usage contract that refers to the
+ inner <cc:renderFacet> element in
+ the <cc:implementation> section.
+
For each of the behaviorial interfaces in
+ section 3.2 "Component Behavioral Interfaces" of the Jakarta Faces Specification Document,
+ there is a tag in the
+ cc: library to nest inside of the
+ <cc:interface> section.
+
If the <cc: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 <cc:interface> element
+ does appear, there must be an accompanying
+ <cc: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
+ <cc: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 <cc:actionSource>,
+ <cc:editableValueHolder>,
+ <cc: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 <cc: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 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 jakarta.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 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.
+ + ]]>The "hidden" flag is used to identify features that are + intended only for tool use, and which should not be exposed to humans.
+ + ]]>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.
+ + ]]>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.
+ + ]]>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.
+ + ]]>This element is used in the
+<cc: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
+ jakarta.faces.Output and renderer-type
+ jakarta.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.
Declares that the
+composite component whose contract is declared by the
+<cc: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
+ <cc:valueHolder> declaration on
+ line 2 of foo.xhtml:
It is possible to declare that a single
+<cc:valueHolder> element should cause multiple
+components within the <cc: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
+<cc: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 <cc:implementation> section. In
+this case, "targets" refers to the <h:inputText>
+components on lines 6 and 7 above.
Please see <cc:interface> for a usage
+example.
The "hidden" flag is used to identify features that are + intended only for tool use, and which should not be exposed to humans.
+ + ]]>
+ 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 <cc: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 <cc:implementation> section. Space is
+used as the delimiter for compatibility with the IDREFS and NMTOKENS
+data types from the XML Schema.
The core Jakarta Faces + tags that are independent of any particular + RenderKit.
+ ]]>The String value for ids
+ specified for execute and render may be specified as a search
+ expression as outlined in the JavaDocs for
+ UIComponent.findComponent(). The implementation
+ must resolve these ids as specified for
+ UIComponent.findComponent(). For example, consider
+ the following Facelets code.
When the button is pressed, + panel_1, in form_1 will be re-rendered, along with panel_2 in + form_2.
+ + ]]>'none'
+ without the quotes, no delay is used.
+
+ ]]>ClientBehaviorHolder#getEventNames().
+ For HTML components this would be the set of supported DOM events for the
+ component, plus "action" for Faces ActionSource components and "valueChange"
+ for Faces EditableValueHolder components. If not specified, the default
+ event is determined for the component via ClientBehaviorHolder#getDefaultEventName(). The DOM event name is the actual DOM
+ event name (for example: "click") as opposed to (for example: "onclick").
+
+
+ ]]>SearchKeywordResolver for the complete list of
+ keywords. If a literal is specified the ids must be
+ space delimited. If
+ not specified, the default value of "@this" is assumed. For
+ example, @this clientIdOne clientIdTwo.
+
+ When nested within a composite component,
+ and the value contains or implies the keyword @this,
+ then the keyword must be remapped to the targets attribute of the associated <composite:clientBehavior> declaration, if any,
+ else if the value is not an absolute search expression,
+ then it must be reinterpreted relative to the location of the <f:ajax> declaration.
SearchKeywordResolver for the complete list of
+ keywords. If a literal is specified the identifiers must
+ be space delimited. If not specified, the
+ default value of "@none" is assumed. For example, @this
+ clientIdOne clientIdTwo.
+
+ When nested within a composite component,
+ and the value contains or implies the keyword @this,
+ then the keyword must be remapped to the client ID of the associated <composite:implementation>,
+ else if the value is not an absolute search expression,
+ then it must be reinterpreted relative to the location of the <f:ajax> declaration.
render attribute as
+ a space separated list of client identifiers suitable for
+ passing directly to UIViewRoot.resetValues().
+ The implementation must cause an ActionListener
+ to be attached to the ActionSource component
+ in which this tag is nested that calls
+ UIViewRoot.resetValues() passing the value of
+ the render attribute as the argument.
+
+ ]]>Map.Entry in the Map<String, Object>
+ referenced by the value attribute of this tag, take the following action.
+ If parent.getAttributes().containsKey(entry.getKey()) returns
+ true, take no action for this entry. Otherwise, if
+ entry.getValue() is a ValueExpression call
+ parent.setValueExpression(entry.getKey(), entry.getValue()).
+ Otherwise, call parent.getAttributes.put(entry.getKey(), entry.getValue()).
+
+
+]]>
+ ValueExpression that evaluates to a Map<String, Object>.]]>java.time
+ formatter is being used, yet the dateStyle is set to "default",
+ the value "medium" is assumed.
+
+ ]]>java.time
+ formatter is being used, yet the timeStyle is set to "default",
+ the value "medium" is assumed.
+
+ ]]>java.time with
+ the name derived by upper casing the first letter. For
+ example, java.time.LocalDate for the value
+ "localDate". Default value is "date".
+
+ ]]>Locale + whose + predefined styles for numbers are used during formatting + and parsing. If not specified, the Locale returned by + FacesContext.getViewRoot().getLocale() will be used. + Expressions must evaluate to a java.util.Locale or a String that is valid to + pass as the first argument to the constructor + java.util.Locale(String language, String country). The + empty string is passed as the second argument.
+ + ]]>ComponentSystemEventListener
+ instances
+ on a component in a page.
+
+ ComponentSystemEvent parameter, with a return
+ type of void, or to a public method that takes no
+ arguments with a return type of void. In the latter case,
+ the method has no way of easily knowing where the event
+ came from, but this can be useful in cases where a
+ notification is needed that "an event happened".
+ ]]>value for "type" tag
+attribute |
+
+Type of event sent to listener method + | + +
|---|---|
| preRenderComponent + | + +jakarta.faces.event.PreRenderComponentEvent + | + +
| preRenderView + | + +jakarta.faces.event.PreRenderViewEvent + | + +
| postAddToView + | + +jakarta.faces.event.PostAddToViewEvent + | + +
| preValidate + | + +jakarta.faces.event.PreValidateEvent + | + +
| postValidate + | + +jakarta.faces.event.PostValidateEvent + | + +
In addition to these values, the fully qualified class name of any
+java class that extends
+jakarta.faces.event.ComponentSystemEvent may be used as the
+value of the "type" attribute.
Also, the @jakarta.faces.event.NamedEvent annotation may
+be attached to any java class that extends
+jakarta.faces.event.ComponentSystemEvent. This enables that
+event to be referenced from this attribute, as descibed in the javadocs
+for @NamedEvent.
+ When the facet contains more than one child the children will be + automatically put in a container UIPanel. +
+ + ]]>public static final fields of the given type.
+ The map key represents the constant field name as String.
+ The map value represents the actual constant field value.
+ This works for classes, interfaces and enums.
+
+ ]]><f:view>. This tag
+ must reside within the top level XHTML file for the given
+ viewId, or in a
+ template client, but not in a template. The
+ implementation must insure that the direct child of the
+ facet is a UIPanel, even if there
+ is only one child of the facet. The implementation must set
+ the id of the UIPanel to be the
+ value of the
+ UIViewRoot.METADATA_FACET_NAME
+ symbolic constant.
+
+ The implementation must allow templating for this element + according + to the following pattern.
+ +template client XHTML view, view01.xhtml
+ +Note line 4. The page author must ensure that the
+ <f:metadata> element does not
+ appear on a template or
+ included page. It must reside on the root page that corresponds to
+ the
+ viewId.
The template page, template.xhtml
+ +The page author is not required to use
+ templating, but if
+ they do, it must be done as shown above, (or with
+ <ui:include> in a similar
+ manner).
UIParameter component associated with this
+ jakarta.faces.Output
+ jakarta.faces.Link and
+ jakarta.faces.OutcomeTarget
+ jakarta.faces.Link.
+
+
+ ]]>passThroughAttributes Map of the UIComponent
+ associated with the closest parent UIComponent tag.
+
+ ]]>Renderer specific attribute, the value
+ specified here supercedes the one that would otherwise be
+ rendered by the Renderer]]>passThroughAttributes Map of the UIComponent
+ associated with the closest parent UIComponent tag.
+ For each Map.Entry in the Map<String, Object>
+ referenced by the value attribute of this tag, take the following action.
+ Call component.getPassThroughAttributes().put(entry.getKey(), entry.getValue()).
+
+]]>
+ ValueExpression that evaluates to a Map<String, Object>.]]>itemLabel
+ attribute must be escaped. This flag is set to "true" by
+ default.
+ ]]>When iterating over the
+ select items, toString() must be called on
+ the
+ string rendered attribute values.
Version 2 of the specification + introduces + several new attributes, described below. These are: var, itemValue, + itemLabel, itemDescription, itemDisabled, and itemLabelEscaped.
+ + + ]]>true.
+
+ ]]>Collection
+ or array. The member elements may be instances of
+ SelectItem or any Java Object. In the
+ case where the member elements are plain Java Objects,
+ several additional attributes must be used by the page
+ author to correctly identify the data to the enclosing
+ UISelectOne or UISelectMany
+ component, as shown in the following example.
+
+In the preceding example, the
+value attribute on line 1 points to a
+Collection<HobbitBean>. HobbitBean is
+just a regular Java Object (POJO) that conforms to JavaBeans naming
+conventions for its properties. The value attribute on
+line 2 points to a List<HobbitBean>, though it could
+just as well point to a Collection, array, or
+jakarta.faces.model.DataModel. The attributes on lines 3
+through 9, inclusive, leverage the fact that the value is a collection
+of POJOs.
+
value attribute under this request
+ scoped key so that it
+ may be referred to in EL for the value of other attributes.
+
+
+ ]]>UISelectMany or UISelectOne component,
+ and causes the addition of one SelectItemGroup of one or more SelectItem instances to the list of available options in the parent component.
+ This component accepts only children of type UISelectItems or UISelectItem.
+
+ ]]>UISelectMany or UISelectOne component,
+ and causes the addition of one or more SelectItemGroup of one or more SelectItem instances to the list of available options in the parent component.
+ This component accepts only children of type UISelectItems or UISelectItem.
+
+ ]]>value attribute of any nested UISelectItems or UISelectItem component.
+ ]]>false.
+ ]]>The implementation of this tag creates a special
+ ActionListener instance and registers it on
+ the
+ ActionSource associated with our most
+ immediate surrounding
+ instance of a tag whose implementation class is a subclass of
+ UIComponentTag. This tag creates no output
+ to the page
+ currently being created.
The ActionListener instance
+ created and installed by
+ this tag has the following behavior and contract.
ActionListener
+ instance
+ the first time the component for this tag is createdA validator that
+ delegates the validation of the local value to the Bean
+ Validation API. The validationGroups attribute serves as a
+ filter that instructs the Bean Validation API which
+ contraints to enforce. If there are any constraint
+ violations reported by Bean Validation, the value is
+ considered invalid. An
+ instance of this validator can participate in class-level
+ validation provided the preconditions mentioned in
+ <f:validateWholeBean /> are met. Please
+ see the documentation for <f:validateWholeBean
+ /> and
+ jakarta.faces.validator.BeanValidator.validate() for
+ the specification and usage example.
value attribute, for the sole
+ purpose of populating the bean with field values already
+ validated by <f:validateBean /> and then
+ performing class-level validation on the copy. Regardless
+ of the result of the class-level validation, the copy is
+ discarded. This feature must explicitly be enabled by
+ setting the application parameter specified in the javadoc
+ for the symbolic constant
+ jakarta.faces.validator.BeanValidator.ENABLE_VALIDATE_WHOLE_BEAN_PARAM_NAME.
+ If this parameter is not set, or is set to false, this tag
+ must be a no-op. A non-normative example follows the
+ specification of the feature.
+
+ At a high level, the feature provides for
+ a UIInput subclass that maintains its own
+ special private Validator that uses information
+ from one or more <f:validateBean />s to
+ perform class-level bean validation. For discussion, this
+ special Validator is called
+ the wholeBeanValidator.
This tag must be backed by a UIInput
+ component with the following specializations.
Override getSubmittedValue() to return a
+ non-null non empty String. This
+ allows UIInput.validate() to
+ call wholeBeanValidator.validate().
Override setConverter() to be a no-op.
+ It does not make sense to allow a converter to be
+ installed.
Override addValidator() to be a no-op
+ unless the argument is an instance
+ of wholeBeanValidator. It does not make sense to
+ allow additional validators to be installed.
Override validate() to take the
+ following actions.
If the feature is not enabled, return + immediately.
If the wholeBeanValidator has not yet
+ been installed, instantiate and pass it to
+ this.addValidator().
Call super.validate().
The wholeBeanValidator must have
+ a validate() method that performs the following
+ actions. Due to the above specification, this method will
+ only ever be passed the special UIInput
+ component.
Resolve the value of the component to
+ its Object. Assume that
+ this value is the bean whose properties are
+ intended to be populated by components whose values are each
+ validated by <f:validateBean /> tags.
+ For discussion, this bean is called the candidate
+ bean and the properties and their respective values are
+ called the candidate values. If the candidate
+ bean cannot be referenced, return immediately
+ from validate(). Use the information recorded
+ by each of those <f:validateBean /> tags
+ to ensure that none of the candidate values are
+ invalid. If any of them are invalid, return immediately
+ from validate(). This ensures class-level
+ validation is only performed on an instance whose fields are
+ all individually valid.
Otherwise it can be assumed that all field-level + validations for this class-level validation have passed.
+ +Class-level bean validation must operate on a + sufficiently populated bean instance. This differs from Faces + field-level validation, which prevents beans from being + populated with invalid values. To accomodate this + difference, the candidate bean must be copied, + populated with the already-validated candidate + values, and then subjected to class-level validation. + The copying must proceed in the following order.
+ +Invoke the newInstance() method on the
+ bean's Class. If this throws
+ any Exception, swallow it and
+ continue.
If the bean implements Serializable, use
+ that to copy the bean instance.
Otherwise, if the bean
+ implements Cloneable, clone the bean
+ instance.
Otherwise, if the bean has a copy constructor, use + that to copy the bean instance.
If none of these techniques yields a copy,
+ throw FacesException.
Populate the copied bean with the candidate + values.
+ +Obtain a reference to
+ a jakarta.validation.Validator instance using the
+ same steps described in the javadoc
+ for jakarta.faces.validator.BeanValidator.validate().
+ Let the instance be called beanValidator for
+ discussion.
Obtain the value of the validationGroups
+ attribute using the same steps described in the javadoc
+ for jakarta.faces.validator.BeanValidator.validate().
+ If this value is not present or not valid,
+ throw FacesException.
Call the validate method on
+ beanValidator, passing the populated copied bean
+ and the validation groups as arguments. The copied bean can
+ be discarded at this point.
If the
+ returned Set<ConstraintViolation> is
+ non-empty, for each element in the Set, create
+ a FacesMessage where the summary and detail are
+ the return from
+ calling ConstraintViolation.getMessage().
+ Capture all such FacesMessage instances into
+ a Collection and pass them
+ to ValidatorException. Using information
+ recorded by the <f:validateBean />
+ tag(s), call setValid(false) on all of the
+ components whose values contributed to this class-level
+ validation. This is essential to prevent the invalid value
+ from being set into the model during the update model values
+ phase. Finally, throw the exception.
This tag must be placed in the component tree after all + of the fields that are to be included in the multi-field + validation. If this precondition is not met, the results + of applying this tag are unspecified.
+ +This tag must be used in concert
+ with <f:validateBean /> and Bean
+ Validation. Here is a brief example of the common case of
+ ensuring two password fields are individually valid and also
+ both the same. The feature requires the use of
+ the validationGroups attribute on all of
+ the <f:validateBean /> tags and
+ the <f:validateWholeBean /> tag.
First, the ConstraintValidator
+ implementation.
+public class PasswordValidator implements ConstraintValidator<Password, PasswordHolder> {
+
+ @Override
+ public void initialize(Password constraintAnnotation) { }
+
+ @Override
+ public boolean isValid(PasswordHolder value, ConstraintValidatorContext context) {
+ boolean result;
+
+ result = value.getPassword1().equals(value.getPassword2());
+
+ return result;
+ }
+
+}
+Note that a PasswordHolder instance is
+ passed to the isValid() method. This method
+ will only be called if the individual properties of
+ the PasswordHolder are valid. This fact allows
+ the isValid() method to inspect the properties
+ and perform effective class-level validtion.
Next, the Constraint.
+@Constraint(validatedBy=PasswordValidator.class)
+@Target(TYPE)
+@Retention(RUNTIME)
+@interface Password {
+
+ String message() default "Password fields must match";
+ Class[] groups() default {};
+ Class[] payload() default {};
+}
+Now the backing bean constrained by
+ this Constraint. Note the use
+ of groups. Note the fact that the bean
+ implements Cloneable.
+@Named
+@RequestScoped
+@Password(groups = PasswordValidationGroup.class)
+public class BackingBean implements PasswordHolder, Cloneable {
+
+ private String password1;
+
+ private String password2;
+
+ public BackingBean() {
+ password1="";
+ password2="";
+ }
+
+ @Override
+ protected Object clone() throws CloneNotSupportedException {
+ BackingBean other = (BackingBean) super.clone();
+ other.setPassword1(this.getPassword1());
+ other.setPassword2(this.getPassword2());
+ return other;
+ }
+
+ @NotNull(groups=PasswordValidationGroup.class)
+ @Size(max=16, min=8, message="Password must be between 8 and 16 characters long",
+ groups = PasswordValidationGroup.class)
+ @Override
+ public String getPassword1() {
+ return password1;
+ }
+
+ public void setPassword1(String password1) {
+ this.password1 = password1;
+ }
+
+ @NotNull(groups=PasswordValidationGroup.class)
+ @Size(max=16, min=8, message="Password must be between 8 and 16 characters long",
+ groups = PasswordValidationGroup.class)
+ @Override
+ public String getPassword2() {
+ return password2;
+ }
+
+ public void setPassword2(String password2) {
+ this.password2 = password2;
+ }
+
+}
+Finally, the Facelets view.
+
+<h:panelGrid columns="2">
+
+ <h:outputText value="Password" />
+ <h:inputSecret id="password1" value='#{backingBean.password1}'>
+ <f:validateBean validationGroups="PasswordValidationGroup" />
+ </h:inputSecret>
+
+ <h:outputText value="Password again" />
+ <h:inputSecret id="password2" value='#{backingBean.password2}'>
+ <f:validateBean validationGroups="PasswordValidationGroup" />
+ </h:inputSecret>
+
+</h:panelGrid>
+
+<f:validateWholeBean value='#{backingBean}'
+ validationGroups="PasswordValidationGroup" />
+Usage outside of an EditableValueHolder
+ parent
If this element is nested within a
+ UIComponent tag that has other
+ UIComponent children, the validator will be
+ automatically added to all the child components as well as
+ this one. The implementation must ensure this occurs even if
+ the parent of this element is not an instance of
+ EditableValueHolder.
ViewDeclarationLanguage.createView(). Any
+ use of this attribute on a non-outer-most file is undefined.
+
+ If this attribute exists on the tag,
+ empty or not, the tag handler must create a
+ List<String> for the value of the attribute and
+ unconditionally call
+ FacesContext.setRresourceLibraryContracts() passing
+ that list value.
true, this view must not participate in
+ state saving or restoring. Note that transient views
+ may not be used with @ViewScoped managed
+ beans. The implementation must call
+ setTransient() on the
+ UIViewRoot, passing the value of the
+ attribute as specified in the markup.]]>
+ <f:metadata>,
+ a view action has no visual representation in the view.
+ This attribute has exactly the same effect on a view action
+ as the rendered attribute has on a visual
+ component. Specifically, if the value of this attribute
+ evaluates to false the component has no
+ effect.
+ ]]>UIViewParameter extends UIInput
+ all of the attributes and nested child content for any
+ UIInput tags are valid on this tag as well.
+
+ ]]>ValueChangeEvent
+ parameter,
+ with a return type of void, or
+ to a public method that takes no arguments with a return type
+ of void. In the latter case, the method has no way of easily
+ knowing what the new value is, but this can be useful in cases
+ where a notification is needed that "this value
+ changed".
+
+
+ ]]>jakarta.faces.push.PushContext interface. See also
+ jakarta.faces.push.Push API documentation for an
+ elaborate instruction on how to use
+ <f:websocket>.
+
+ ]]>UIComponent created by this tag.
+
+ ]]>UIWebsocket component to be created.
+
+ ]]>application, session and view, case insensitive.
+ When the value is application, then all channels with the same name throughout the application will receive the same push message.
+ When the value is session, then only the channels with the same name in the current user session will receive the same push message.
+ When the value is view, then only the channel in the current view will receive the push message.
+ The default scope is application.
+ When the user attribute is specified, then the default scope is session.
+
+ ]]>Serializable and preferably have low memory footprint.
+ Suggestion: use #{request.remoteUser} or #{someLoggedInUser.id}.
+ All open websockets on the same channel and user will receive the same push message from the server.
+
+ ]]>MessageEvent itself.
+
+ ]]>CloseEvent itself.
+ Note that this will not be invoked on final close of the websocket, even when the final close is caused by an error.
+ See also
+ RFC 6455 section 7.4.1
+ and
+ CloseCodes
+ API for an elaborate list of all close codes.
+
+ ]]>CloseEvent itself.
+ Note that this will also be invoked when the close is caused by an error and that you can inspect the close reason code if an actual connection error occurred and which one (i.e. when the code is not 1000 or 1008).
+ See also
+ RFC 6455 section 7.4.1
+ and
+ CloseCodes
+ API for an elaborate list of all close codes.
+
+ ]]>true.
+ It's interpreted as a JavaScript instruction whether to open or close the websocket push connection.
+ This attribute is implicitly re-evaluated on every ajax request by a PreRenderViewEvent listener on the UIViewRoot.
+ You can also explicitly set it to false and then manually control in JavaScript by faces.push.open(clientId) and faces.push.close(clientId).
+
+ ]]>true.
+ This attribute is implicitly re-evaluated on every ajax request by a PreRenderViewEvent listener on the UIViewRoot.
+ If the value changes to false while the websocket is already opened, then the websocket will implicitly be closed.
+
+ ]]>render attribute as
+ a space separated list of client identifiers suitable for
+ passing directly to UIViewRoot.resetValues().
+ The implementation must cause an ActionListener
+ to be attached to the ActionSource component
+ in which this tag is nested that calls
+ UIViewRoot.resetValues() passing the value of
+ the render attribute as the argument.
+ ]]>UIViewRoot.resetValues(). The identifiers
+ must be space delimited.
+ ]]>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.
+
+ First, we define a template: +
+
+ 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: +
+ +
+ 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: +
+ +
+ 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.
+
+ +]]>
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.
+
+ 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. +
+ + + ]]>
+
+ 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.
+
+
+ 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.
+ + + + ]]>
+
+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.
+
+
+
+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 "/".
+
+
+ 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. +
+ + + ]]>+ 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. +
+ + + + ]]>+ 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.
+ + + + + ]]>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.
+
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.
+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:
+
+
ui:decorate tag, ui:decorate can
+be used to decorate pieces of a page.
+
+
+ ]]>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 "/".
+
+
+
+ ]]>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.
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.
+ 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. +
+ + ]]> +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.
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.
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.
+
+
+ ]]>
Use this tag as an alternative to
+ h:dataTable or c:forEach
+ If the value attribute is not specified: iteration begins with the specified number (inclusive) as item.
+ If the value attribute is specified: a FacesException must be thrown.
+ If the corresponding end attribute is not specified: use 0 as default.
+ The corresponding end attribute may be less than the beginbegin attribute: iteration will take place in a reversed manner.
+
+ If the value attribute is not specified: iteration ends with the specified number (inclusive) as item.
+ If the value attribute is specified: a FacesException must be thrown.
+ If the corresponding begin attribute is not specified: use 0 as default.
+ The corresponding begin attribute may be greater than the end attribute: iteration will take place in a reversed manner.
+
+ If the value attribute is specified: iteration begins with the specified number as index.
+ If the value attribute is not specified: a FacesException must be thrown.
+ If the offset attribute is not specified: use 0 as default.
+ If the offset attribute is less than 0 or is greater than the size of the actual collection behind the value attribute: a FacesException must be thrown.
+
+ If the value attribute is specified: iteration ends when the specified number of times has been iterated (inclusive).
+ If the value attribute is not specified: a FacesException must be thrown.
+ If the size attribute is not specified: use the size of the actual collection behind the value attribute as default.
+ If the sum of the size attribute and the offset attribute is less than 0 or is greater than the size of the actual collection behind the value attribute: a FacesException must be thrown.
+ If the step attribute is specified: each skipped item must also be counted for the size attribute.
+
+ Iteration will only process every step items of the collection, starting with the first one.
+ If the step attribute is less than 1: a FacesException must be thrown.
+
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.
+ Name of the exported scoped variable for the current item of + the iteration. This scoped variable has nested visibility. +
+ + ]]> ++ 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
+ 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. +
+ + ]]> +
+ Boolean flag directing how the per-row component state of EditableValueHolder children should be handled across requests on the same view.
+ If set to true, then state for EditableValueHolder components in each row will not be discarded before a new row is rendered.
+ If not specified, the default value is false.
+
+ This attribute should be set only when the current repeat component contains UIForm children which in turn contains EditableValueHolder children.
+ This will only work reliably when the data model of the current repeat component does not change across requests on the same view by e.g. sorting, adding or removing rows.
+ The alternative is to use c:forEach instead.
+
Remove content from a page.
+ + + ]]>This tag library contains Jakarta Faces component tags for all + UIComponent + HTML RenderKit Renderer combinations as defined in + section 9.5 "Standard HTML RenderKit Tag Library" of the Jakarta Faces Specification Document.
+ ]]>getResourceURL() method of the ViewHandler
+ for this application, and passing the result through the encodeResourceURL()
+ method of the ExternalContext. Any child UIParameter components
+ are appended to the String to be used as the target URL as query parameters before rendering.
+ The entire target URL string must be passed through a call to the encodeResourceURL()
+ method of the ExternalContext. The name of the UIParameter goes on the
+ left hand side, and the value of the UIParameter on the right hand side. The name
+ and the value must be URLEncoded. Each UIParameter instance is separeted by an
+ ampersand, as dictated in the URL spec. The final encoded result will be written out to the
+ onclick attribute of the button as "window.location.href = 'It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +image attribute is not specified.]]>
+ ClientWindow on the rendering of this element.]]>
+ UIParameter components are appended to the String to be
+ output as the value of the "href" attribute as query parameters
+ before rendering. The entire "href" string must be passed through
+ a call to the encodeResourceURL() method of the
+ ExternalContext. The name of the UIParameter goes on
+ the left hand side, and the value of the UIParameter on the right
+ hand side. The name and the value must be URLEncoded. Each
+ UIParameter instance is separated by an ampersand, as dictated in
+ the URL spec. If the "fragment" attribute is specified, the value will be
+ included at the end of the resulting URL preceded by a hash mark.
+ If the "styleClass" attribute is specified, render
+ its value as the value of the "class" attribute. If the "id" attribute
+ is specified, follow the same steps as mentioned in the
+ "General
+ Notes on Encoding" regarding the "id" attribute for UIInput components.
+ If the "disabled" attribute is specified, do not render the HTML "a"
+ anchor element or the "href" element. Instead, render a "span" element.
+ If the "styleClass" attribute is specified, render its value as the value
+ of the "class" attribute on the "span". Render any pass-through attributes
+ on the "span".]]>
+ It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +ClientWindow on the rendering of this element.]]>
+ <head> element.
+
+ Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Render the starting <head> element tag. Any attributes declared on the element must be passed through
+ unmodified to the rendered output.
+ Just before rendering the
+ closing </head> element tag, render any resources that have been targeted
+ for this "head" element:
+
UIViewRoot instance.List of component resources targeted for
+ this "head" element with a call to UIViewRoot.getComponentResources()
+ with the String "head" as the argument.List of UIComponent instances
+ and call encodeAll on each UIComponent instance.
+
+ Any attributes declared on the element must be passed through + unmodified to the rendered output.
+ +</head> element tag.
+
+ ]]>
+ <body> element.
+
+ Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Render the starting <body> element tag. Just before rendering the
+ closing </body> element tag, render any resources that have been targeted
+ for this "body" element:
+
UIViewRoot instance.List of component resources targeted for
+ this "body" element with a call to
+ UIViewRoot.getComponentResources() with the
+ String "body" as the argument. Render the ending
+ </body> element tag.List of UIComponent instances
+ and call encodeAll on each UIComponent instance.
+ Any attributes declared on the element must be passed through + unmodified to the rendered output.
+ + ]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +image attribute is not specified.
+ ]]>It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +faces.ajax.request() function.
+
+
+
+ Render an HTML script element. If the value of the "name" attribute does not contain a
+ period . indicating a namespaced function name, then render JavaScript var
+ keyword, followed by a space character. Render the value of the "name" attribute, followed by
+ JavaScript assignment operator. Render JavaScript function which invokes faces.ajax.request()
+ with data provided by execute, render, onbegin,
+ oncomplete, onsuccess and onerror arguments, if any.
+
+ If the component being rendered has any UIParameter children, each one of them must be
+ encoded into params object of the options object of the faces.ajax.request()
+ function.
+
+ If the rendered JavaScript function is invoked with an object argument, each property must be
+ encoded into params object of the options object of the faces.ajax.request()
+ function. This will override any property with the same key.
+
+ Obtain the Map from the "requestParameterMap" property of the ExternalContext.
+ If the value in the Map for the value of the "jakarta.faces.source" equals to the "clientId" property of the component,
+ create a jakarta.faces.event.ActionEvent around the component, and pass it to the queueEvent() method of the component,
+ which must be an instance of UICommand.
+
name="ez.functionName".
+ ]]>window.
+ Defaults to false.
+ ]]>toString() of the returned Object is called to derive the logical outcome.
+ This outcome is passed to the NavigationHandler for this application.
+ ]]>void,
+ or to a public method that takes no arguments with a return type of void.
+ In the latter case,
+ the method has no way of easily knowing where the event came from,
+ but this can be useful in cases where a notification is needed that "some action happened".
+ ]]>UIViewRoot.resetValues().
+ The implementation must cause an ActionListener to be attached to the ActionSource
+ component in which this tag is nested that calls UIViewRoot.resetValues() passing the value
+ of the render attribute as the argument.
+ ]]>
+ Boolean flag directing how the per-row component state of EditableValueHolder children should be handled across requests on the same view.
+ If set to true, then state for EditableValueHolder components in each row will not be discarded before a new row is rendered.
+ If not specified, the default value is false.
+
+ This attribute should be set only when the current dataTable component contains UIForm children which in turn contains EditableValueHolder children.
+ This will only work reliably when the data model of the current dataTable component does not change across requests on the same view by e.g. sorting, adding or removing rows.
+ The alternative is to use c:forEach instead.
+
It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +text.
+ If a value is specified for which already a more specific component exist, such as
+ hidden, password, checkbox, radio, file, submit, image, reset and button,
+ and the ProjectStage is set to Development, then the renderer must add a warning message stating that the more specific component should be preferred.
+ ]]>
+ It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +Render the markup for a <link> element that
+ renders the style Resource specified by the optional
+ name and library attributes.
Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Use the algorithm Common Encode Behavior for
+ encodeBegin(), encodeChildren() and
+ getRendersChildren().
For encodeEnd(), use the algorithm Common
+ Algorithm for Obtaining A Resource to Render to obtain a
+ reference to the Resource to be encoded.
Output a <link> element. Use the result from
+ calling resource.getRequestPath() as the value of the
+ "href" attribute. Use the result from calling
+ resource.getContentType() as the value of the "type"
+ attribute, unless the value equals text/css and the current doctype is a HTML5 doctype..
+ Use the literal string "stylesheet" as the value of the "rel"
+ attribute, and the literal string "screen" as the value of the "media"
+ attribute.
The implementation of this renderer must have a @ListenerFor
+ annotation attached to it, at the class level, declaring PostAddToViewEvent.class
+ as the value of the systemEventClass attribute. The presence of
+ this annotation on a renderer implies the renderer implements ComponentSystemEventListener,
+ which this renderer must do. The implementation of
+ processEvent() must extract the UIComponent
+ from the argument event pass it to UIViewRoot.addComponentResource(), specifying
+ the literal string "head" as the last argument.
The stylsheet renderer must ensure that any stylesheets are included in the <head> of the document. +
+ + ]]> +The libraryName for this resource.
]]> +The resourceName for this resource.
++ This attribute is required if the stylesheet is NOT inline. +
+It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +Render the markup for a <script> element that
+ renders the script Resource specified by the optional
+ name attribute and library attributes.
The implementation of this renderer must have a @ListenerFor
+ annotation attached to it, at the class level, declaring PostAddToViewEvent.class
+ as the value of the systemEventClass attribute. The presence of
+ this annotation on a renderer implies the renderer implements ComponentSystemEventListener,
+ which this renderer must do. The implementation of
+ processEvent() must extract the UIComponent
+ from the argument event and look for the presence of the key
+ "target" in the component's attribute Map. If
+ and only if such a key is present, the implementation of
+ processEvent() must pass the component to UIViewRoot.addComponentResource().
Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Common Algorithm for Obtaining A Resource to Render
+ +This algorithm is used by all resource renderers to obtain
+ a Resource instance which is then rendered in a
+ specific way depending on what kind of renderer is doing the
+ encoding.
Look in the component attribute Map for a
+ value under the key name.
Look in the component attribute Map for a
+ value under the key library. This attribute is
+ optional, therefore, library may be
+ null.
Create the resource by calling
+ Application.getResourceHandler.createResource(name,
+ library);.
This algorithm is used by all resource renderers to render the + resource.
+ +encodeBegin() must take no action.
Because this renderer returns true from
+ getRendersChildren(), the encodeChildren()
+ method must take the following action.
If there is no name attribute, and the
+ argument component has no children, and
+ ProjectStage is not
+ ProjectStage.Production, add a
+ FacesMessage for this component's clientId to the
+ FacesContext stating that if no name attribute is
+ present, and no body content is present either, then the user
+ should take action to correct this problem. In this case,
+ encodeChildren() must take no further
+ action.
If there is no name attribute and the argument
+ component does have children, the renderer
+ must ensure that those children are encoded as usual.
If there is a name attribute and the
+ argument component does have children, the
+ renderer must log a descriptive localized message stating that
+ the child content will be ignored. The resource referenced by
+ the name attribute will be rendered in
+ encodeEnd().
If there is a name attribute and the
+ argument component does not have children,
+ encodeChildren() must take no action.
encodeEnd() must take specific action based on
+ the specific kind of resource being rendered.
Use the algorithm Common Encode Behavior for
+ encodeBegin(), encodeChildren() and
+ getRendersChildren().
For encodeEnd(), use the algorithm Common
+ Algorithm for Obtaining A Resource to Render above to
+ obtain a reference to the Resource to be
+ encoded.
If this is NOT the first time this Resource has
+ been referenced on this request take no action and return.
Render a script element. Use the result from calling
+ resource.getRequestPath() as the value of the "src"
+ attribue. Use the result from calling
+ resource.getContentType() as the value of the "type"
+ attribute, unless the value equals text/javascript and the current doctype is a HTML5 doctype.
The libraryName for this resource.
]]> +The resourceName for this resource.
++ This attribute is required if the script is NOT inline. +
+The target area for which this resource will be rendered. For example, target="head" would cause the resource to be rendered within the head element.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +clientId of the component per the rules at the beginning of this specification.SelectItemGroup, render them as a nested root element.SelectItem children are ultimately rendered as follows.
+ SelectItem.getLabel() is specified, and the group attribute is specified, render as follows.
+ SelectItem.getLabel().clientId of the component.SelectItem.getValue().UISelectOne value using the Expression Language coercion rules before comparing the values.
+ If the select item value is equal to the value of the parent UISelectOne, render an appropriate HTML boolean value indicating "checked" for the enclosing "input".SelectItem.isDisabled() returns true, render "disabled" as the value of the "disabled" attribute.SelectItem.getLabel() is specified, and the group attribute is not specified, render as follows.
+ SelectItem.getLabel().ListboxRenderer for more detail on how to render the "option" elements in this renderer.It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +Obtain the Map from the "requestParameterMap"
+ property of the ExternalContext. If the
+ Map contains an entry for the "clientId" of the
+ component, pass the value of the entry to the
+ setSubmittedValue() method of the component, which
+ must be an instance of EditableValueHolder, and
+ return. Otherwise, obtain the "request" property from the
+ ExternalContext and cast it to
+ jakarta.servlet.http.HttpServletRequest. Call
+ getParts() on the httpServletRequest. Iterate over
+ the parts. If the "name" property of the current part is equal to
+ the "clientId", then collect the part.
+ After the iteration, if the multiple attribute is set to true,
+ then pass java.util.Collection<jakarta.servlet.http.Part> to the setSubmittedValue() method of the component,
+ else pass the first item, if any, as jakarta.servlet.http.Part to the
+ setSubmittedValue() method of the component. If an
+ exception is thrown during the iteration, log the exception and
+ continue.
The standard implementation must override the
+ getConvertedValue() so that it filters out from the
+ submittedValue any parts which return
+ null or an empty string on getSubmittedFileName(),
+ or return 0 or less on getSize().
Any exception thrown when interacting with the underlying
+ multi-part API must be wrapped in a FacesException
+ and allowed to reach the ExceptionHandler.
Encode Behavior
+ +Render the clientId of the component as the value of the + "name" attribute. Do not render the "value" attribute. If the + "styleClass" attribute is specified, render its value as the value + of the "class" attribute.
+ +If ProjectStage is not
+ ProjectStage.Production, verify that the enclosing
+ form has an enctype attribute whose value is
+ multipart/form-data. If not, add a
+ FacesMessage for this component's clientId to the
+ FacesContext stating that file upload requires a form
+ with enctype equal to
+ multipart/form-data. If ProjectStage
+ is ProjectStage.Production, do not
+ do this verification.
multiple attribute is set to true,
+ then this must be assignable to java.util.Collection<jakarta.servlet.http.Part>,
+ else this must be assignable to jakarta.servlet.http.Part.]]>
+ ValueChangeEvent parameter,
+ with a return type of void, or
+ to a public method that takes no arguments with a return type
+ of void. In the latter case, the method has no way of easily
+ knowing what the new value is, but this can be useful in cases
+ where a notification is needed that "this value
+ changed".
+
+ ]]>
+ It is the page author's + responsibility to ensure that the user agent is capable of + correctly interpreting the value of this attribute.
]]> +Render the markup for
+ a <!DOCTYPE> declaration.
Decode Behavior
+ +No action is required during decode for this renderer.
+ +Encode Behavior
+ +Output an XML Doctype using the provided attributes. Output the
+ literal text <!DOCTYPE. The "rootElement" attribute is
+ required and must be rendered next. If the "public" attribute is
+ defined, render the literal text PUBLIC then render the
+ value of the attribute inside double quotes. If the "system" attribute
+ is defined, render it next, inside double quotes. Close the doctype
+ declaration with the literal text >.
No relocation occurs with the output of this component. It is + rendered at whatever position in the view hierarchy it happens to be + encountered when traversing the view to render. Therefore, this + component must be located in the view hierarchy at the correct location + so that the final rendered markup has it in the proper place with + respect to the user agent that consumes the rendered markup. In practice + this means in front of the <html> or <h:html> element. + Furthermore, if multiple <h:doctype> components exist, + all of them will be rendered.
+ +If this component is present in a view, any DOCTYPE that would + otherwise have been rendered by virtue of being present in the VDL page + must be ignored.
+ +Facelet tag attributes in
+ this namespace must be added to the pass through attribute map
+ on the UIComponent corresponding to the facelet
+ tag. There are no tags in this tag library.
Usage example
+ +<h:outputText value="Namespaced Attributes" pt:foo="bar" />
Would cause <span foo="bar">Namespaced Attributes</span> to be rendered.
The presence of an
+ attribute from this namespace on an otherwise non-Faces aware
+ markup element indicates that the markup element must be treated
+ as a Faces component that will be rendered equivalently to what is
+ specified directly in the Facelet page, with the added benefit
+ of being associated with a server side UIComponent
+ instance.
+
+
Please see the documentation for Java class jakarta.faces.view.facelets.TagDecorator.
component-family:
+ jakarta.faces.Panel with renderer-type:
+ jakarta.faces.passthrough.Element to be inserted in the tree.
+ This element is primarily intended to be used by the default
+ TagDecorator, when no match is found as described in
+ the javadoc for that class. The component that backs this element
+ must implement
+ jakarta.faces.component.behavior.ClientBehaviorHolder
+ and return "click" from its getDefaultEventName()
+ method. The list of events returned from its
+ getEventNames() method must include the "on*"
+ attributes below, ommitting the leading "on".
+
+
+ ]]>jakarta.faces.passthrough namespace and
+ its value must be set into the component's pass through
+ attributes map under the key given by the value of the symbolic
+ constant
+ jakarta.faces.render.Renderer.PASSTHROUGH_RENDERER_LOCALNAME_KEY.
+
+ ]]>TagException
+ is
+ thrown with an informative error message, ensuring page location
+ information is saved.
+
+ This handler operates in one of two ways. + +
The user has set "var", "value" and (optionally) + "scope" attributes.
The user has set "target", "property", and + "value" + attributes.
The first case takes precedence over the second.
+ + + ]]>Jakarta Faces 5.0 Facelet Tag Libraries that wish to conform to + this schema must declare it in the following manner.
+ + <facelet-taglib xmlns="https://jakarta.ee/xml/ns/jakartaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-facelettaglibrary_5_0.xsd" + version="5.0"> + + ... + + </facelet-taglib> + +The instance documents may indicate the published + version of the schema using xsi:schemaLocation attribute + for jakartaee namespace with the following location:
+ +https://jakarta.ee/xml/ns/jakartaee/web-facelettaglibrary_5_0.xsd
+ + ]]> +The attribute element defines an attribute for the nesting + tag. The attribute element may have several subelements + defining:
+ +a description of the attribute +
the name of the attribute +
whether the attribute is required or + optional +
the type of the attribute +
If not present then the default is "false", i.e + the attribute is optional.
+ + ]]> +
+
+ 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 )
As of 3.0 of the specification, this requirement is no longer
+ present: This element must have exactly one of
+ <component-type>, <resource-id>,
+ or <handler-class> among its child elements.
<resource-id>myCC/ccName.xhtml</resource-id>
Defines the canonical name of a tag or attribute being + defined.
+ +The name must conform to the lexical rules for an NCName
+ + + ]]> +https://jakarta.ee/xml/ns/jakartaee/web-facesconfig_4_0.xsd
+https://jakarta.ee/xml/ns/jakartaee/web-facesconfig_5_0.xsd
]]>