org.omnifaces.component.output.PathParam Maven / Gradle / Ivy

Go to download
/*
 * 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 javax.faces.component.FacesComponent;
import javax.faces.context.FacesContext;
import javax.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
	public static final String COMPONENT_TYPE = "org.omnifaces.component.output.PathParam";
	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.
	}

}