input element
for a button of type submit or reset.
The label text is specified by the component value.]]>
a element for a hyperlink that acts
like a submit button. This component must be placed inside
a form, and requires JavaScript to be enabled in the client.]]>
table element.]]>
form element. Child input components
will be submitted unless they have been disabled.]]>
img element, used to retrieve
and render a graphical image.]]>
input element
of type hidden.]]>
input element
of type password. On a redisplay,
any previously entered value will not
be rendered (for security reasons) unless the
redisplay property is set to
true.]]>
input element
of type text.]]>
textarea element.]]>
MessageFormat pattern string and substitutes in
parameter values from nested UIParameter components, and
renders the result. If the "dir" or "lang" attributes are
present, render a span element and pass them through
as attributes on the span.]]>
label element, used to define
an accessible label for a corresponding input element.]]>
a (hyperlink) element that may be
used to link to an arbitrary URL defined by the value
property.]]>
span element if I18N attributes, CSS styles or style
classes are specified.]]>
input element
of type checkbox. The checkbox will
be rendered as checked, or not, based on the value
of the value property.]]>
input elements of type
checkbox.]]>
select element, showing either all
available options or the specified number of options.]]>
select element, showing a single
available option at a time.]]>
select element, showing either all
available options or the specified number of options.]]>
select element, showing a single
available option at a time.]]>
input elements of type
radio.]]>
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 javax.faces.component.EditableValueHolder or
javax.faces.component.ActionSource or Renderers for
javax.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
javax.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.
General notes on encoding
If the value of the component's "rendered" property is false, the component, and its children must not be rendered.
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.
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
javax.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 the "styleClass" attribute is specified, render its value as the value of the "class" attribute.
General Behaviour
Both the encode and decode behavior require the ability to get the id/name for a hidden field 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 javax.faces.event.ActionEvent instance
around the component and call queueActionEvent() on
the component, passing the event.
Encode Behavior
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';
return false;
document.forms['CLIENT_ID'].submit()" 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. If the "styleClass" attribute is specified, render its value as the value of the "class" attribute. Render any non-UIParameter 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.
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 pass-through attributes are
also rendered on the "table" element.
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 UIData
component, if present, as the value of the "class" attribute on
the "th". Output "col" as the value of the "colgroup" attribute
on the "th" element.
Close out the "thead" element.
Rendering the footer
Follow the same process as for the header, except replace "header" with "footer", "th" with "td", "thead" with "tfoot", and "headerClass" with "footerClass". Do not render any "scope" attribute for the footer.
Rendering the table body
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.
Output a "tr" element. Output the value of the "rowClasses" per
the attribute description below. For each UIColumn
child, output a "td" element, attaching 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" 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.
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. If the "styleClass"
attribute is specified, render its value as the value of the
"class" attribute. Call 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.
ViewHandler
for this application, and passing the result
through the encodeResourceURL() method of the
ExternalContext. If present, render the value of the
alt attribute as the value of the "alt" attribute. If the
"styleClass" attribute is specified, render its value as the value
of the "class" 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.
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.
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.
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. This will be
the only message we render. Obtain the severity style for this
message. If the severity of the message is
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 the UIMessage has "showSummary" and
"showDetail" properties with the value "true", if we haven't
already written out the "span", output the "summary" as the value
of the "title" attribute on the "span". If we haven't already
written out a "title" attribute, and "showSummary" is true, output
the summary. If "showDetail" is true, output the detail. Close
out the span if necessary.
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.
]]>
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
pass through 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.]]>
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. If the "styleClass" attribute is specified, render
its value as the value of the "class" attribute.]]>
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. If the "styleClass" attribute is specified, render its value as the value of the "class" 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", "border" attributes are specified,
pass them thru. 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
a "label" element. Inside of the "label", render an "input" element
of "type" "checkbox" for each child component. 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 "id" attribute must not be output on each "input"
element. The value of the current SelectItem is rendered as the value of
the "value" attribute. If the value of the enclosing UISelectMany
matches the current value, render "checked" as the value of the
"checked" attribute. If the current SelectItem.isDisabled()
returns true, render "disabled" as the value of the "disabled"
attribute. Close out the "input" element and render the return
value from SelectItem.getLabel(). Close out the "label" element
and any other nested elements. See the "Rendering
the option elements" specification for
ListboxRenderer for more detail on how to render the
"option" elements in this renderer.
Decode Behavior
This section documents the decode behavior for all renderers
that handle UISelectMany or UISelectOne
components.
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.
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.
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
javax.faces.model.SelectItem instances. If the
current child is a UISelectItem create a
SelectIteminstance from its itemValue,
itemLabel 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 t othe
list. If the result is a Collection of
SelectItem beans, add each one to the list. If the
result isa 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. 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. 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.
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 "true" 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.
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. 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.
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.
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,
pass them thru. 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. Render a "label" element. Each of the children are
ultimately rendererd as an "input" element of "type" "radio". 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 "id" attribute must not be
output on each "input" element. Output the value of the "label"
attribute of the SelectItem after the "input"
element. 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". If
the current SelectItem.isDisabled() returns true, render
"disabled" as the value of the "disabled" attribute. See the "Rendering the option
elements" specification for ListboxRenderer for
more detail on how to render the "option" elements in this
renderer. Close out the "label" element.