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	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 empty or different from the argument tag's namespace, let the current attribute be convertedTagAttribute. This will have the effect of setting the current attribute as an attribute on the attributes map of the UIComponent instance represented by this markup.

    • 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 Summary

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

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