public final class Components extends Object
Collection of utility methods for the JSF API with respect to working with UIComponent. There are several
traversal/lookup methods, there are several UIForm and UIInput related methods which makes it easier
to deal with forms and inputs.
Some examples:
// Get closest parent of given type. UIForm form = Components.getClosestParent(someUIInputComponent, UIForm.class);
// Get currently submitted form. UIForm form = Components.getCurrentForm();
// Get currently invoked command, useful for logging actions in a phase listener. UICommand command = Components.getCurrentCommand();
// Get the label of the given UIInput component as JSF uses for validation messages. String label = Components.getLabel(someUIInputComponent);
// Inside decode() and/or encode() of some custom component, validate if it has no children. Components.validateHasNoChildren(this);
// Programmatically include composite component. Components.includeCompositeComponent(someParentComponent, libraryName, tagName, id);
// Programmatically create value and action expressions.
UICommand command = new HtmlCommandButton();
command.setId("foo");
command.setValue(Components.createValueExpression("#{bundle['button.foo']}", String.class));
command.addClientBehavior("action", Components.createAjaxBehavior("#{bean.ajaxListener}"));
command.addActionListener(Components.createActionListenerMethodExpression("#{bean.actionListener}"));
command.setActionExpression(Components.createVoidMethodExpression("#{bean.action}"));
// Programmatically capture HTML output of a given view.
String mailHtml = Components.encodeHtml(Components.buildView("/WEB-INF/mail-template.xhtml"));
| Modifier and Type | Class and Description |
|---|---|
static class |
Components.ForEach
Builder class used to collect a number of query parameters for a visit (for each) of components in the JSF
component tree.
|
| Modifier and Type | Method and Description |
|---|---|
static UIComponent |
addScriptResourceToBody(String libraryName,
String resourceName)
Add given JavaScript resource to end of body of the current view.
|
static UIComponent |
addScriptResourceToHead(String libraryName,
String resourceName)
Add given JavaScript resource to end of head of the current view.
|
static UIComponent |
addScriptToBody(String script)
Add given JavaScript code as inline script to end of body of the current view.
|
static UIViewRoot |
buildView(String viewId)
Creates and builds a local view for the given view ID independently from the current view.
|
static MethodExpressionActionListener |
createActionListenerMethodExpression(String expression)
Create an action listener method expression based on the given EL expression.
|
static AjaxBehavior |
createAjaxBehavior(String expression)
Create an ajax behavior which should invoke an ajax listener method expression based on the given EL expression.
|
static MethodExpression |
createMethodExpression(String expression,
Class<?> returnType,
Class<?>... parameterTypes)
Create a method expression based on the given EL expression, the given return type and the given parameter types,
if any.
|
static ValueExpression |
createValueExpression(String expression,
Class<?> type)
Create an editable value expression based on the given EL expression and the given type.
|
static MethodExpression |
createVoidMethodExpression(String expression,
Class<?>... parameterTypes)
Create a void method expression based on the given EL expression and the given parameter types, if any.
|
static String |
encodeHtml(UIComponent component)
Encodes the given component locally as HTML, with UTF-8 character encoding, independently from the current view.
|
static <C extends UIComponent> |
findComponent(String clientId)
Returns the UI component matching the given client ID search expression.
|
static <C extends UIComponent> |
findComponentInChildren(UIComponent component,
String clientId)
Returns the UI component matching the given client ID search expression relative to the point
in the component tree of the given component, searching only in its children.
|
static <C extends UIComponent> |
findComponentInParents(UIComponent component,
String clientId)
Returns the UI component matching the given client ID search expression relative to the point
in the component tree of the given component, searching only in its parents.
|
static <C extends UIComponent> |
findComponentRelatively(UIComponent component,
String clientId)
Returns the UI component matching the given client ID search expression relative to the point
in the component tree of the given component.
|
static <C extends UIComponent> |
findComponentsInChildren(UIComponent component,
Class<C> type)
Returns a list of UI components matching the given type in children of the given component.
|
static Components.ForEach |
forEachComponent()
Invokes an operation on every component in the component tree.
|
static Components.ForEach |
forEachComponent(FacesContext facesContext)
Invokes an operation on every component in the component tree.
|
static <T> T |
getAttribute(UIComponent component,
String name)
Returns the attribute of the given component on the given name.
|
static <C extends UIComponent> |
getClosestParent(UIComponent component,
Class<C> parentType)
Returns from the given component the closest parent of the given parent type, or
null if none
is found. |
static UICommand |
getCurrentCommand()
Returns the currently invoked UI command component, or
null if there is none, which may happen when
the current request is not a postback request at all, or when the view has been changed by for example a
successful navigation. |
static UIComponent |
getCurrentComponent()
Returns the current UI component from the EL context.
|
static UIForm |
getCurrentForm()
Returns the currently submitted UI form component, or
null if there is none, which may happen when
the current request is not a postback request at all, or when the view has been changed by for example a
successful navigation. |
static <T> T |
getImmediateValue(UIInput input)
Returns the value of the given input component whereby any unconverted submitted string value will immediately
be converted/validated as this method is called.
|
static String |
getLabel(UIComponent input)
Returns the value of the
label attribute associated with the given UI component if any, else
the client ID. |
static String |
getOptionalLabel(UIComponent input)
Returns the value of the
label attribute associated with the given UI component if any, else
null. |
static List<ParamHolder> |
getParams(UIComponent component)
Returns an unmodifiable list with all child
UIParameter components (<f|o:param>) of
the given parent component as a list of ParamHolder instances. |
static <T> T |
getValue(EditableValueHolder component)
Returns the value of the given editable value holder component without the need to know if the given component
has already been converted/validated or not.
|
static boolean |
hasInvokedSubmit(UIComponent component)
Returns whether the given component has invoked the form submit.
|
static boolean |
hasSubmittedValue(EditableValueHolder component)
Returns whether the given editable value holder component has a submitted value.
|
static UIComponent |
includeCompositeComponent(UIComponent parent,
String libraryName,
String tagName,
String id)
Create and include the composite component of the given library and resource name as child of the given UI
component parent and return the created composite component.
|
static UIComponent |
includeCompositeComponent(UIComponent parent,
String libraryName,
String tagName,
String id,
Map<String,String> attributes)
Create and include the composite component of the given library and resource name as child of the given UI
component parent, set the given attributes on it and return the created composite component.
|
static void |
includeFacelet(UIComponent parent,
String path)
Include the Facelet file at the given (relative) path as child of the given UI component parent.
|
static boolean |
isEditable(UIInput input)
Returns whether the given UI input component is editable.
|
static boolean |
isRendered(UIComponent component)
Returns whether the given UI component and all of its parents is rendered.
|
static <C extends UIComponent> |
validateHasDirectParent(UIComponent component,
Class<C> parentType)
Validate if the given component has a direct parent of the given parent type.
|
static void |
validateHasNoChildren(UIComponent component)
Validate if the given component has no children.
|
static <C extends UIComponent> |
validateHasParent(UIComponent component,
Class<C> parentType)
Validate if the given component has a parent of the given parent type.
|
public static UIComponent getCurrentComponent()
UIComponent.getCurrentComponent(FacesContext)public static <T> T getAttribute(UIComponent component, String name)
T - The expected return type.component - The component to return the attribute of the given name for.name - The name of the attribute of the given component to be returned.ClassCastException - When T is of wrong type.public static boolean isRendered(UIComponent component)
rendered attribute, but also of all of its parents.component - The component to be checked.true if the given UI component and all of its parents is rendered.public static <C extends UIComponent> C findComponent(String clientId)
C - The expected component type.clientId - The client ID search expression.ClassCastException - When C is of wrong type.UIComponent.findComponent(String)public static <C extends UIComponent> C findComponentRelatively(UIComponent component, String clientId)
C - The expected component type.component - the component from which the relative search is started.clientId - The client ID search expression.ClassCastException - When C is of wrong type.UIComponent.findComponent(String)public static <C extends UIComponent> C findComponentInParents(UIComponent component, String clientId)
C - The expected component type.component - the component from which the relative search is started.clientId - The client ID search expression.ClassCastException - When C is of wrong type.UIComponent.findComponent(String)public static <C extends UIComponent> C findComponentInChildren(UIComponent component, String clientId)
C - The expected component type.component - the component from which the relative search is started.clientId - The client ID search expression.ClassCastException - When C is of wrong type.UIComponent.findComponent(String)public static <C extends UIComponent> List<C> findComponentsInChildren(UIComponent component, Class<C> type)
C - The generic component type.component - The component to search in its children for UI components matching the given type.type - The type of the UI components to be searched in children of the given component.public static <C extends UIComponent> C getClosestParent(UIComponent component, Class<C> parentType)
null if none
is found.C - The generic component type.component - The component to return the closest parent of the given parent type for.parentType - The parent type.null if none
is found.public static Components.ForEach forEachComponent()
This is a simplified version of regular component visiting that uses the builder pattern to provide the various optional parameters. Includes supports for only visiting components of a certain class type and two simplified functional interfaces / lambdas.
Components.ForEach.public static Components.ForEach forEachComponent(FacesContext facesContext)
This is a simplified version of regular component visiting that uses the builder pattern to provide the various optional parameters. Includes supports for only visiting components of a certain class type and two simplified functional interfaces / lambdas.
facesContext - the faces context used for tree visitingComponents.ForEach, using the given faces context.public static void includeFacelet(UIComponent parent, String path) throws IOException
<ui:include>. The path is relative to the current view ID and absolute
to the webcontent root.parent - The parent component to include the Facelet file in.path - The (relative) path to the Facelet file.IOException - Whenever something fails at I/O level. The caller should preferably not catch it, but just
redeclare it in the action method. The servletcontainer will handle it.FaceletContext.includeFacelet(UIComponent, String)public static UIComponent includeCompositeComponent(UIComponent parent, String libraryName, String tagName, String id)
xmlns:my="http://xmlns.jcp.org/jsf/composite/libraryName and
<my:tagName>. The given component ID must be unique relative to the current naming
container parent and is mandatory for functioning of input components inside the composite, if any.parent - The parent component to include the composite component in.libraryName - The library name of the composite component (path after "http://xmlns.jcp.org/jsf/composite/").tagName - The tag name of the composite component.id - The component ID of the composite component.public static UIComponent includeCompositeComponent(UIComponent parent, String libraryName, String tagName, String id, Map<String,String> attributes)
xmlns:my="http://xmlns.jcp.org/jsf/composite/libraryName and
<my:tagName>. The given component ID must be unique relative to the current naming
container parent and is mandatory for functioning of input components inside the composite, if any.
The attribute values must represent literal values or literal EL expressions, exactly like as you would declare in the view file. E.g.
attributes.put("foo", "#{bean.foo}");
attributes.put("bar", "true");
attributes.put("baz", "#{bean.baz(" + someId + ")}");
parent - The parent component to include the composite component in.libraryName - The library name of the composite component (path after "http://xmlns.jcp.org/jsf/composite/").tagName - The tag name of the composite component.id - The component ID of the composite component.attributes - The attributes to be set on the composite component.public static UIComponent addScriptToBody(String script)
Ajax.oncomplete(String...) instead.script - JavaScript code to be added as inline script to end of body of the current view.public static UIComponent addScriptResourceToBody(String libraryName, String resourceName)
libraryName - Library name of the JavaScript resource.resourceName - Resource name of the JavaScript resource.public static UIComponent addScriptResourceToHead(String libraryName, String resourceName)
<h:head> has already been encoded. During render response, rather use
addScriptResourceToBody(String, String) instead.libraryName - Library name of the JavaScript resource.resourceName - Resource name of the JavaScript resource.public static UIViewRoot buildView(String viewId) throws IOException
viewId - The ID of the view which needs to be created and built.IOException - Whenever something fails at I/O level. This can happen when the given view ID is unavailable or malformed.ViewHandler.createView(FacesContext, String),
ViewDeclarationLanguage.buildView(FacesContext, UIViewRoot)public static String encodeHtml(UIComponent component) throws IOException
component - The component to capture HTML output for.IOException - Whenever something fails at I/O level. This would be quite unexpected as it happens locally.UIComponent.encodeAll(FacesContext)public static UIForm getCurrentForm()
null if there is none, which may happen when
the current request is not a postback request at all, or when the view has been changed by for example a
successful navigation. If the latter is the case, you'd better invoke this method before navigation.UIForm.isSubmitted()public static UICommand getCurrentCommand()
null if there is none, which may happen when
the current request is not a postback request at all, or when the view has been changed by for example a
successful navigation. If the latter is the case, you'd better invoke this method before navigation.public static boolean isEditable(UIInput input)
input - The UI input component to be checked.true if the given UI input component is editable.public static String getLabel(UIComponent input)
label attribute associated with the given UI component if any, else
the client ID. It never returns null.input - The UI input component for which the label is to be retrieved.label attribute associated with the given UI component if any, else
the client ID.public static String getOptionalLabel(UIComponent input)
label attribute associated with the given UI component if any, else
null.input - The UI input component for which the label is to be retrieved.label attribute associated with the given UI component if any, else
null.public static <T> T getValue(EditableValueHolder component)
T - The expected return type.component - The editable value holder component to obtain the value for.ClassCastException - When T is of wrong type.public static <T> T getImmediateValue(UIInput input)
T - The expected return type.input - The input component to obtain the converted/validated value for.ClassCastException - When T is of wrong type.public static boolean hasSubmittedValue(EditableValueHolder component)
component - The editable value holder component to be checked.true if the given editable value holder component has a submitted value, otherwise
false.public static boolean hasInvokedSubmit(UIComponent component)
UICommand component. In ajax requests, that can also be among others an UIInput component.component - The component to be checked.true if the given component has invoked the form submit.public static List<ParamHolder> getParams(UIComponent component)
UIParameter components (<f|o:param>) of
the given parent component as a list of ParamHolder instances. Those with disabled=true and
an empty name are skipped.component - The parent component to retrieve all child UIParameter components from.UIParameter components having a non-empty name and not
disabled.public static ValueExpression createValueExpression(String expression, Class<?> type)
expression - The EL expression to represent an editable value expression.type - The type of the property referenced by the value expression.UIComponent.setValueExpression(String, ValueExpression).public static MethodExpression createMethodExpression(String expression, Class<?> returnType, Class<?>... parameterTypes)
Create a method expression based on the given EL expression, the given return type and the given parameter types, if any. As an example, the following action method examples,
public void submit1()public String submit2()public void submit3(String argument)public String submit4(String argument)public void submit5(String argument1, Long argument2)public String submit6(Long argument1, String argument2)can be created as follows:
createMethodExpression("#{bean.submit1}", Void.class);createMethodExpression("#{bean.submit2}", String.class);createMethodExpression("#{bean.submit3('foo')}", Void.class, String.class);createMethodExpression("#{bean.submit4('foo')}", String.class, String.class);createMethodExpression("#{bean.submit5('foo', 0)}", Void.class, String.class, Long.class);createMethodExpression("#{bean.submit6(0, 'foo')}", String.class, Long.class, String.class);expression - The EL expression to create a method expression for.returnType - The return type of the method expression. Can be null if you don't care about the
return type (e.g. void or String).parameterTypes - The parameter types of the method expression.UICommand.setActionExpression(MethodExpression).public static MethodExpression createVoidMethodExpression(String expression, Class<?>... parameterTypes)
Create a void method expression based on the given EL expression and the given parameter types, if any. As an example, the following action method examples,
public void submit1()public void submit3(String argument)public void submit5(String argument1, Long argument2)can be created as follows:
createVoidMethodExpression("#{bean.submit1}");createVoidMethodExpression("#{bean.submit3('foo')}", String.class);createVoidMethodExpression("#{bean.submit5('foo', 0)}", String.class, Long.class);expression - The EL expression to create a void method expression for.parameterTypes - The parameter types of the void method expression.UICommand.setActionExpression(MethodExpression).public static MethodExpressionActionListener createActionListenerMethodExpression(String expression)
ActionEvent as argument.
As an example, the following action method example,
public void actionListener(ActionEvent event)can be created as follows:
createActionListenerMethodExpression("#{bean.actionListener}");expression - The EL expression to create an action listener method expression for.UICommand.addActionListener(javax.faces.event.ActionListener).public static AjaxBehavior createAjaxBehavior(String expression)
AjaxBehaviorEvent as argument.
As an example, the following ajax listener example,
public void ajaxListener(AjaxBehaviorEvent event)can be created as follows:
createAjaxBehavior("#{bean.ajaxListener}");Note that this is essentially the programmatic equivalent of <f:ajax>. So if you intented
to create for example a <p:ajax> programmatically, then don't use this method.
expression - The EL expression to be invoked when the created ajax behavior is processed.UIComponentBase.addClientBehavior(String, ClientBehavior) whereby the string argument represents the
client event name, such as "action", "valueChange", "click", "blur", etc.public static <C extends UIComponent> void validateHasParent(UIComponent component, Class<C> parentType) throws IllegalArgumentException
C - The generic component type.component - The component to be validated.parentType - The parent type to be checked.IllegalArgumentException - When the given component doesn't have any parent of the given type.public static <C extends UIComponent> void validateHasDirectParent(UIComponent component, Class<C> parentType) throws IllegalArgumentException
C - The generic component type.component - The component to be validated.parentType - The parent type to be checked.IllegalArgumentException - When the given component doesn't have a direct parent of the given type.public static void validateHasNoChildren(UIComponent component) throws IllegalArgumentException
component - The component to be validated.IllegalArgumentException - When the given component has any children.Copyright © 2012–2015 OmniFaces. All rights reserved.