html_basic

Tag Library Information 
InfoValue
ID (tag prefix)html_basic
URIhttp://xmlns.jcp.org/jsf/html
Tag Summary 
TagDescription
button
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. 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 = ''". If the developer has specified a custom onlclick the window.location.href name/value pair will be appended at the end of the developer specified script. 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 "onclick" element and assign the "disabled" attribute a value of true.
link
Render an HTML "a" anchor element. The value of the component is rendered as the anchor text and the outcome of the component is used to determine the target URL rendered in the "href" attribute. Any child 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".
head

Render the markup for a <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:

    • Obtain a UIViewRoot instance.
    • Obtain a List of component resources targeted for this "head" element with a call to UIViewRoot.getComponentResources() with the String "head" as the argument.
    • Iterate over the returned 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.

    Render the ending </head> element tag.

body

Render the markup for a <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:

    • Obtain a UIViewRoot instance.
    • Obtain a 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.
    • Iterate over the returned 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.

commandButton

Renders an HTML "input" element.

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 &amp;. 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 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.

commandLink

Render an HTML "a" anchor element that acts like a form submit button when clicked.

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 passthru attributes and the target attribute as pass-through 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'; 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 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(){#JSF_FUNCTION#}; return (a()==false) ? false : b();

    where #USER_FUNCTION# is the user's JavaScript and #JSF_FUNCTION# is the JavaScript rendered by 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 pass-through 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 JSP tag.

commandScript

Render a JavaScript function that invokes jsf.ajax.request() function.

Encode Behavior

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 jsf.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 jsf.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 jsf.ajax.request() function. This will override any property with the same key.

Decode Behavior

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.

dataTable

Renders an HTML "table" element compliant with the HTML 401 specification. Render the "caption" facet, if present, inside a "caption" element immediately below the "table" element. If the "captionClass" attribute is specified, render its value as the value of the "class" attribute on the "caption" element. If the "captionStyle" attribute is specified, render its value as the value of the "style" attribute on the "caption" element.

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 pass-through 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

    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

    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. 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.

form Renders an HTML "form" 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. 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.

    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.
    Just before rendering the closing </form> element tag, render any resources that have been targeted for this form:
    • Obtain a UIViewRoot instance.
    • Obtain a List of component resources targeted for this form with a call to UIViewRoot.getComponentResources() with the String "form" as the argument.
    • Iterate over the returned List of UIComponent instances and call encodeAll on each UIComponent instance.

graphicImage

Renders an HTML "img" element. Render the clientId as the value of the "id" 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 &amp;. If the "styleClass" attribute is specified, render its value as the value of the "class" attribute.

inputHidden

Renders an HTML "input" element of type "hidden".

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.

inputSecret

Renders an HTML "input" element of "type" "password".

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.

inputText

Renders an HTML "input" element of "type" "text".

Decode Behavior

    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.

inputTextarea

Renders an HTML "textarea" element.

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.

message

Render a single message for a specific component.

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.

messages

The same as for the Message renderer, but output all the messages. If an "id" attribute has been specified, it must be rendered on the outermost markup corresponding to this component. If the value of the "layout" attribute is "table", render nested "table", "tr", and "td" elements, in that order. If the value of the "layout" attribute is "list", or the "layout" attribute is not specified, render nested "ul", "li" elements, in that order. Output the value of the "style" attribute as the value of the "style" attribute, output the value of the "styleClass" attribute as the value of the "class" attribute, and output the dir and lang attributes. Output these values on the "table" element or the "ul" element. Output the values of the "errorStyle", "fatalStyle", "infoStyle", "warnStyle" attributes as the value of the "style" attribute on either the "tr" element or the "li" element. Output the values of the "errorClass", "fatalClass", "infoClass", "warnClass" attributes as the value of the "class" attribute on either the "tr" element or the "li" element. The component is a 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.

If an h:form does not contain a h:messages tag and the ProjectStage is set to Development the runtime will automatically add h:messages for debugging purposes.

outputFormat

Render parameterized text. Obtain the 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.

outputLabel Renders an HTML "label" element. 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, 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.
outputLink Render an HTML "a" anchor element. The value of the component is rendered as the value of the "href" attribute. Any child 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 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 pass-through attributes on the "span".
outputStylesheet

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, the result from calling resource.getContentType() as the value of the "type" attribute, 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.

outputText If the "styleClass", "style", "dir" or "lang" attributes are present, render a "span" element. If the "styleClass" attribute is present, render its value as the value of the "class" attribute. If the "style" attribute is present, pass it thru. If the "escape" attribute is not present, or it is present and its value is "true" all angle brackets should be converted to the ampersand xx semicolon syntax when rendering the value of the "value" attribute as the value of the component. If the "escape" attribute is present and is "false" the value of the component should be rendered as text without escaping.
outputScript

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);.

    Common Encode Behavior

      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 and the result from calling resource.getContentType() as the value of the "type" attribute.

panelGrid Renders an HTML "table" element, conforming to the rules in the HTML 401 specification. Render the "caption" facet, if present, inside a "caption" element immediately below the "table" element. If the "captionClass" attribute is specified, render its value as the value of the "class" attribute on the "caption" element. If the "captionStyle" attribute is specified, render its value as the value of the "style" attribute on the "caption" element. If the "styleClass" attribute is specified, render its value as the value of the "class" attribute. Render the pass-through attributes in the table below. Render the "header" facet, if present, inside of "thead", "tr", and "th" elements, nested in that order. If the "headerClass" attribute is specifed, render its value as the value of the "class" attribute on the "th" element. Render "colgroup" as the value of the "scope" attribute. Render the value of the "columns" attribute as the value of the "colspan" attribute on the "th" element. Render the "footer" facet if present, using similar logic to the rendering of the "header", but replacing "thead" with "tfoot", "th" with "td", and "headerClass" with "footerClass". Render the children of the UIPanel component inside of a "tbody" element. Render the children based on the value of the "columns" attribute, creating a new row each time a "columns" worth of children have been rendered. For the start of each row, render a "tr" element. Output the value of the "rowClasses" per the attribute description below. For each child, output a "td" element, attaching the value of the "columnClasses" attribute per the attribute description below. Recursively encode each child. Close out the "td" element. When done with the row, close out the "tr" element. If a child has "rendered==false" it is not rendered, and the column counter must not be incremented.
panelGroup Intended for use in situations when only one UIComponent child can be nested, such as in the case of facets. If the "style" or "styleClass" attributes are present, and the "layout" attribute is present with a value of "block", render a "div" element, outputting the value of the "style" attribute as the value of the "style" attribute and the value of the "styleClass" attribute as the value of the "class" attribute. Otherwise, if the "layout" attribute is not present, or the "layout" attribute contains a value other than "block", render a "span" element, outputting the value of the "style" attribute as the value of the "style" attribute, and the value of the "styleClass" attribute as the value of the "class" attribute.
selectBooleanCheckbox

Renders an HTML "input" element of type "checkbox".

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.

selectManyCheckbox

Render an HTML checkbox list.

Decode Behavior

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, pass them thru 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. Render any "style" as the "class" attribute on the "label" element. 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. 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.

selectManyListbox

Render an HTML option list.

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.

      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. 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.

selectManyMenu

Render an HTML option list.

Decode Behavior

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.

selectOneListbox

Render an HTML option list.

Decode Behavior

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.

selectOneMenu

Render an HTML option list.

Decode Behavior

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.

selectOneRadio

Render a set of html "input" elements of type "radio".

Decode Behavior

Encode Behavior

  • If the "group" attribute is not specified, render as follows.
    • Render a "table" 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.
    • If the "styleClass" attribute 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 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 SelectItem children are ultimately rendered as follows.
    • If the SelectItem.getLabel() is specified, and the group attribute is specified, render as follows.
      • Render a "label" element.
      • Render the "for" attribute of the "label" element whose value is the corresponding "input" element's "id" value.
      • Render any "class" attribute as the "class" attribute on the "label" element.
      • Render the label value from SelectItem.getLabel().
      • Close out the "label" element.
    • Render an "input" element of "type" "radio" for each child component.
    • Render an "id" attribute on the "input" element. Each "id" value must be unique.
    • If the "group" attribute is not specified, render the "name" attribute on the "input" element with the value of the clientId of the component.
    • If the "group" attribute is specified, render as follows.
      • Render the "name" attribute on the "input" element with the value of the "group" attribute.
      • If the "styleClass" attribute is specified, render the value of the "styleClass" attribute as the value of the "class" attribute on the "input" element.
      • If the "style" attribute is specified, pass it thru and render its value as the "style" attribute on the "input" element.
    • Render the input value from SelectItem.getValue().
    • Coerce the select item value to the type of the parent 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".
    • If the current SelectItem.isDisabled() returns true, render "disabled" as the value of the "disabled" attribute.
    • Close out the "input" element.
    • If the SelectItem.getLabel() is specified, and the group attribute is not specified, render as follows.
      • Render a "label" element.
      • Render the "for" attribute of the "label" element whose value is the corresponding "input" element's "id" value.
      • Render any "class" attribute as the "class" attribute on the "label" element.
      • Render the label value from SelectItem.getLabel().
      • Close out the "label" element.
  • See the "Rendering the option elements" specification for ListboxRenderer for more detail on how to render the "option" elements in this renderer.
column

Renders a UIComponent that represents a single column of data within a parent UIData component.

inputFile

Renders an HTML "input" element of "type" "file". The standard HTML_BASIC RenderKit specifies behavior that assumes Servlet 3.0 or later. Portlet implementations must override this implementation with a semantically equivalent one that functions under the constraints of the Portlet specification.

Decode Behavior

    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.

doctype

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.