jakarta.faces.view.facelets.TagDecorator Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
* Copyright 2005-2007 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jakarta.faces.view.facelets;
/**
*
* Provides the ability to completely change the Tag
* before it's processed for compiling with the associated {@link TagHandler}.
*
*
*
*
*
* The runtime must provide a default implementation of this interface that performs the following actions in its
* {@link #decorate} method.
*
*
*
*
* -
*
* Inspect the attributes of the {@code tag} argument. If none of the attributes are declared to be in the {@code
* http://xmlns.jcp.org/jsf} namespace, iterate through the list of {@code TagDecorator} instances created from the
* values in the {@link jakarta.faces.application.ViewHandler#FACELETS_DECORATORS_PARAM_NAME} {@code context-param}, if
* any. For each entry, call its {@link #decorate} method, passing the argument {@code tag}. The first such entry that
* returns non-{@code null} from its {@link #decorate} method must cause the iteration to stop.
*
*
*
* -
*
* If one or more of the attributes of the {@code tag} argument are in the {@code http://xmlns.jcp.org/jsf} namespace,
* obtain a reference to decoratedTag as described in the following steps and iterate through the list
* of {@link TagDecorator} instances as described in the preceding step, but pass decoratedTag to each
* call to {@link #decorate}.
*
*
*
*
* -
*
* If the namespace of the tag is any namespace other than the empty string or {@code http://www.w3.org/1999/xhtml},
* throw a {@link FaceletException}.
*
*
*
* -
*
* Let localName be the return from {@link 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 {@code 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 {@code
* 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 {@code jsf:element} be the value of targetTag
*
*
*
*
* -
*
* Convert all the attributes of the argument {@code tag} as follows. First, create a new instance of
* {@link TagAttribute} with the following characteristics: location: from the argument {@code
* tag}'s location, namespace: {@code
* http://xmlns.jcp.org/jsf/passthrough}, local name: value of
* {@link jakarta.faces.render.Renderer#PASSTHROUGH_RENDERER_LOCALNAME_KEY}, qualified name: same as local name with the
* "p:" prefix, value: from the argument {@code tag}'s local name. Let this {@code TagAttribute} be
* elementNameTagAttribute.
*
*
*
* For each of argument {@code tag}'s attributes obtain a reference to a {@link TagAttribute} with the following
* characteristics. For discussion let such an attribute be convertedTagAttribute.
*
*
*
*
* -
*
* convertedTagAttribute's location: from the argument {@code tag}'s location.
*
*
*
* -
*
* If the current attribute's namespace is {@code
* 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 {@code UIComponent} instance represented by this
* markup.
*
* -
*
* If the current attribute's namespace is non-empty and different from the argument {@code tag}'s namespace, let the
* current attribute be convertedTagAttribute.
*
*
*
* -
*
* Otherwise, assume the current attribute's namespace is {@code
* 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 {@code
* http://xmlns.jcp.org/jsf/passthrough}.
*
*
*
*
*
*
* Create a {@link TagAttributes} instance containing elementNameTagAttribute and all the
* convertedTagAttributes.
*
*
*
*
* -
*
* Create a new {@link Tag} instance with the following characteristics.
*
*
*
* location: from the argument {@code tag}'s location.
*
*
*
* namespace: if targetTag's prefix is "h", {@code
* http://xmlns.jcp.org/jsf/html}; if targetTag's prefix is "jsf", {@code http://xmlns.jcp.org/jsf}.
*
*
*
* local name: the local name from the target tag column.
*
*
*
* attributes: the {@link TagAttributes} from the preceding step.
*
*
* Let this new {@link Tag} instance be convertedTag.
*
*
*
*
*
*
*
*
*
*
* The {@link Tag} instance returned from this decoration process must ultimately be passed to a {@link FaceletHandler}
* instance as described in the spec prose document section titled, "Specification of the ViewDeclarationLanguage
* Implementation for Facelets for Jakarta Server Faces 2.0".
*
*
*
*
*/
public interface TagDecorator {
/**
* If handled, return a new Tag instance, otherwise return null
*
* @param tag tag to be decorated
* @return a decorated tag, otherwise null
*/
Tag decorate(Tag tag);
}