Package jakarta.faces.view.facelets

Interface TagDecorator

public interface TagDecorator

Provides the ability to completely change the Tag before it's processed for compiling with the associated TagHandler.

The runtime must provide a default implementation of this interface that performs the following actions in its decorate(jakarta.faces.view.facelets.Tag) method.

• Inspect the attributes of the tag argument. If none of the attributes are declared to be in the jakarta.faces namespace, iterate through the list of TagDecorator instances created from the values in the ViewHandler.FACELETS_DECORATORS_PARAM_NAME context-param, if any. For each entry, call its decorate(jakarta.faces.view.facelets.Tag) method, passing the argument tag. The first such entry that returns non-null from its decorate(jakarta.faces.view.facelets.Tag) method must cause the iteration to stop.

• If one or more of the attributes of the tag argument are in the jakarta.faces namespace, obtain a reference to decoratedTag as described in the following steps and iterate through the list of TagDecorator instances as described in the preceding step, but pass decoratedTag to each call to decorate(jakarta.faces.view.facelets.Tag).

  • If the namespace of the tag is any namespace other than the empty string or http://www.w3.org/1999/xhtml, throw a FaceletException.

  • Let localName be the return from Tag.getLocalName(). Use localName to identify an entry in a data structure based on the following table. Once an entry has been identified, let targetTag be the value of the "target tag" column for that entry.

    localName and selector attribute to tag mapping

    localName	selector attribute	target tag
    a	faces:action	h:commandLink
    a	faces:actionListener	h:commandLink
    a	faces:value	h:outputLink
    a	faces:outcome	h:link
    body		h:body
    button		h:commandButton
    button	faces:outcome	h:button
    form		h:form
    head		h:head
    img		h:graphicImage
    input	type="button"	h:commandButton
    input	type="checkbox"	h:selectBooleanCheckbox
    input	type="color"	h:inputText
    input	type="date"
    input	type="datetime"
    input	type="datetime-local"
    input	type="email"
    input	type="month"
    input	type="number"
    input	type="range"
    input	type="search"
    input	type="time"
    input	type="url"
    input	type="week"
    input	type="file"	h:inputFile
    input	type="hidden"	h:inputHidden
    input	type="password"	h:inputSecret
    input	type="reset"	h:commandButton
    input	type="submit"	h:commandButton
    input	type="*"	h:inputText
    label		h:outputLabel
    link		h:outputStylesheet
    script		h:outputScript
    select	multiple="*"	h:selectManyListbox
    select		h:selectOneListbox
    textarea		h:inputTextArea

    In the case where there are multiple rows with the same localName, find a matching entry by using the argument tag's attributes and the value from the "selector attribute" column in the table in the given order. A selector attribute value of * indicates any value. In the table, a selector attribute name prefixed with faces: means the tag is treated as if it were in the jakarta.faces namespace. In actual Facelet pages, the namespace is what matters, not the prefix.

    If no matching entry is found, let faces:element be the value of targetTag

  • Convert all the attributes of the argument tag as follows. First, create a new instance of TagAttribute with the following characteristics: location: from the argument tag's location, namespace: jakarta.faces.passthrough, local name: value of Renderer.PASSTHROUGH_RENDERER_LOCALNAME_KEY, qualified name: same as local name with the "p:" prefix, value: from the argument tag's local name. Let this TagAttribute be elementNameTagAttribute.

    For each of argument tag's attributes obtain a reference to a TagAttribute with the following characteristics. For discussion let such an attribute be convertedTagAttribute.

    • convertedTagAttribute's location: from the argument tag's location.

    • If the current attribute's namespace is jakarta.faces, convertedTagAttribute's qualified name must be the current attribute's local name and convertedTagAttribute's namespace must be the empty string. This will have the effect of setting the current attribute as a proper property on the UIComponent instance represented by this markup.

    • If the current attribute's namespace is non-empty and different from the argument tag's namespace, let the current attribute be convertedTagAttribute.

    • Otherwise, assume the current attribute's namespace is jakarta.faces.passthrough. ConvertedTagAttribute's qualified name is the current attribute's local name prefixed by "p:". convertedTagAttribute's namespace must be jakarta.faces.passthrough.

    Create a TagAttributes instance containing elementNameTagAttribute and all the convertedTagAttributes.

  • Create a new Tag instance with the following characteristics.

    location: from the argument tag's location.

    namespace: if targetTag's prefix is "h", jakarta.faces.html; if targetTag's prefix is "faces", jakarta.faces.

    local name: the local name from the target tag column.

    attributes: the TagAttributes from the preceding step.

    Let this new Tag instance be convertedTag.

The Tag instance returned from this decoration process must ultimately be passed to a FaceletHandler instance as described in the Jakarta Faces Specification Document section 10.2.1 "Specification of the ViewDeclarationLanguage Implementation for Facelets for Jakarta Faces".

Method Summary

Modifier and Type	Method	Description
Tag	decorate(Tag tag)	If handled, return a new Tag instance, otherwise return null

Method Details

decorate

Tag decorate(Tag tag)

If handled, return a new Tag instance, otherwise return null

Parameters:

tag - tag to be decorated

Returns:

a decorated tag, otherwise null