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

    Methods
    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

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.