- <h:body>
- <h:outputLabel id="label" for="@next" value="Test" />
- <h:inputText id="input">
- <f:ajax render="@this @next" />
- </h:inputText>
- <h:inputText id="input2" />
- </h:body>
Package javax.faces.component.search
APIs for searching for components in the component tree by using expressions.
This feature has two entry points: for the page author and for the Java programmer. Following is a brief overview of each.
For the Page Author
The following tags support the use of search
expressions: <h:message />
, <h:messages
/>
, <h:outputLabel />
,
and <f:ajax />
. Each of those tags have one or
more attributes whose value must be a client identifier. This feature
expands the capability of those attributes to be search expressions.
A search expression is space separated list of tokens, where a token
can either be a client identifier, a search keyword, or a combination
of both. See the specification
for SearchKeywordResolver
for the list of keywords that must be supported. See the
specification
for SearchExpressionHandler
to learn how the search is performed.
Here is a brief example of the page author use case:
For the Java Programmer
Using search expressions from Java code offers more flexibility.
One must obtain a handle to
the SearchExpressionHandler
and invoke methods on it as desired.
The following example resolves to a clientId:
- SearchExpressionHandler handler = facesContext.getApplication().getSearchExpressionHandler();
- SearchExpressionContext context = SearchExpressionContext.createSearchExpressionContext(facesContext, facesContext.getViewRoot());
- String clientId = handler.resolveClientId(context, ":form:container:@next");
The following example resolves to a component:
- SearchExpressionHandler handler = facesContext.getApplication().getSearchExpressionHandler();
- SearchExpressionContext context = SearchExpressionContext.createSearchExpressionContext(facesContext, facesContext.getViewRoot());
- handler.resolveComponent(context, ":form:container:@next",
- new ContextCallback() {
- public void invokeContextCallback(FacesContext context,
- UIComponent target) {
- // target == the resolved component
- }
- });
The following example uses multiple expressions and therefor resolves to multiple components:
- SearchExpressionHandler handler = facesContext.getApplication().getSearchExpressionHandler();
- SearchExpressionContext context = SearchExpressionContext.createSearchExpressionContext(facesContext, facesContext.getViewRoot());
- handler.resolveComponents(context, ":form:container:@next :input1 input2:@parent",
- new ContextCallback() {
- public void invokeContextCallback(FacesContext context,
- UIComponent target) {
- // target == the resolved component
- }
- });
Extending the Capabilities of the Component Search Facility
Creation of the SearchExpressionContext
As with other factories in JSF, the FactoryFinder
is
used by the system to create instances of
the SearchExpressionContext
which holds state during the
operation of this API.
Adding new SearchKewordResolver
s
See SearchKeywordResolver
for the specification of how the set of keywords can be expanded.
-
Interface Summary Interface Description UntargetableComponent Components implementing this interface are ignored by the algorithm - especially in the implementation of@child(n)
,@next
and@previous
. -
Class Summary Class Description SearchExpressionContext A context object that is used to hold state relating to resolve a search expression.SearchExpressionContextFactory Provide for separation of interface and implementation for theSearchExpressionContext
contract.SearchExpressionHandler The SearchExpressionHandler is responsible for resolving search expression(s)SearchExpressionHandlerWrapper Provides a simple implementation ofSearchExpressionHandler
that can be subclassed by developers wishing to provide specialized behavior to an existingSearchExpressionHandler
instance.SearchKeywordContext SearchKeywordContext provides context information that may be useful toSearchKeywordResolver.resolve(javax.faces.component.search.SearchKeywordContext, javax.faces.component.UIComponent, java.lang.String)
implementations.SearchKeywordResolver A SearchKeywordResolver is responsible for resolving a single keyword. -
Enum Summary Enum Description SearchExpressionHint An enum that specifies hints that impact the behavior of a component tree search. -
Exception Summary Exception Description ComponentNotFoundException TypedFacesException
for theSearchExpressionHandler
, if a component can't be resolved.