com.sun.webui.jsf.component
Class Label

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UIOutput
              extended by com.sun.webui.jsf.component.WebuiOutput
                  extended by com.sun.webui.jsf.component.Label
All Implemented Interfaces:
javax.faces.component.NamingContainer, javax.faces.component.StateHolder, javax.faces.component.ValueHolder

public class Label
extends WebuiOutput
implements javax.faces.component.NamingContainer

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:

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

REQUIRED_ID

public static final java.lang.String REQUIRED_ID
The id suffix used for the required image.

See Also:
getRequiredIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext), Constant Field Values

REQUIRED_FACET

public static final java.lang.String REQUIRED_FACET
The name of a developer defined facet for the required indicator.

See Also:
getRequiredIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext), Constant Field Values

ERROR_ID

public static final java.lang.String ERROR_ID
The id suffix used for the error image.

See Also:
getErrorIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext, boolean), Constant Field Values

ERROR_FACET

public static final java.lang.String ERROR_FACET
The name of a developer defined facet for the error indicator.

See Also:
getErrorIcon(com.sun.webui.theme.Theme, javax.faces.context.FacesContext, boolean), Constant Field Values
Constructor Detail

Label

public Label()
Default constructor. This implementation sets the renderer type to com.sun.webui.jsf.widget.Label.

Method Detail

getFamily

public java.lang.String getFamily()

Return the family for this component.

Overrides:
getFamily in class javax.faces.component.UIOutput

getRendererType

public 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().

Overrides:
getRendererType in class javax.faces.component.UIComponentBase

setLabeledComponent

public void setLabeledComponent(javax.faces.component.UIComponent comp)
Set labeledComponent to comp. If comp is null, labeledComponent is set to null.


getLabeledComponent

public javax.faces.component.EditableValueHolder getLabeledComponent()
Deprecated. 

Return the labeled component instance. If the labeled component has not been set and 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.

Returns:
the labeled component instance or null
See Also:
getFor()

getLabeledComponentId

public java.lang.String getLabeledComponentId(javax.faces.context.FacesContext context)
Deprecated. This method now just calls getLabeledElementId

Return the absolute client id of the labeled component. If the labeled component is an instance of 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.

Returns:
the client id of the labeled component or null.
See Also:
getLabeledElementId(javax.faces.context.FacesContext)

getRequiredIcon

public javax.faces.component.UIComponent getRequiredIcon(Theme theme,
                                                         javax.faces.context.FacesContext context)
Return a component that implements a required icon. If a facet named 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.

Returns:
- required facet or an Icon instance

getErrorIcon

public javax.faces.component.UIComponent getErrorIcon(Theme theme,
                                                      javax.faces.context.FacesContext context,
                                                      boolean valid)
Deprecated. 

Return a component that implements an error icon. If a facet named 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.

Returns:
- error facet or an Icon instance
See Also:
getErrorIcon(Theme, FacesContext, String)

getErrorIcon

public javax.faces.component.UIComponent getErrorIcon(Theme theme,
                                                      javax.faces.context.FacesContext context,
                                                      java.lang.String toolTipErrorMsg)
Return a component that implements an error icon. If a facet named 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.

Returns:
- error facet or an Icon instance

getElement

public java.lang.String getElement()
Deprecated. 

Return span if the label is not labeling another component, else return label. The deprecated behavior always returns label.


getLabeledElementId

public java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
Return an id suitable for the HTML label element's "for" attribute. Call 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().

Parameters:
context - The faces context
Returns:
An id suitable for the HTML label element's "for" attribute.

getLabeledComponent

public 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).

Returns:
the labeled component instance or null

getLabelLevel

public int getLabelLevel()
Return the label level. If the label level is less than 1 or greater than 3, 2 is returned.


getValueExpression

public javax.el.ValueExpression getValueExpression(java.lang.String name)

Return the ValueExpression stored for the specified name (if any), respecting any property aliases.

Overrides:
getValueExpression in class javax.faces.component.UIComponentBase
Parameters:
name - Name of value binding expression to retrieve

setValueExpression

public void setValueExpression(java.lang.String name,
                               javax.el.ValueExpression binding)

Set the ValueExpression stored for the specified name (if any), respecting any property aliases.

Overrides:
setValueExpression in class javax.faces.component.UIComponentBase
Parameters:
name - Name of value binding to set
binding - ValueExpression to set, or null to remove

getValue

public java.lang.Object getValue()
Specified by:
getValue in interface javax.faces.component.ValueHolder
Overrides:
getValue in class javax.faces.component.UIOutput

getFor

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.


setFor

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.


isHideIndicators

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.


setHideIndicators

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.

See Also:
isHideIndicators()

getHtmlTemplate

public java.lang.String getHtmlTemplate()
Get alternative HTML template to be used by this component.


setHtmlTemplate

public void setHtmlTemplate(java.lang.String htmlTemplate)
Set alternative HTML template to be used by this component.


_getLabelLevel

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.


setLabelLevel

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.

See Also:
getLabelLevel()

getOnClick

public java.lang.String getOnClick()

Scripting code executed when a mouse click occurs over this component.


setOnClick

public void setOnClick(java.lang.String onClick)

Scripting code executed when a mouse click occurs over this component.

See Also:
getOnClick()

getOnMouseDown

public java.lang.String getOnMouseDown()

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.


setOnMouseDown

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.

See Also:
getOnMouseDown()

getOnMouseMove

public java.lang.String getOnMouseMove()

Scripting code executed when the user moves the mouse pointer while over the component.


setOnMouseMove

public void setOnMouseMove(java.lang.String onMouseMove)

Scripting code executed when the user moves the mouse pointer while over the component.

See Also:
getOnMouseMove()

getOnMouseOut

public java.lang.String getOnMouseOut()

Scripting code executed when a mouse out movement occurs over this component.


setOnMouseOut

public void setOnMouseOut(java.lang.String onMouseOut)

Scripting code executed when a mouse out movement occurs over this component.

See Also:
getOnMouseOut()

getOnMouseOver

public java.lang.String getOnMouseOver()

Scripting code executed when the user moves the mouse pointer into the boundary of this component.


setOnMouseOver

public void setOnMouseOver(java.lang.String onMouseOver)

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

See Also:
getOnMouseOver()

getOnMouseUp

public java.lang.String getOnMouseUp()

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.


setOnMouseUp

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.

See Also:
getOnMouseUp()

isRequiredIndicator

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.


setRequiredIndicator

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.

See Also:
isRequiredIndicator()

getStyle

public java.lang.String getStyle()

CSS style(s) to be applied to the outermost HTML element when this component is rendered.


setStyle

public void setStyle(java.lang.String style)

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

See Also:
getStyle()

getStyleClass

public java.lang.String getStyleClass()

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.


setStyleClass

public void setStyleClass(java.lang.String styleClass)

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

See Also:
getStyleClass()

getText

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.


setText

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.

See Also:
getText()

getToolTip

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.


setToolTip

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.

See Also:
getToolTip()

isVisible

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.


setVisible

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.

See Also:
isVisible()

getIndicatorComponent

public javax.faces.component.UIComponent getIndicatorComponent()
Return the indicatorComponent property.


getIndicatorComponent

public 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. If 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.


setIndicatorComponent

public 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. It is mainly used by components that have built in labels as sub components. This method must be called whenever a component wants to return its built in label instance, since the underlying member that stores the instance reference is transient.

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.


restoreState

public void restoreState(javax.faces.context.FacesContext _context,
                         java.lang.Object _state)

Restore the state of this component.

Specified by:
restoreState in interface javax.faces.component.StateHolder
Overrides:
restoreState in class javax.faces.component.UIOutput

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext _context)

Save the state of this component.

Specified by:
saveState in interface javax.faces.component.StateHolder
Overrides:
saveState in class javax.faces.component.UIOutput


Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.