org.omnifaces.component.output.PathParam Maven / Gradle / Ivy
Show all versions of omnifaces Show documentation
/*
* Copyright OmniFaces
*
* 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
*
* https://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 org.omnifaces.component.output;
import static org.omnifaces.util.FacesLocal.createConverter;
import jakarta.faces.component.FacesComponent;
import jakarta.faces.context.FacesContext;
import jakarta.faces.convert.Converter;
import org.omnifaces.facesviews.FacesViews;
import org.omnifaces.facesviews.FacesViewsViewHandler;
/**
* The <o:pathParam> is a component that extends the OmniFaces {@link Param} to support
* MultiViews feature of {@link FacesViews}. It is done by rendering the supplied parameters of such components
* as <h:link> and <h:button> among others as path parameters and not as
* query parameters as otherwise will be produced by <o:param> and <f:param> tags.
*
* The component has built-in support for a {@link Converter} to convert the supplied value to string by usual means via
* the converter attribute of the tag, or the nested <f:converter> tag, or just automatically
* if a converter is already registered for the target class via @FacesConverter(forClass).
*
* This component doesn't support returning encoded output of its children as parameter value in case no value is present.
* This feature is provided by {@link Param} component instead.
*
* Also, the name attribute must not be specified for this component as it already evaluates to a predefined one.
*
* This component is used to create bookmarkable URLs via standard outcome target components that take into account
* <o:pathParam> tags nested in the components. The path parameters will be rendered
* in the order they were declared for a view id that is defined as a multi view and if the view was
* not defined as a multi view then they won't be rendered at all. Additionally, declaring path parameters
* for a non-multi view will be logged as a warning and a faces warning message will be added for any
* stage different from Production.
*
* In the following example the link to the multi view page will be rendered with two path parameters:
*
* <h:link value="Link" outcome="multiview-supported-path">
* <o:pathParam value="first" />
* <o:pathParam value="second" />
* </h:link>
*
* The code above will be rendered as:
* <a id="..." name="..." href="/context-path/multiview-supported-path/first/second">Link</a>.
* The path parameters will be available via @Inject @Param(pathIndex=0) private String first; and
* @Inject @Param(pathIndex=1) private String second; the usual way.
*
* @author Sergey Kuntsel
* @param The type of the value.
* @since 3.6
* @see FacesViews
* @see FacesViewsViewHandler#getBookmarkableURL(FacesContext, String, java.util.Map, boolean)
*/
@FacesComponent(PathParam.COMPONENT_TYPE)
public class PathParam extends Param {
// Constants
/** The component type, which is {@value org.omnifaces.component.output.PathParam#COMPONENT_TYPE}. */
public static final String COMPONENT_TYPE = "org.omnifaces.component.output.PathParam";
/** The predefined value of the name attribute of this component. */
public static final String PATH_PARAM_NAME_ATTRIBUTE_VALUE = "org.omnifaces.pathparam";
// Actions
@Override
@SuppressWarnings("unchecked")
public String getValue() {
FacesContext context = getFacesContext();
Converter converter = getConverter();
Object value = getLocalValue();
if (converter == null && value != null) {
converter = createConverter(context, value.getClass());
}
if (converter != null) {
return converter.getAsString(context, this, (T) value);
}
return value != null ? value.toString() : null;
}
@Override
public void setName(String name) {
// Do nothing.
}
@Override
public String getName() {
return PATH_PARAM_NAME_ATTRIBUTE_VALUE; // Always return a predefined name.
}
}