javax.faces.view.facelets.TagDecorator Maven / Gradle / Ivy
Show all versions of jsf-api Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*
*
* This file incorporates work covered by the following copyright and
* permission notice:
*
* 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 javax.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
* javax.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
* 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
* javax.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 empty or different
* from the argument {@code 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 {@code UIComponent} instance represented by this
* markup.
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 JSF
* 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
*/
public Tag decorate(Tag tag);
}