|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.faces.component.UIComponent
javax.faces.component.UIComponentBase
javax.faces.component.UIOutput
com.sun.webui.jsf.component.WebuiOutput
com.sun.webui.jsf.component.Label
public class Label
The Label component displays a label for a component and
implements methods to aid a Label
renderer to
render error
and required
indicators
based on the state of the labeled component.
A distinction is made between the component that is identified as the
target of the for
attribute and the component that is
used to determine the status of the indicators. This is because
the labeled component's id, as idententified by the value of the
for
property, may not be the literal id used for the
rendered HTML label element's "for" attribute. This is commonly the
case for complex components that depend on subcomponents for
parts of their behavior.
The Label
's for
property is used to
specify the id of the HTML label element's "for" attribute, and it
may not be a component's client id. However in many cases when the
JSP tag for a Label
is used, the only id available is the
client id or simple id of the labeled component. The Label
must
then find the component instance to determine if this is the
id to be rendered as the value of the HTML label element's "for"
attribute. A Label
renderer uses Label
methods to obtain an appropriate id. The Label
methods that facilitate finding the appropriate id do so in the
following way:
labeledComponent
property is not null
,
it is used directly to determine the appropriate id. This property
is usually set for performance reasons by components that have
labels as subcomponents, i.e. when the label
property
is used on some components, like TextField
.labeledComponent
property is null
the, for
property is used to obtain a component instance.
findComponent
is called with the value of the
for
property to locate a component instance.
If the value of the "for" property contains a leading
NamingContainer.SEPARATOR
character,
an explicit search from the view root is performed to find
the component.NamingContainer.SEPARATOR
then the value is treated as
an id of a sibling to the Label
and if the component
is still not found, it is treated as an id of a Label
child and findComponent
is used again to find the
component instance.NamingContainer.SEPARATOR
characters within the id, it
is treated as a fully qualifed id and a search from the view root is
performed.labeledComponent
and the for
property are null
a Label
child, if
one exists, is chosen as the target of the Label
.EditableValueHolder
child is chosen.EditableValueHolder
children then the first ComplexComponent
child is chosen.ComplexComponent
children then the first
child is chosen.for
property
or the labeledComponent
property), or as a child,
and it is an instance of ComplexComponent
,
the getLabeledElementId
method is
called on the instance and the returned value is used as the
rendered HTML label element's "for" attribute value, else the
component instance's client id is used.
The Label
uses a similar algorithm to obtain a
component instance to reference in order to determine the status
of the error
and required
indicators.
If the indicatorComponent
property is not null, it
should be used to determine the status of the error and required
indicators. If it is an instanceof ComplexComponent
the getIndicatorComponent
method should be called
to obtain the appropriate instance reference.
If the indicatorComponent
property is null
then fallback to the strategy for finding an instance for the
HTML label element's "for" attribute. The instance obtained from this
strategy, if an instance of ComplexComponent
has its
getIndicatorComponent
method called and the instance
returned is used, otherwise use the instance to determine the state
of the error and required indicators. This may or may not be
possible depending on the interfaces needed by the renderer
to render error and required indicators. The default renderer
expects the required
and valid
properties
to exist on the component instance used to determine the status
of the error and required indicators.
Field Summary | |
---|---|
static java.lang.String |
ERROR_FACET
The name of a developer defined facet for the error indicator. |
static java.lang.String |
ERROR_ID
The id suffix used for the error image. |
static java.lang.String |
REQUIRED_FACET
The name of a developer defined facet for the required indicator. |
static java.lang.String |
REQUIRED_ID
The id suffix used for the required image. |
Fields inherited from class javax.faces.component.UIOutput |
---|
COMPONENT_FAMILY, COMPONENT_TYPE |
Fields inherited from interface javax.faces.component.NamingContainer |
---|
SEPARATOR_CHAR |
Constructor Summary | |
---|---|
Label()
Default constructor. |
Method Summary | |
---|---|
int |
_getLabelLevel()
Style level for this label, where lower values typically specify progressively larger font sizes, and/or bolder font weights. |
java.lang.String |
getElement()
Deprecated. |
javax.faces.component.UIComponent |
getErrorIcon(Theme theme,
javax.faces.context.FacesContext context,
boolean valid)
Deprecated. |
javax.faces.component.UIComponent |
getErrorIcon(Theme theme,
javax.faces.context.FacesContext context,
java.lang.String toolTipErrorMsg)
Return a component that implements an error icon. |
java.lang.String |
getFamily()
Return the family for this component. |
java.lang.String |
getFor()
Use this attribute to specify the labeled component. |
java.lang.String |
getHtmlTemplate()
Get alternative HTML template to be used by this component. |
javax.faces.component.UIComponent |
getIndicatorComponent()
Return the indicatorComponent property. |
javax.faces.component.UIComponent |
getIndicatorComponent(javax.faces.context.FacesContext context,
boolean fallback)
Return a component instance to determine the status of the error and required indicators. |
javax.faces.component.EditableValueHolder |
getLabeledComponent()
Deprecated. |
javax.faces.component.UIComponent |
getLabeledComponent(javax.faces.context.FacesContext context)
If the labeledComponent member is not null
return it, else return the result of
getLabeledComponent(FacesContext,String) . |
java.lang.String |
getLabeledComponentId(javax.faces.context.FacesContext context)
Deprecated. This method now just calls getLabeledElementId |
java.lang.String |
getLabeledElementId(javax.faces.context.FacesContext context)
Return an id suitable for the HTML label element's "for" attribute. |
int |
getLabelLevel()
Return the label level. |
java.lang.String |
getOnClick()
Scripting code executed when a mouse click occurs over this component. |
java.lang.String |
getOnMouseDown()
Scripting code executed when the user presses a mouse button while the mouse pointer is on the component. |
java.lang.String |
getOnMouseMove()
Scripting code executed when the user moves the mouse pointer while over the component. |
java.lang.String |
getOnMouseOut()
Scripting code executed when a mouse out movement occurs over this component. |
java.lang.String |
getOnMouseOver()
Scripting code executed when the user moves the mouse pointer into the boundary of this component. |
java.lang.String |
getOnMouseUp()
Scripting code executed when the user releases a mouse button while the mouse pointer is on the component. |
java.lang.String |
getRendererType()
This implementation returns com.sun.webui.jsf.ajax.Label
for the renderer type if ComponentUtilities.isAjaxRequest()
returns true else super.getRendererType() . |
javax.faces.component.UIComponent |
getRequiredIcon(Theme theme,
javax.faces.context.FacesContext context)
Return a component that implements a required icon. |
java.lang.String |
getStyle()
CSS style(s) to be applied to the outermost HTML element when this component is rendered. |
java.lang.String |
getStyleClass()
CSS style class(es) to be applied to the outermost HTML element when this component is rendered. |
java.lang.Object |
getText()
The label text to be displayed for this label. |
java.lang.String |
getToolTip()
Sets the value of the title attribute for the HTML element. |
java.lang.Object |
getValue()
|
javax.el.ValueExpression |
getValueExpression(java.lang.String name)
Return the ValueExpression stored for the
specified name (if any), respecting any property aliases. |
boolean |
isHideIndicators()
Use the hideIndicators attribute to prevent display of the required and invalid icons with the label. |
boolean |
isRequiredIndicator()
Flag indicating that the labeled component should be marked as required. |
boolean |
isVisible()
Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. |
void |
restoreState(javax.faces.context.FacesContext _context,
java.lang.Object _state)
Restore the state of this component. |
java.lang.Object |
saveState(javax.faces.context.FacesContext _context)
Save the state of this component. |
void |
setFor(java.lang.String _for)
Use this attribute to specify the labeled component. |
void |
setHideIndicators(boolean hideIndicators)
Use the hideIndicators attribute to prevent display of the required and invalid icons with the label. |
void |
setHtmlTemplate(java.lang.String htmlTemplate)
Set alternative HTML template to be used by this component. |
void |
setIndicatorComponent(javax.faces.component.UIComponent component)
This method is used to set a component instance to determine the status of the error and required indicators. |
void |
setLabeledComponent(javax.faces.component.UIComponent comp)
Set labeledComponent to comp . |
void |
setLabelLevel(int labelLevel)
Style level for this label, where lower values typically specify progressively larger font sizes, and/or bolder font weights. |
void |
setOnClick(java.lang.String onClick)
Scripting code executed when a mouse click occurs over this component. |
void |
setOnMouseDown(java.lang.String onMouseDown)
Scripting code executed when the user presses a mouse button while the mouse pointer is on the component. |
void |
setOnMouseMove(java.lang.String onMouseMove)
Scripting code executed when the user moves the mouse pointer while over the component. |
void |
setOnMouseOut(java.lang.String onMouseOut)
Scripting code executed when a mouse out movement occurs over this component. |
void |
setOnMouseOver(java.lang.String onMouseOver)
Scripting code executed when the user moves the mouse pointer into the boundary of this component. |
void |
setOnMouseUp(java.lang.String onMouseUp)
Scripting code executed when the user releases a mouse button while the mouse pointer is on the component. |
void |
setRequiredIndicator(boolean requiredIndicator)
Flag indicating that the labeled component should be marked as required. |
void |
setStyle(java.lang.String style)
CSS style(s) to be applied to the outermost HTML element when this component is rendered. |
void |
setStyleClass(java.lang.String styleClass)
CSS style class(es) to be applied to the outermost HTML element when this component is rendered. |
void |
setText(java.lang.Object text)
The label text to be displayed for this label. |
void |
setToolTip(java.lang.String toolTip)
Sets the value of the title attribute for the HTML element. |
void |
setValueExpression(java.lang.String name,
javax.el.ValueExpression binding)
Set the ValueExpression stored for the
specified name (if any), respecting any property
aliases. |
void |
setVisible(boolean visible)
Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. |
Methods inherited from class com.sun.webui.jsf.component.WebuiOutput |
---|
processDecodes, processUpdates, processValidators, setConverter, setId, setRendered |
Methods inherited from class javax.faces.component.UIOutput |
---|
getConverter, getLocalValue, setValue |
Methods inherited from class javax.faces.component.UIComponentBase |
---|
broadcast, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, restoreAttachedState, saveAttachedState, setParent, setRendererType, setTransient, setValueBinding |
Methods inherited from class javax.faces.component.UIComponent |
---|
encodeAll, getContainerClientId |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String REQUIRED_ID
getRequiredIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext)
,
Constant Field Valuespublic static final java.lang.String REQUIRED_FACET
getRequiredIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext)
,
Constant Field Valuespublic static final java.lang.String ERROR_ID
getErrorIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext, boolean)
,
Constant Field Valuespublic static final java.lang.String ERROR_FACET
getErrorIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext, boolean)
,
Constant Field ValuesConstructor Detail |
---|
public Label()
com.sun.webui.jsf.widget.Label
.
Method Detail |
---|
public java.lang.String getFamily()
Return the family for this component.
getFamily
in class javax.faces.component.UIOutput
public java.lang.String getRendererType()
com.sun.webui.jsf.ajax.Label
for the renderer type if ComponentUtilities.isAjaxRequest()
returns true
else super.getRendererType()
.
getRendererType
in class javax.faces.component.UIComponentBase
public void setLabeledComponent(javax.faces.component.UIComponent comp)
labeledComponent
to comp
.
If comp
is null, labeledComponent
is set to null
.
public javax.faces.component.EditableValueHolder getLabeledComponent()
getFor
returns null, return the first EditableValueHolder
child of this Label
component.
If getFor
does not return null and the value
is a not an absolute id, search for the labeled component
using UIComponentBase.findComponent
.
Otherwise search for the labeled component from the view root
using UIComponentBase.findComponent
(In this
case the id is ensured to have ":" prepended to the id to
cause findComponent
to search from the view root).
setLabeledComponent
is called
to set the labeled component to the component
that is found or null.
getFor()
public java.lang.String getLabeledComponentId(javax.faces.context.FacesContext context)
getLabeledElementId
ComplexComponent
, call getPrimaryElementID
on
the labeled component and return that id.
If the labeled component is not an instance of
ComplexComponent
, call getClientId
on the
labeled component and return that id.
If the labeled component has not been set, and the
getFor
method returns a non null absolute
id, return that id.
If getFor
returns a relative id and the label's parent
is a NamingContainer
, return
an absolute client id constructed from the label's parent client id
and the id returned by the getFor
method. If the label's
parent is not a NamingContainer
return the id
returned by getFor
.
If getFor
returns null, return null.
getLabeledElementId(javax.faces.context.FacesContext)
public javax.faces.component.UIComponent getRequiredIcon(Theme theme, javax.faces.context.FacesContext context)
required
is found
that component is returned.
If a facet is not found an Icon
component instance is returned with the id
getId() + "_required"
.
If a facet is not defined then the returned Icon
component is created every time this method is called.
public javax.faces.component.UIComponent getErrorIcon(Theme theme, javax.faces.context.FacesContext context, boolean valid)
error
is found
that component is returned.
If a facet is not found an Icon
component instance is returned with the id
getId() + "_error"
.
If a facet is not defined then the returned Icon
component is created every time this method is called.
getErrorIcon(Theme, FacesContext, String)
public javax.faces.component.UIComponent getErrorIcon(Theme theme, javax.faces.context.FacesContext context, java.lang.String toolTipErrorMsg)
error
is found
that component is returned.
If a facet is not found an Icon
component instance is returned with the id
getId() + "_error"
.
If a facet is not defined then the returned Icon
component is created every time this method is called.
public java.lang.String getElement()
span
if the label is not labeling another
component, else return label
.
The deprecated behavior always returns label
.
public java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
getLabeledComponent(FacesContext)
to obtain
the labeled component instance. If the returned instance is
a ComplexComponent
call getLabeledElementId
on the instance and return that id, else return the instance's
client id. If getLabeledComponent
returns null
return the value of getFor()
.
context
- The faces context
public javax.faces.component.UIComponent getLabeledComponent(javax.faces.context.FacesContext context)
labeledComponent
member is not null
return it, else return the result of
getLabeledComponent(FacesContext,String)
.
public int getLabelLevel()
public javax.el.ValueExpression getValueExpression(java.lang.String name)
Return the ValueExpression
stored for the
specified name (if any), respecting any property aliases.
getValueExpression
in class javax.faces.component.UIComponentBase
name
- Name of value binding expression to retrievepublic void setValueExpression(java.lang.String name, javax.el.ValueExpression binding)
Set the ValueExpression
stored for the
specified name (if any), respecting any property
aliases.
setValueExpression
in class javax.faces.component.UIComponentBase
name
- Name of value binding to setbinding
- ValueExpression to set, or null to removepublic java.lang.Object getValue()
getValue
in interface javax.faces.component.ValueHolder
getValue
in class javax.faces.component.UIOutput
public java.lang.String getFor()
Use this attribute to specify the labeled component. The value of the attribute is the absolute client id of the component or the id of the component to be labeled. A relative component id may be used only if the labeled component is a sibling of the label.
public void setFor(java.lang.String _for)
Use this attribute to specify the labeled component. The value of the attribute is the absolute client id of the component or the id of the component to be labeled. A relative component id may be used only if the labeled component is a sibling of the label.
public boolean isHideIndicators()
Use the hideIndicators attribute to prevent display of the required and invalid icons with the label. When the required attribute on the component to be labeled is set to true, the required icon is displayed next to the label. If the user submits the page with an invalid value for the component, the invalid icon is displayed. This attribute is useful when the component has more than one label, and only one label should show the icons.
public void setHideIndicators(boolean hideIndicators)
Use the hideIndicators attribute to prevent display of the required and invalid icons with the label. When the required attribute on the component to be labeled is set to true, the required icon is displayed next to the label. If the user submits the page with an invalid value for the component, the invalid icon is displayed. This attribute is useful when the component has more than one label, and only one label should show the icons.
isHideIndicators()
public java.lang.String getHtmlTemplate()
public void setHtmlTemplate(java.lang.String htmlTemplate)
public int _getLabelLevel()
Style level for this label, where lower values typically specify progressively larger font sizes, and/or bolder font weights. Valid values are 1, 2, and 3. The default label level is 2. Any label level outside this range will result in no label level being added.
public void setLabelLevel(int labelLevel)
Style level for this label, where lower values typically specify progressively larger font sizes, and/or bolder font weights. Valid values are 1, 2, and 3. The default label level is 2. Any label level outside this range will result in no label level being added.
getLabelLevel()
public java.lang.String getOnClick()
Scripting code executed when a mouse click occurs over this component.
public void setOnClick(java.lang.String onClick)
Scripting code executed when a mouse click occurs over this component.
getOnClick()
public java.lang.String getOnMouseDown()
Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.
public void setOnMouseDown(java.lang.String onMouseDown)
Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.
getOnMouseDown()
public java.lang.String getOnMouseMove()
Scripting code executed when the user moves the mouse pointer while over the component.
public void setOnMouseMove(java.lang.String onMouseMove)
Scripting code executed when the user moves the mouse pointer while over the component.
getOnMouseMove()
public java.lang.String getOnMouseOut()
Scripting code executed when a mouse out movement occurs over this component.
public void setOnMouseOut(java.lang.String onMouseOut)
Scripting code executed when a mouse out movement occurs over this component.
getOnMouseOut()
public java.lang.String getOnMouseOver()
Scripting code executed when the user moves the mouse pointer into the boundary of this component.
public void setOnMouseOver(java.lang.String onMouseOver)
Scripting code executed when the user moves the mouse pointer into the boundary of this component.
getOnMouseOver()
public java.lang.String getOnMouseUp()
Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.
public void setOnMouseUp(java.lang.String onMouseUp)
Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.
getOnMouseUp()
public boolean isRequiredIndicator()
Flag indicating that the labeled component should be marked as required. It is only relevant if the labeled component is not a child of the label tag. Set this flag to ensure that the required icon shows up the first time the page is rendered.
public void setRequiredIndicator(boolean requiredIndicator)
Flag indicating that the labeled component should be marked as required. It is only relevant if the labeled component is not a child of the label tag. Set this flag to ensure that the required icon shows up the first time the page is rendered.
isRequiredIndicator()
public java.lang.String getStyle()
CSS style(s) to be applied to the outermost HTML element when this component is rendered.
public void setStyle(java.lang.String style)
CSS style(s) to be applied to the outermost HTML element when this component is rendered.
getStyle()
public java.lang.String getStyleClass()
CSS style class(es) to be applied to the outermost HTML element when this component is rendered.
public void setStyleClass(java.lang.String styleClass)
CSS style class(es) to be applied to the outermost HTML element when this component is rendered.
getStyleClass()
public java.lang.Object getText()
The label text to be displayed for this label. This attribute
can be set to a literal string, to a value binding expression
that corresponds to a property of a managed bean, or to a value
binding expression that corresponds to a message from a resource
bundle declared using f:loadBundle
.
public void setText(java.lang.Object text)
The label text to be displayed for this label. This attribute
can be set to a literal string, to a value binding expression
that corresponds to a property of a managed bean, or to a value
binding expression that corresponds to a message from a resource
bundle declared using f:loadBundle
.
getText()
public java.lang.String getToolTip()
Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.
public void setToolTip(java.lang.String toolTip)
Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.
getToolTip()
public boolean isVisible()
Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.
public void setVisible(boolean visible)
Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.
isVisible()
public javax.faces.component.UIComponent getIndicatorComponent()
indicatorComponent
property.
public javax.faces.component.UIComponent getIndicatorComponent(javax.faces.context.FacesContext context, boolean fallback)
indicatorComponent
is not null, and it is
a ComplexComponent
, call
getIndicatorComponent
and return the value, else
return indicatorComponent
.
If indicatorComponent
is null
call getLabeledComponent
. If the labeled component is a
ComplexComponent
call getIndicatorComponent
on it and return the value, else return the labeled component.
This method may return null
.
public void setIndicatorComponent(javax.faces.component.UIComponent component)
The motivation for this method and member is to ensure that the
label has an appropriate component instance to allow a renderer
to discern the state of the error and required indicators. This is
sometimes needed because the id value of the for
property is not always guaranteed to identify a component that
can provide the interfaces needed by a renderer to render
the error and required indicators.
It also provides an optimization so that findComponent
does not have to be called when rendering built in labels, similar
to the optimization benefit of the labeledComponent
property.
public void restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)
Restore the state of this component.
restoreState
in interface javax.faces.component.StateHolder
restoreState
in class javax.faces.component.UIOutput
public java.lang.Object saveState(javax.faces.context.FacesContext _context)
Save the state of this component.
saveState
in interface javax.faces.component.StateHolder
saveState
in class javax.faces.component.UIOutput
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |