Package javax.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(javax.faces.view.facelets.Tag) method.

    • Inspect the attributes of the tag argument. If none of the attributes are declared to be in the http://xmlns.jcp.org/jsf 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(javax.faces.view.facelets.Tag) method, passing the argument tag. The first such entry that returns non-null from its decorate(javax.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 http://xmlns.jcp.org/jsf 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(javax.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 jsf:action h:commandLink
        a jsf:actionListener h:commandLink
        a jsf:value h:outputLink
        a jsf:outcome h:link
        body h:body
        button h:commandButton
        button jsf: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 jsf: means the tag is treated as if it were in the http://xmlns.jcp.org/jsf namespace. In actual Facelet pages, the namespace is what matters, not the prefix.

        If no matching entry is found, let jsf: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: http://xmlns.jcp.org/jsf/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 http://xmlns.jcp.org/jsf, 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 http://xmlns.jcp.org/jsf/passthrough. ConvertedTagAttribute's qualified name is the current attribute's local name prefixed by "p:". convertedTagAttribute's namespace must be http://xmlns.jcp.org/jsf/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", http://xmlns.jcp.org/jsf/html; if targetTag's prefix is "jsf", http://xmlns.jcp.org/jsf.

        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 spec prose document section titled, "Specification of the ViewDeclarationLanguage Implementation for Facelets for JSF 2.0".

    • Method Detail

      • 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